中国工商银行银企互连系统企业开发手册初稿.docx

中国工商银行银企互连系统企业开发手册初稿.docx

《中国工商银行银企互连系统企业开发手册初稿.docx》由会员分享，可在线阅读，更多相关《中国工商银行银企互连系统企业开发手册初稿.docx（13页珍藏版）》请在冰豆网上搜索。

中国工商银行银企互连系统企业开发手册初稿

第1章概述

银企互联面向大的集团客户，提供与企业ERP系统直连的平台，银企互联面向大的集团客户，提供与企业ERP系统直连的平台，为工行的现金管理服务提供多渠道和客户化支持。

企业ERP系统通过HTTPS协议与工行系统进行连接并向银企互联前置发送数据，数据的接口格式使用标准的xml数据格式，但双方通讯的过程中则需要遵守下文描述的规定。

银企互联前置接到企业数据后进行一系列的检查后完成交易，并将处理结果以企业便于处理的形式返回给企业。

在安全保证方面，通讯层的安全保证是HTTPS协议。

企业如需使用银企互联系统，要办理有关注册手续，并审领证书。

企业进行结算类交易时，如果涉及到授权过程，企业需要在企业网银系统中完成相关授权动作。

银企互连系统将企业提交的支付指令或者授权成功后的指令当作最终转账指令，根据提交指令的证书ID检查收付方帐号等合法性，以保证所提交指令在权限允许范围内进行操作。

第2章总体方案介绍

2.1总体网络结构图

上图企业ERP系统1采用的是非NC方式接入的客户；企业ERP系统2采用的是NC方式接入的客户；

2.2企业端安全服务器简介

此服务器只对使用NC方式接入的客户有效。

企业端安全服务器被称为NetSafeClient。

它有两个可以配置的端口分别用于加密和签名／验签服务，如下图所示（假设１为加密端口，２为签名／验签端口）。

具体使用时，企业应用向工行提交交易请求时，可以依照http协议向NetSafeClient的端口１发送请求。

接到请求后，NetSafeClient使用企业证书将http请求包转换成https请求包发往工行端服务器；如果需要对某些交易数据进行签名，则企业应用需要与签名端口建立Socket连接并将待签名数据发往端口２，然后接收端口２的签名结果，之后再将包含签名信息的交易请求发往端口１而完成整个交易请求过程。

对签名还是验签名请求的区分则是通过http包头来进行。

Content-Type:

INFOSEC_SIGN/1.0和Content-Type:

INFOSEC_VERIFY_SIGN/1.0分别用于标识签名请求和验签名请求，而Content-Type:

INFOSEC_SIGN_RESULT/1.0和Content-Type:

INFOSEC_VERIFY_SIGN_RESULT/1.0分别用于标识签名和验签名的返回结果。

为方便起见，可以将NetSafeClient的两个服务端口逻辑地称为两台服务器，NetSafeClient的加密服务器和签名服务器。

2.3安全控制介绍

对于NC方式接入的客户

✓企业向工行提交的交易数据，必须通过企业方的NetSafeClient进行与工行服务器的连接，接口确定需要签名的数据也必须由NetSafeClient的签名服务器签名后组成规定的数据包格式后，通过NetSafeClient提交工行，这样可以保证企业数据以及相关信息不被恶意篡改。

✓数据全部由NetSafeClient负责转发，使NetSafeClient成为架设在企业现场的工行接入服务器。

而企业与工行之间安全的连接，由NetSafeClient和工行安全代理服务器NetSafe保证；

✓工行接收到企业提交过来的部分关键交易数据后，需要解密并验证企业的数字签名，以防止第三方假冒企业的行为。

对于非NC方式接入的客户

✓企业向工行提交交易数据时的安全控制

企业ERP与银企互连系统之间使用HTTPS协议通讯。

企业可以选择是否对交易数据进行对称加密，目前系统支持的算法有DES与3DES。

进行对称加密可以防止第三方截获交易的信息。

而加密中需要用到的密钥由企业与工行共同约定。

（加密功能暂不支持）

企业需要对其发送的指令数据进行数字签名，签名中使用的证书可以是企业证书也可以是工行证书，其中签名使用的算法是SHA1withRSA。

进行数字签名可以防止第三方假冒企业的行为。

✓工行向企业发送结果信息时的安全控制

企业ERP与银企互连系统之间使用HTTPS协议通讯。

企业可选择是否对返回数据进行对称加密，方法与上文相同。

工行对部分关键交易返回信息进行数字签名。

第3章重点说明

Ø所有的交易请求包中“包序列ID”字段（PackageID）由企业产生，产生规则为当前日期（北京时间，格式为yyyyMMdd）＋7位序列号（例如200212230000001，为2002年12月23日发送的一个交易请求包的包序列ID）。

在一个企业代码下当日包序列ID必须唯一。

工行处理完毕之后将该字段原值返回，即所有的交易返回包中“包序列ID”字段（PackageID）。

Ø转帐交易请求包中“签名时间”字段（SignTime），格式为yyyyMMddhhmmssSSS（例如20021223092710568，表示2002年12月23日9点27分10秒568毫秒）。

签名时间应为北京时间。

签名时间如果与交易请求到达工行服务器时的北京标准时间误差过大（暂定为15分钟），交易将无法进行。

此措施将可以有效地防止黑客采用重放攻击进行干扰帐务活动的行为。

同一笔交易如果因为网络不正常等因素需要重新提交时，要修改转账交易请求包的“签名时间字段”并重新签名。

Ø所有请求包和返回包中备用字段的使用主要是出于对今后扩展的考虑，如果以后需要增加企业上送的项目或者返回给企业的信息，不必再改变交易包格式。

目前对企业请求包来说这些备用字段的值可以送空；企业对银行返回包中的备用字段也不必作处理。

请求包中的备用字段标签为“ReqReserved*”，返回包中的备用字段标签为“RepReserved*”（其中*为1、2、3或4，详见接口说明文档）。

Ø查询历史明细返回数据包中交易时间（）数值如为空，则说明该笔指令是银行的计息交易明细。

Ø支付查询指令接口，方便企业对可疑、有疑问（如网络中断，交易长时间没有返回等）或处理完毕的转帐指令进行查询。

企业提交要查询的结算请求的包序列ID，工行返回该笔转帐指令的基本信息和状态。

Ø本接口说明中所有涉及金额的字段都是以分为单位（不带小数点）。

Ø如企业系统需要代理汇兑功能则企业应用需同步开发网点信息下载交易，以便为代理汇兑交易中收方为它行情况时提供工行网点名称。

否则，无需开发网点信息下载交易。

Ø在网点信息下载功能中，由于下载数据过大且数据不会经常更新，所以此交易控制了企业每日下载次数。

目前暂定次数为每日2次。

Ø个人联名卡签权指令只支持币种是人民币的账号/卡号。

Ø企业端传输数据时，指定xml编码方式为GB2312。

Ø银企互联提交包中包含“签名时间（yyyyMMddhhmmssSSS）”此标签的，说明该交易需要进行签名处理。

Ø企业端的程序需要对银行返回的数据有可扩展性，以便适应今后业务的不断发展。

Ø银企互连系统支持两种接入方式，客户可以任何选择一种。

第一种：

使用第三方NC软件方式接入银企互连系统；第二种：

使用非NC方式企业直接接入银企互连系统；

下面将区分两类客户分别对接入方式等相关信息进行说明。

第4章银企互联——NC方式接入客户

4.1企业端系统环境要求

4.1.1软件环境

对企业的ERP系统无要求；

工行企业端证书服务器软件NetSafeClient需安装在一台PC机上。

4.1.2网络环境

企业财务系统通过局域网与工商银行提供的NetSafeClient连接；

企业端的NetSafeClient可以通过专线或INTERNET与中国工商银行银企互连系统互联。

4.1.3企业开发过程描述

4.1.3.1企业提交交易请求数据过程

企业提交的交易分为两大类：

查询类和结算类（需要进行签名处理）。

1、查询类：

（1）企业按照工行提供的xml包格式进行打包，在局域网内通过http协议以POST方式将交易包发送到NetSafeClient的安全http协议服务器。

http请求格式：

action=”http:

//客户端NetSafeClient的地址和加密端口号/servlet/ICBCCMPAPIReqServlet?

userID=证书ID&PackageID=包序列ID&SendTime=请求时间”

请求数据格式（post方式）：

Version=版本号（区分版本时间，暂定0.0.0.1）&TransCode=交易代码（区分交易类型，每个交易固定）&BankCode=客户的归属单位&GroupCIS=客户的归属编码&ID=客户的证书ID（无证书客户可空）&PackageID=客户的指令包序列号（由客户ERP系统产生，不可重复）&Cert=客户的证书公钥信息（进行BASE64编码；NC客户送空）&reqData=客户的xml请求数据

其中：

包序列ID、证书ID应根据实际情况进行更改，请求时间为企业发出该交易请求包的当前系统时间。

post方式最后不允许有回车等其他乱字符，TransCode交易名称应与xml包内标签中的值一致，action中的证书ID、PackageID与请求数据格式中的证书ID、PackageID、xml包中的证书ID、PackageID的值三者相一致。

（2）NetSafeClient将xml包加密后按照https协议，通过互联网/专线发送到银行端的NetSafeServer。

（本步由NetSafeClient完成，企业无需处理）；

（3）NetSafeServer将交易请求送银企互连系统进行处理。

2、结算类：

（1）企业按照工行提供的xml包格式进行打包，在局域网内与NetSafeClient的签名端口建立Socket连接，通过此连接向签名端口发送http数据包。

http包头中需包含“Content-Length”和“Content-Type”两个属性。

其中“Content-Length:

”后面是需要签名的二进制数据包的长度，“Content-Type:

”后面是需要签名的标记，为INFOSEC_SIGN/1.0。

（注意大小写）

http请求格式：

action=”http:

//客户端NetSafeClient的地址和签名端口号”

请求数据格式：

结算类请求提交的xml包

NetSafeClient对xml包进行签名后，通过http协议将签名结果返回给企业系统。

如签名成功标签与标签之间的部分为签名结果。

NetSafeClient返回的签名包如下：

0

MIIIXAYJKovcNAQcCo………….0BlLdSgw=

（2）企业按照工行提供的xml包格式进行打包，在局域网内通过http协议以POST方式将交易包发送到NetSafeClient的安全http协议服务器。

http请求格式：

action=”http:

//客户端NetSafeClient的地址和加密端口号/servlet/ICBCCMPAPIReqServlet?

userID=证书ID&PackageID=包序列ID&SendTime=请求时间”

请求数据格式（post方式）：

Version=版本号（区分版本时间，暂定0.0.0.1）&TransCode=交易代码（区分交易类型，每个交易固定）&BankCode=客户的归属单位&GroupCIS=客户的归属编码&ID=客户的证书ID（无证书客户可空）&PackageID=客户的指令包序列号（由客户ERP系统产生，不可重复）&Cert=客户的证书公钥信息（进行BASE64编码；NC客户送空）&reqData=客户的xml请求数据

其中：

包序列ID、证书ID应根据实际情况进行更改，请求时间为企业发出该交易请求包的当前系统时间。

post方式最后不允许有回车等其他乱字符，TransCode交易名称应与xml包内标签中的值一致，action中的证书ID、PackageID与请求数据格式中的证书ID、PackageID、xml包中的证书ID、PackageID的值三者相一致。

（3）NetSafeClient将企业送来的签名包加密后按照https协议，通过互联网/专线发送到工行端的NetSafeServer，再发往工行网银进行处理。

（本步由NetSafeClient完成，企业无需处理）。

4.1.3.2企业接收交易响应数据过程

企业接收到数据包的格式：

reqData=交易返回包或errorCode=错误代码

步骤：

判断返回数据中是否是errorCode：

（1）如果是：

根据错误代码做相应处理，结束。

错误代码的含义参见接口说明文档中的附录。

（2）如果否：

企业接收到数据包的格式：

reqData=交易结果包；企业根据先进行BASE64解码，签名返回包按照格式拆分出明文和密文，验签正确后对明文按工行提供的xml包格式进行解包。

对于单笔提交类指令（即存在文件级返回包的指令），返回的xml包格式按照指令级返回包格式来处理，多笔则按照文件级返回包格式来处理。

4.1.3.3企业接收银行主动返回过程

http请求格式：

action=”http:

//客户ERP服务器的地址和端口号”

请求数据格式（post方式）：

Version=版本号（区分版本时间，暂定0.0.0.1）&TransCode=交易代码（区分交易类型，每个交易固定）&BankCode=客户的归属单位&GroupCIS=客户的归属编码&ID=客户的证书ID（无证书客户可空）&PackageID=客户的指令包序列号（由客户ERP系统产生，不可重复）&Cert=客户的证书公钥信息（进行BASE64编码；NC客户送空）&reqData=客户的xml请求数据

reqData数据格式：

如果需要签名，格式为：

数字字符串：

长度10位，代表明文数据长度，不足10位左补0；

明文：

xml明文，长度可变，需要上面的数据指明，双字节字符（汉字）算作1位长度；

分隔符：

ICBCCMP；

密文：

明文经过签名后的数据并做BASE64编码；

如果不需要签名，则直接送xml明文；

以上数据经过拼接后，再进行BASE64编码（仅reqData项）、URLEncode编码（全部参数项）得到最终的reqData数据。

按照以上格式将请求数据发送到企业；

第5章银企互联——非NC方式接入客户

5.1企业端系统环境要求

5.1.1软件环境

对企业的ERP系统无要求；

5.1.2网络环境

企业财务系统可以通过专线与中国工商银行银企互连系统互联。

5.1.3企业开发过程描述

5.1.3.1企业提交交易请求数据过程

（1）企业按照工行提供的xml包格式进行打包，在局域网内通过http协议以POST方式将交易包发送到NetSafeClient的安全http协议服务器。

http请求格式：

action=”http:

//客户端NetSafeClient的地址和加密端口号/servlet/ICBCCMPAPIReqServlet?

userID=证书ID&PackageID=包序列ID&SendTime=请求时间”

请求数据格式（post方式）：

Version=版本号（区分版本时间，暂定0.0.0.1）&TransCode=交易代码（区分交易类型，每个交易固定）&BankCode=客户的归属单位&GroupCIS=客户的归属编码&ID=客户的证书ID（无证书客户可空）&PackageID=客户的指令包序列号（由客户ERP系统产生，不可重复）&Cert=客户的证书公钥信息（进行BASE64编码；NC客户送空）&reqData=客户的xml请求数据

其中：

包序列ID、证书ID应根据实际情况进行更改，请求时间为企业发出该交易请求包的当前系统时间。

post方式最后不允许有回车等其他乱字符，TransCode交易名称应与xml包内标签中的值一致，action中的证书ID、PackageID与请求数据格式中的证书ID、PackageID、xml包中的证书ID、PackageID的值三者相一致。

reqData数据格式：

如果需要签名：

数字字符串：

长度10位，代表明文数据长度，不足10位左补0；

明文：

xml明文，长度可变，需要上面的数据指明，双字节字符（汉字）算作1位长度；

分隔符：

ICBCCMP；

密文：

明文经过签名后的数据并做BASE64编码；

如果不需要签名，则直接送xml明文；

以上数据经过拼接后，再进行BASE64编码得到最终的reqData数据。

按照以上格式将请求数据发送到工行；

5.1.3.2企业接收交易响应数据过程

企业接收到数据包的格式：

reqData=交易返回包或errorCode=错误代码

reqData=交易返回包结构：

如果交易返回包进行了签名，则结构为：

数字字符串：

长度10位，代表明文数据长度，不足10位左补0；

明文：

长度可变，需要上面的数据指明，双字节字符（汉字）算作1位长度；

分隔符：

ICBCCMP；

密文：

明文经过签名后的数据；

如果交易返回包没有签名，则结构为：

明文；

不论是否签名，交易返回包均进行了BASE64编码；

步骤：

判断返回数据中是否是“errorCode=”打头：

（1）如果是：

根据错误代码做相应处理，结束。

错误代码的含义参见接口说明文档中的附录。

（2）如果否：

企业接收到数据包的格式：

reqData=交易结果包

企业根据先进行BASE64解码，签名返回包按照格式拆分出明文和密文，验签正确后对明文按工行提供的xml包格式进行解包。

对于单笔提交类指令（即存在文件级返回包的指令），返回的xml包格式按照指令级返回包格式来处理，多笔则按照文件级返回包格式来处理。

5.1.3.3企业接收银行主动返回过程

http请求格式：

action=”http:

//客户ERP服务器的地址和端口号”

请求数据格式（post方式）：

Version=版本号（区分版本时间，暂定0.0.0.1）&TransCode=交易代码（区分交易类型，每个交易固定）&BankCode=客户的归属单位&GroupCIS=客户的归属编码&ID=客户的证书ID（无证书客户可空）&PackageID=客户的指令包序列号（由客户ERP系统产生，不可重复）&Cert=客户的证书公钥信息（进行BASE64编码；NC客户送空）&reqData=客户的xml请求数据

reqData数据格式：

如果需要签名，格式为：

数字字符串：

长度10位，代表明文数据长度，不足10位左补0；

明文：

xml明文，长度可变，需要上面的数据指明，双字节字符（汉字）算作1位长度；

分隔符：

ICBCCMP；

密文：

明文经过签名后的数据并做BASE64编码；

如果不需要签名，则直接送xml明文；

以上数据经过拼接后，再进行BASE64编码（仅reqData项）、URLEncode编码（全部参数项）得到最终的reqData数据。

按照以上格式将请求数据发送到企业；

企业签名验签过程

在银企互联中，对于指令体的签名与验签工作由纯java版工行签名验签接口完成的。

本文档对在专业版银企互联中使用的接口作出描述。

同时提供了一套纯java版的从企业发送指令到工行系统和从工行系统接收处理结果的例子程序。

从企业发送指令到工行系统的例子中包括了两方面的内容：

用企业的数据层私钥对数据进行签名，然后用工行的通讯层公钥进行通讯认证；从工行系统接收处理结果的例子中包括了两方面的内容：

用企业的通讯层私钥要求通讯认证，然后用工行的数据层公钥进行数据的验签。

企业签名验签方法总体介绍

接口包含icbc.jar、InfosecCrypto_Java1_02_JDK14.jar、org.mortbay.jetty.jar、tools.jar四个文件，使用时需要把这四个文件放置到java的classpath目录中。

该接口建议的JDK版本为1.4.2。

（不要使用JDK1.5版本或者比1.4更低版本）

接口使用的详细说明

Sign（对原始数据进行数字签名的函数）

publicstaticbyte[]sign（byte[] src,

intlen,

byte[] privateKey,

char[] keyPass）

Description用rsa算法对一段消息签名

Parameters:

privateKey-为口令保护的私钥

src-为待签名消息

len-为待签名消息的长度

keyPass-为私钥保护口令

Returns:

如果成功返回签名结果,如果失败返回null

Throws:

NoSuchProviderException-

NoSuchAlgorithmException-

InvalidKeyException-

SignatureException-

verifySign（对数字签名进行验签的函数）

publicstaticintverifySign（byte[] src,

intlen,

byte[] cert,

byte[] sign）

Description用rsa算法对一段签名进行验证

Parameters:

cert-为证书

src-为被签名的消息

len-为被签名消息的长度

sign-为签名的结果

Returns:

如果成功返回0,如果其它则失败

Throws:

SignatureException-

NoSuchAlgorithmException-

InvalidKeyException-

附件说明

1．ceshizhang.cer，ceshizhang.key是一套客户证书的公钥与私钥，保护口令是12345678。

2．Test.java是一个演示各个接口使用方式的测试程序。

3．APIforZHEJIANG.rar指导企业开发的例子程序；《使用说明》例子的使用说明。

4．附件如下

5.1.3.4https服务器建立开发支持

请参考上面附件中APIforZHEJIANG.rar\APIforZHEJIANG\icbc\api\server.java开发。

《使用说明》文档介绍了开发方法。

5.1.3.5Base64编解码方法参考

/**

*base64解码

*@params

*@return

*/

publicstaticStringgetstrFromBASE64（Strings）{

if（s==null）

returnnull;

sun.misc.BASE64Decoderdecoder=newsun.misc.BASE64Decoder（）;

try{

byte[]b=decoder.decodeBuffer（s）;

returnnewString（b）;

}catch（Exceptione）{

returnnull;

}