DB35∕T 1960-2021 单一窗口进出口信用证服务系统接口技术要求

ICS35.240.30CCSA8035DB35/T1960—2021单一窗口进出口信用证服务系统接口技术要求Thetechnicalrequirementofinterfaceforimportandexportcreditservicesystemofsinglewindow2021-02-09发布2021-05-09实施福建省市场监督管理局发布IDB35/T1960—2021前言 12规范性引用文件 13术语和定义 14缩略语 25基本要求 26主要数据项 27数据交换方式 48接口调用方式 49报文头 410接口信息描述 5附录A（规范性）数据字典 6附录B（资料性）接口信息描述 8附录C（规范性）银行代码 附录D（资料性）接口调用示例（以Java代码为例） 附录E（资料性）接口报文示例（JSON） 参考文献 DB35/T1960—2021本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。本文件由福建省商务厅提出并归口。本文件起草单位：福建省电子口岸管理中心、福建省标准化研究院、福建天础信息科技有限公司、福建省标院信息技术有限公司。本文件主要起草人：张晶、蒋乐超、柴勇、孙琳、李海晏、康雪娟、程军、王彬彬、程晓明、洪文木、林晓銮、王姝敏、刘荣荣。DB35/T1960—20211单一窗口进出口信用证服务系统接口技术要求本文件规定了单一窗口进出口信用证服务系统接口的缩略语、基本要求、主要数据项、数据交换方式、接口调用方式、报文头和接口信息描述。本文件适用于单一窗口进出口信用证服务系统与银行信用证业务系统的数据交换，其他需要与单一窗口进出口信用证服务系统对接的业务系统可参照执行。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T2659世界各国和地区名称代码GB/T11457信息技术软件工程术语GB/T12406表示货币和资金的代码GB/T16711银行业银行电信报文银行标识代码GB32100法人和其他组织统一社会信用代码编码规则JR/T0014—2005银行信息化通用代码集IETFRFC7231HypertextTransferProtocol(HTTP/1.1):SemanticsandContent3术语和定义GB/T11457界定的术语和定义适用于本文件。3.1单一窗口singlewindow贸易和运输相关各方在单一登记点提交满足全部进口、出口和转口相关监管规定的标准信息和单证[来源：GB/T36597—2018，2.1]3.2信用证credit一项约定，无论其如何命名或描述，该约定不可撤销并因此构成开证行对于相符交单予以兑付的确[来源：ICCUCP600中英文对照版，第二条定义]3.3订单order平台上用户通过单一窗口进出口信用证服务系统向商业银行发起的交易请求。2DB35/T1960—20214缩略语下列缩略语适用于本文件。AES：高级加密标准（AdvancedEncryptionStandard）API：应用程序编程接口（ApplicationProgrammingInterface）CA：证书认证机构（CertificateAuthority）CBC：密文分组链接（CipherBlockChaining）HTTP：超文本传输协议（HypertextTransferProtocol）HTTPS：超文本传输安全协议（HypertextTransferProtocoloverSecureSocketLayer）IETF：国际互联网工程任务组（TheInternetEngineeringTaskForce）IP：互联网协议（InternetProtocol）JSON：JavaScript对象标记（JavaScriptObjectNotation）PKCS：公钥加密标准（PublicKeyCryptographyStandards）RFC：请求评论（RequestForComments）SHA：安全散列算法（SecureHashAlgorithm）URI：统一资源标识符（UniformResourceIdentifier）5基本要求单一窗口进出口信用证服务系统的接口应能满足以下基本要求：a)实用性：能与不同商业银行进行业务对接、完成数据交换；b)安全性：数据交换过程中保护国家秘密、商业秘密和个人隐私；c)时效性：能实时完成数据交换。6主要数据项接口的主要数据项见表1。表1主要数据项1话—2—3456—78码9息——DB35/T1960—20213表1主要数据项（续）息—————————息—息—DB35/T1960—202147数据交换方式7.1数据对接方式对接方式包括但不限于：a)专线+HTTP；b)HTTPS+CA证书。7.2数据加密方式数据加密方式包括但不限于：a)SM2椭圆曲线公钥密码算法；b)RSA算法。8接口调用方式8.1请求8.1.1接口调用地址：a)专线+HTTP：http://IP地址/银行代码/附录B中的URI，常见的银行代码应符合附录C的要b)HTTPS+CA证书：https://IP地址/银行代码/附录B中的URI。8.1.2请求方法为post，接口调用示例参见附录D。8.2返回8.2.1返回报文体格式为JSON。8.2.2交易成功时，返回信息见附录B中的输出数据项；交易失败时，返回信息为返回状态码和返回状态码描述。8.2.3HTTP返回状态码描述详见IETFRFC7231规范定义。9报文头9.1报文头参数报文头参数见表2。表2报文头参数1—29.2签名方式9.2.1客户端签名：a)输入：content（请求报文体）、secret（密钥）；DB35/T1960—20215b)输出：signature（签名）。9.2.2签名过程要求：a)content至少经过两次不同加密算法加密处理；b)最终生成的signature需要转Base64编码输出。9.2.3调用signBytes方法时采用JSON字符串，调用API时请求报文体格式为JSON。10接口信息描述10.1接口信息描述包括但不限于以下内容：a)接口类型；b)URI；d)输入数据项；e)输出数据项；1)查询字符串（描述资源的键/值对）；2)消息体（描述HTTP请求的消息体）；3)返回结果（描述HTTP请求的响应）。10.2接口信息描述参见附录B，接口报文示例参见附录E。DB35/T1960—20216数据字典数据字典见表A.1～表A.6。表A.1会员账户状态代码1122334455667789表A.2订单状态代码1234567表A.3订单类型代码1122表A.4信用证状态代码1234DB35/T1960—20217表A.4信用证状态代码（续）5678表A.5批量查询申请状态代码1122表A.6返回状态码1234DB35/T1960—20218接口信息描述接口信息描述见表B.1。表B.1接口信息描述接口类型查询字符串消息体返回结果会员台账接口新增建立商户会员台账，只建立会员台账，不绑定银行实平台会员联系电话*、平台会员联系人平台会员地址*、平台会员编号*、平台会员状态*、统一社会信用代码*、交易流水号、返回状态码*、返回状态码描述修改对部分会员信息进行修改，可修改字段为：平台会员名平台会员联系电话、平台会员联系人、平台会员名称、平台会员删除删除会员台账，不删除数据记录，只将会员标志置为“2-销户”查询查询已建立的会员订单信息接口新增申请人国别名称、申请人国别代DB35/T1960—20219表B.1接口信息描述（续）接口类型查询字符串消息体返回结果订单信息接口修改修改订单状态，或者修改订单中部分统一社会信用代码*、商币种、订单号*、修改后受益人银行BICNO.、受益人银行名称、受益人国别名称、受益人国别银行BICNO.、开证银行删除撤销登记过的订单,撤销成功后无法进行各类业务场景平台会员编号*、统一社DB35/T1960—2021表B.1接口信息描述（续）接口类型查询字符串消息体返回结果订单信息接口查询会员已登记台会员编号、平台会员实账号、统一社会信用代码、商受益人账号、受益益人银行名称、受益人国别名称、受益人国别代码、受益人名称、开证银行名称、申请人国别名称、申请人国别代码、申请人名称、交易流水号、DB35/T1960—2021表B.1接口信息描述（续）接口类型查询字符串消息体返回结果信用证查询接口询—统一社会信用代平台会员编号、统一社会信用代交易币种*、信用证金额*、信用证查询结果总数量*、返回状态码*、l—交易流水号、信用证记录信息、订单号、实际交易金额*、实际交易信用证状态*、通知编号、申请状态*、查询结果总数量、返回状态DB35/T1960—2021银行代码银行代码采用GB/T16711中规定的“银行标识代码”的前四位“银行代码”，即SwiftCode中前四位“银行代码”。表C.1列出了常见的银行代码。表C.1常见的银行代码123456789DB35/T1960—2021接口调用示例（以Java代码为例）D.1JSON报文转换工具类/***@descriptionJSON报文转换工具类*/publicclassJsonUtil{privatestaticMap<String,Object>config=newHashMap<String,Object>();/***@description将对象转换成JSON报文*@paramobj被转换的对象*@returnstringJSON报文*/publicstaticStringParseObject(Objectobj){}/***@description将JSON字符串转换成JsonObject*@paramjsonStr待转换的JSON字符串*@returnJsonObject*@throwsUnsupportedEncodingException*/publicstaticJsonObject<String,Object>ParseJson(StringjsonStr)throwsUnsupportedEncodingException{JsonObject<String,Object>jo=newJsonObject<>();;DB35/T1960—2021InputStreamba=newByteArrayInputStream(jsonStr.getBytes("UTF-8"));returnjo;}}D.2加密签名类/***@description加密签名类*/publicclassCryptoSample{/***@description获取报文摘要*@paramalgorithm密钥*@parambytes请求报文体*@returnbyte[]摘要*/privatestaticbyte[]digestBytes(Stringalgorithm,byte[]bytes){MessageDigestmessageDigest=MessageDigest.getInstance(algorithm);messageDigest.update(bytes);returnmessageDigest.digest();e.printStackTrace();}}/***@description报文加密，并经Base64编码*@paramcipherAlgorithm算法/模式/补码方式*@paramkeyBytes密钥摘要DB35/T1960—2021*@paramkeyAlgorithm加密算法名称*@paramcontentDigest报文摘要*@returnString加密并编码后的字符串*/privatestaticStringencrypt(StringcipherAlgorithm,byte[]keyBytes,StringkeyAlgorithm,StringcontentDigest){Ciphercipher=Cipher.getInstance(cipherAlgorithm);SecretKeySpeckeySpec=newSecretKeySpec(keyBytes,keyAlgorithm);Long.toHexString(UUID.randomUID().getLeastSignificantBits()).getBytes();IvParameterSpecivParamSpec=newIvParameterSpec(iv);cipher.init(Cipher.ENCRYPT_MODE,keySpec,ivParamSpec);byte[]encyptedBytes=cipher.doFinal(contentDigest.getBytes());byte[]resultBytes=newbyte[encyptedBytes.length+16];System.arraycopy(encyptedBytes,0,resultBytes,16,encyptedBytes.length);returnDatatypeConverter.printBase64Binary(resultBytes);e.printStackTrace();}}/***@description报文签名*@paramcontent请求报文体*@paramsecret密钥*@returnstring签名后的字符串*/publicstaticStringsignBytes(byte[]content,byte[]secret){DB35/T1960—2021StringcontentDigest=DatatypeConverter.printBase64Binary(content));byte[]keyDigestBytes=digestBytes("SHA-256",secret);byte[]keyBytes=newbyte[16];System.arraycopy(keyDigestBytes,0,keyBytes,0,16);StringcipherAlgorithm="AES/CBC/PKCS5Padding";StringkeyAlgorithm="AES";returnencrypt(cipherAlgorithm,keyBytes,keyAlgorithm,contentDigest);}}D.3HTTP工具类/***@descriptionHttp工具类*/publicclassHttpClientUtil{/***创建一个自定义的OkHttpClient实例*/privatestaticfinalOkHttpClientclient=newOkHttpClient.Builder().connectionPool(newConnectionPool(500,5,TimeUnit.MINUTES)).connectTimeout(10000,TimeUnit.MILLISECONDS).readTimeout(60000,TimeUnit.MILLISECONDS).build();/***@Description:以JSON格式发送数据的post请求*@paramjsonStrJSON字符串*@paramurl请求地址*@paramclientIdclientId*@paramclientSecret密钥*@return*/DB35/T1960—2021publicstaticStringpostWithJsonMsg(StringjsonStr,Stringurl,StringclientId,StringclientSecret){Stringresult="";MediaTypemediaType=MediaType.parse("application/json;charset=utf-8");RequestBodybody=RequestBody.create(mediaType,jsonStr);Requestrequest=newRequest.Builder().url(url).post(body).addHeader("content-type","application/json;charset=utf-8").addHeader("X-Client-Id",clientId).addHeader("X-SIGNATURE",CryptoSample.signBytes(jsonStr.getBytes(),clientSecret.getBytes())).build();Responseresponse=client.newCall(request).execute();result=newString(response.body().bytes(),"UTF-8");}catch(IOExceptione){e.printStackTrace();}returnresult;}}D.4接口调用/***@description接口调用示例*/publicclassTest{/***会员台账建立接口调用DB35/T1960—2021*@paramargs*/publicstaticvoidmain(String[]args){JsonObjectobj=newJsonObject();obj.put("pltfContactTel",);obj.put("pltfCrspName","张三");obj.put("pltfMemName","福建XXX股份有限公司");obj.put("pltfMemAddr","福建省XX路98号");obj.put("pltfMemId","PM201903272000000004");obj.put("unfSocCrdtNo","9135000012345678G");Stringurl=":9093/SPDB/memberStndBkCrt";System.out.println(JsonUtil.ParseStringresult=HttpClientUtil.postWithJsonMsg(JsonUtil.ParseObject(obj),url,"d83fa07c-0b7f-40e5-b53a-8c21f3c0437f","nS6uP3oO5wK4dY8uX4aN0tT7hH6rU8jU7oW6aE7aI6iV6qO4qD");System.out.println(result);}}DB35/T1960—2021接口报文示例（JSON）E.1会员台账接口E.1.1新增E.1.1.1输入报文示例{"pltfContactTel":,"pltfCrspName":"张三","pltfMemName":"福建XXX股份有限公司","pltfMemAddr":"福建省XX路98号","pltfMemId":"PM201803272000000004","unfSocCrdtNo":"9135000012345678G"}E.1.1.2输出报文示例{"pltfContactTel":,"pltfCrspName":"张XX","pltfMemName":"福建XXX有限公司","pltfMemAddr":"福建省XX路98号","pltfMemId":"PM201803272100000021","pltfMemSt":"1","unfSocCrdtNo":"9135000012345678G","transNo":"049718032711910034654561","stCode":"00"}E.1.2修改E.1.2.1输入报文示例{"pltfContactTel":,"pltfCrspName":"张三","pltfMemAddr":"福建省XX路98号","pltfMemId":"PM201803272000000004","unfSocCrdtNo":"9135000012345678G"}E.1.2.2输出报文示例参见E.1.1.2。DB35/T1960—2021E.1.3删除E.1.3.1输入报文示例{"pltfMemId":"PM201803272100000021","unfSocCrdtNo":"9135000012345678G"}E.1.3.2输出报文示例参见E.1.1.2。E.1.4查询输入报文示例参见E.1.3.1，输出报文示例：参见E.1.1.2。E.2订单信息接口E.2.1新增E.2.1.1输入报文示例{"pltfMemName":"福建XXX有限公司有限公司","pltfMemId":"PM201803272100000021","pltfMemRlAcct":"4301XXXXXXXXXXX1457","unfSocCrdtNo":"9135000012345678G","ordrAmt":"2124416.18","ordrCcy":"USD","ordrNo":"EO201803272200000001","ordrTp":"2","crCtfNo":"ILC761230405"}E.2.1.2输出报文示例{"pltfMemId":"PM201803272100000006","unfSocCrdtNo":"9135000012345678G","ordrDtTm":"2019-04-1218:10:09","ordrNo":"EO201803272200000001","ordrSt":"21","transNo":"04971804121200610097426655","stCode":"00"}E.2.2修改E.2.2.1输入报文示例DB35/T1960—2021{"pltfMemId":"PM201803272100000021","pltfMemRlAcct":"4301XXXXXXXXXXX1457","unfSocCrdtNo":"9135000012345678G","ordrNo":"EO201803272200000001","udtAftrOrdrSt":"22","crCtfNo":"ILC761230405"}E.2.2.2输出报文示例{"pltfMemName":"福建XXX有限公司有限公司","pltfMemId":"PM201803272100000021","pltfMemRlAcct":"4301XXXXXXXXXXX1457","ordrAmt":"2124416.18","ordrCcy":"USD","ordrDtTm":"2019-04-1218:10:09","ordrNo":"EO201803272200000001","ordrSt":"22","ordrTp":"2","transNo":"04971804121200610097426655","crCtfNo":"ILC761230405","issuBBIC":"MHCBJPJT","issuBName":"MIZUHOBANK,LTD.TOKYO","applCName":"RepublicofCuba","applCty":"CUB","applName":"LIDLHONGKONGLIMITED","stCode":"00"}E.2.3查询E.2.3.1输入报文示例{"pltfMemId":"PM201803272100000006","unfSocCrdtNo":"9135000012345678G","ordrNo":"EO201803272200000001","crCtfNo":"ILC761230405"}E.2.3.2输出报文示例参见E.2.2.2。DB35/T1960—2021E.2.4删除E.2.4.1输入报文示例{"pltfMemId":"PM201803272100000006","unfSocCrdtNo":"9135000012345678G","ordrNo":"EO201803272200000001","crCtfNo":"ILC761230405"}E.2.4.2输出报文示例{"pltfMemId":"PM201803272100000006","unfSocCrdtNo":"9135000012345678G","ordrNo":"EO201803272200000001","ordrSt":"21","transNo":"04971804121200610097426655","stCode":"00"}E.3信用证查询接口E.3.1单笔