中国工商银行银企互联系统企业开发手册

　第 第 1 章

　概述

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

　企业 ERP 系统通过 HTTPS 协议与工行系统进行连接并向银企互联前置发送数据，数据的接口格式使用标准的 xml 数据格式，但双方通讯的过程中则需要遵守下文描述的规定。银企互联前置接到企业数据后进行一系列的检查后完成交易，并将处理结果以企业便于处理的形式返回给企业。

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

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

　企业进行结算类交易时，如果涉及到授权过程，企业需要在企业网银系统中完成相关授权动作。银企互连系统将企业提交的支付指令或者授权成功后的指令当作最终转账指令，根据提交指令的证书 ID 检查收付方帐号等合法性，以保证所提交指令在权限允许范围内进行操作。

　第 第 2 章

　总体方案介绍 2.1 总体网络结构图 Internet/IntranetInternet/Intranet企业ERP系统2银企互联系统NetSafe服务器企业ERP系统1httpsNetSafe Clienthttphttps 上图企业 ERP 系统 1 采用的是非 NC 方式接入的客户；企业 ERP 系统 2 采用的是 NC 方式接入的客户； 2.2 企业端安全服务器简介 此服务器只对使用 NC 方式接入的客户有效。企业端安全服务器被称为 NetSafe Client。

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

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

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

　Content-Type: INFOSEC_SIGN/和 Content-Type: INFOSEC_VERIFY_SIGN/分别用于标识签名请求和验签名 请 求 ， 而 Content-Type: INFOSEC_SIGN_RESULT/ 和 Content-Type: INFOSEC_VERIFY_SIGN_RESULT/分别用于标识签名和验签名的返回结果。

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

　2.3 安全控制介绍 于 对于 NC 方式接入的客户  企业向工行提交的交易数据，必须通过企业方的 NetSafe Client 进行与工行服务器的连接，接口确定需要签名的数据也必须由 NetSafe Client 的签名服务器签名后组成规定的数据包格式后，通过 NetSafe Client 提交工行，这样可以保证企业数据以及相关信息不被恶意篡改。

　 数据全部由 NetSafe Client 负责转发，使 NetSafe Client 成为架设在企业现场的工行接入服务器。而企业与工行之间安全的连接，由 NetSafe Client 和工行安全代1（加密）

　NetSafe Client

　2（签名／验签）

　1. http 交易请求包 https 交易请求包 1.签名／验签请求2.签名／验签结果 2. 交易结果

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

　非 对于非 NC 方式接入的客户  企业向工行提交交易数据时的安全控制

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

　企业可以选择是否对交易数据进行对称加密，目前系统支持的算法有 DES 与3DES。进行对称加密可以防止第三方截获交易的信息。而加密中需要用到的密钥由企业与工行共同约定。（加密功能暂不支持）

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

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

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

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

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

　第 第 3 章

　重点说明  所有的交易请求包中“包序列 ID”字段（PackageID）由企业产生，产生规则为当前日期（北京时间，格式为 yyyyMMdd）＋7 位序列号（例如 2002，为 2002 年 12 月 23日发送的一个交易请求包的包序列 ID）。在一个企业代码下当日包序列 ID 必须唯一。工行处理完毕之后将该字段原值返回，即所有的交易返回包中“包序列 ID”字段（PackageID）。

　 转帐交易请求包中“签名时间”字段（SignTime），格式为 yyyyMMddhhmmssSSS（例如 2002，表示 2002 年 12 月 23 日 9 点 27 分 10 秒 568 毫秒）。签名时间应为北京时间。签名时间如果与交易请求到达工行服务器时的北京标准时间误差过大（暂定为 15 分钟），交易将无法进行。此措施将可以有效地防止黑客采用重放攻击进行干扰帐务活动的行为。同一笔交易如果因为网络不正常等因素需要重新提交时，要修改转账交易请求包的“签名时间字段”并重新签名。

　 所有请求包和返回包中备用字段的使用主要是出于对今后扩展的考虑，如果以后需要增加企业上送的项目或者返回给企业的信息，不必再改变交易包格式。目前对企业请求包来说这些备用字段的值可以送空；企业对银行返回包中的备用字段也不必作处

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

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

　 支付查询指令接口，方便企业对可疑、有疑问（如网络中断，交易长时间没有返回等）或处理完毕的转帐指令进行查询。企业提交要查询的结算请求的包序列 ID，工行返回该笔转帐指令的基本信息和状态。

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

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

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

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

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

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

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

　 银企互连系统支持两种接入方式，客户可以任何选择一种。第一种：使用第三方 NC软件方式接入银企互连系统；第二种：使用非 NC 方式企业直接接入银企互连系统；  一些接口中，返回包分文件级返回包和指令级返回包两种。文件级返回包是作为客户请求的响应信息同步返回的。而指令级返回包是银行主动发起的异步返回信息，表示指令处理的结果，指令级返回包首先会返回整批指令的处理结果，然后对于其中指令状态非最终状态（成功和失败）的指令，银行会实时更新每一条指令的状态，然后再每条分别以指令级返回包的格式返回给客户。

　 建议客户使用 HTTP/协议。HTTP/及其以下协议版本可能无法正常发送指令到银行端。

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

　第 第 4 章

　银企互联 ——C NC 方式接入 客户

　4.1 企业端系统环境要求 4.1.1 软件环境

　对企业的 ERP 系统无要求； 工行企业端证书服务器软件 NetSafe Client 需安装在一台 PC 机上。

　4.1.2 网络环 境

　企业财务系统通过局域网与工商银行提供的 NetSafe Client 连接； 企业端的 NetSafe Client 可以通过专线或 INTERNET 与中国工商银行银企互连系统互联。

　4.1.3 企业开发过程描述

　4.1.3.1 企业提交交易 请求 数据 过程 企业提交的交易分为两大类：查询类和结算类（需要进行签名处理）。

　1 、 查询类：

　（1）

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

　http ：

　请 求 格 式 ：

　action=” Client 的 地 址 和 加 密 端 口 号/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 包 内 标 签<TransCode></TransCode> 中的 值一致 ， action 中 的 证 书 ID 、PackageID 与请求数据格式中的证书 ID、PackageID、xml 包中的证书ID、PackageID 的值三者相一致。

　（2）

　NetSafe Client 将 xml 包加密后按照 https 协议，通过互联网/专线发送到银行端的 NetSafe Server。（本步由 NetSafe Client 完成，企业无需处理）； （3）

　NetSafe Server 将交易请求送银企互连系统进行处理。

　2 、 结算类：

　（1）

　企业按照工行提供的 xml 包格式进行打包，在局域网内与 NetSafe Client 的签名端口建立 Socket 连接，通过此连接向签名端口发送 http数据包。http 包头中需包含“Content-Length”和“Content-Type”两个属性。其中“Content-Length:”后面是需要签名的二进制数据包的长度，“Content-Type:”后面是需要签名的标记，为 INFOSEC_SIGN/。（注意大小写）

　http 请求格式：action=”” 请求数据格式：结算类请求提交的 xml 包 NetSafe Client 对 xml 包进行签名后，通过 http 协议将签名结果返回给企业系统。如签名成功<sign>标签与</sign>标签之间的部分为签名结果。

　NetSafe Client 返回的签名包如下：

　<html> <head> <title>签名结果</title>

　企业 NetSafe Client NetSafe Server （1）

　（2）

　工行 （3）

　<result>0</result> </head> <body> <sign>MIIIXAYJKovcNAQcCo…………. 0BlLdSgw=</sign> </body> </html> （2）

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

　http ：

　请 求 格 式 ：

　action=” Client 的 地 址 和 加 密 端 口 号/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 包 内 标 签<TransCode></TransCode> 中的 值一致 ， action 中 的 证 书 ID 、PackageID 与请求数据格式中的证书 ID、PackageID、xml 包中的证书ID、PackageID 的值三者相一致。

　（3）

　NetSafe Client 将企业送来的签名包加密后按照 https 协议，通过互联网/专线发送到工行端的 NetSafe Server，再发往工行网银进行处理。（本步由 NetSafe Client 完成，企业无需处理）。

　 4.1.3.2 企业接收 交易 响应 数据过程 企业接收到数据包的格式 ：

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

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

　（1）如果是：根据错误代码做相应处理，结束。错误代码的含义参见接口说明文档中的附录。

　（2）如果否：

　企业接收到数据包的格式：reqData=交易结果包；企业根据先进行 BASE64 解码，签名返回包按照格式拆分出明文和密文，验签正确后对明文按工行提供的 xml 包格式进行解包。对于单笔提交类指令（即存在文件级返回包的指令），返回的 xml 包格式按照指令级返回包格式来处理，多笔则按照文件级返回包格式来处理。

　4.1.3.3 企业接收银行主动返回 过程 http 请求格式：action=”

　请求数据格式（post ：

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

　如果需要签名，格式为：

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

　企业

　NetSafe Client

　NetSafe Server （1）

　（2）

　（3）

　（4）

　明文：xml 明文，长度可变，需要上面的数据指明，双字节字符（汉字）算作 1 位长度； 分隔符：ICBCCMP； 密文：明文经过签名后的数据并做 BASE64 编码； 如果不需要签名，则直接送 xml 明文；

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

　按照以上格式将请求数据发送到企业；此格式返回的数据是不经过 NC的，是银行直接发给企业的 ERP 系统；如有使用，企业需要在内管注册或者修改集团信息时填入企业用于接收银行反馈的地址，标准格式是；编解码方式查看 5.1.3.5 第 第 5 章

　银企互联 ——非 非 C NC 方式接入客户

　5.1 企业端系统环境要求 5.1.1 软件环境

　对企业的 ERP 系统无要求； 5.1.2 网络环境

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

　5.1.3 企业开发过程描述

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

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

　http ：

　请 求 格 式 ：

　action=” Client 的 地 址 和 加 密 端 口 号

　/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 包 内 标 签<TransCode></TransCode> 中的 值一致 ， 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=”

　请求数据格式（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 数据。

　按照以上格式将请求数据发送到企业；此格式返回的数据是银行直接发给企业的 ERP 系统；如有使用，企业需要在内管注册或者修改集团信息时填入企业用于接收银行反馈的地址，标准格式是；编解码方式查看 5.1.3.5

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

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

　同时提供了一套纯 java 版的从企业发送指令到工行系统和从工行系统接收处理结果的例子程序。从企业发送指令到工行系统的例子中包括了两方面的内容：用企业的数据层私钥对数据进行签名，然后用工行的通讯层公钥进行通讯认证；从工行系统接收处理结果的例子中包括了两方面的内容：用企业的通讯层私钥要求通讯认证，然后用工行的数据层公钥进行数据的验签。

　使用这种接入方式的客户只能使用磁盘证书；该磁盘证书需要拆分，拆分为一对数据层证书，用于签名验签；一对通讯层证书，用于建立与银行的 https 连接。拆分方法见第 7 章

　 企业签名验签方法 总体介绍 接口包含、、、四个文件，使用时需要把这四个文件放置到 java 的 classpath 目录中。

　该接口建议的 JDK 版本为 1.4.2。（不要使用版本或者比更低版本）

　接口使用的详细说明

　Sign

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

　public static byte[] sign(byte[]?src,

　int len,

　byte[]?privateKey,

　char[]?keyPass) Description 用 rsa 算法对一段消息签名

　Parameters:

　privateKey - 为口令保护的私钥

　src - 为待签名消息

　len - 为待签名消息的长度

　keyPass - 为私钥保护口令

　Returns:

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

　Throws:

　NoSuchProviderException -

　NoSuchAlgorithmException -

　InvalidKeyException -

　SignatureException -

　 verifySign

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

　public static int verifySign(byte[]?src,

　 int len,

　 byte[]?cert,

　 byte[]?sign) Description 用 rsa 算法对一段签名进行验证

　Parameters:

　cert - 为证书

　src - 为被签名的消息

　len - 为被签名消息的长度 sign - 为签名的结果

　Returns:

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

　Throws:

　SignatureException -

　NoSuchAlgorithmException -

　InvalidKeyException -

　 附件说明 1．

　，是一套客户证书的公钥与私钥，保护口令是。

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

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

　4． 附件如下

　5.1.3.4 https 服务器建立 开发支持 请参考上面附件中\APIforZHEJIANG\icbc\api\开发。《使用说明》文档介绍了开发方法。

　5.1.3.5 Base64 编解码方法参考 建议使用 sun 提供的 BASE64 编解码方法实现。

　/**

　* base64解码

　* @param s:需要解码的数据

　* @return 解码后的数据

　*/

　public static String getstrFromBASE64(String s) {

　 if (s == null)

　return null;

　decoder = new

　 try {

　byte[] b = (s);

　return new String(b);

　 } catch (Exception e) {

　return null;

　 }

　} /**

　* base64解码

　* @param s:需要解码的数据

　* @return 解码后的数据

　*/

　public static byte[] getbyteFromBASE64(String s) {

　 if (s == null)

　return null;

　decoder = new

　 try {

　return (s);

　 } catch h (Exception e) {

　return null;

　 }

　} /**

　* base64编码

　 * @param s:需要编码的数据

　* @return

　编码后的数据

　*/

　public static String getrevFromBASE64(String s) {

　 if (s == null)

　return null;

　encoder = new

　 try {

　return ());

　 } catch (Exception e) {

　ret urn null;

　 }

　} 第 第 6 章

　关于通讯证书和银行证书 的 说明

　如果企业客户需要接收银行的主动反馈信息，请注意以下内容：

　1、 对于申请 IC 卡或者 USBKey 的硬方式数据证书的客户，需要在电子银行内部管理系统的“企业客户管理-客户通讯证书 ID 管理”下载一个通讯证书。此证书为磁盘证书，用于银行与客户建立 https 通讯使用；签名证书请客户继续使用硬证书；此磁盘证书需要拆分，拆分方法请见第 7 章。

　2、 所有客户需要从银行端获取两张证书，一张是：银行端将对应的数据层公钥 trust文件发给客户，以便银行与客户主动建立 https 链接认证使用；另一张是：银行端还要将客户验签使用的公钥证书在客户注册时也要发给客户，以便客户对银行返回的部分交易的数据进行验签使用。

　第 第 7 章

　磁盘证书拆分

　7.1 证书拆分方法 见以下附件中的《证书制作流程.doc》，拆分工具也在其中。

　7.2 证书拆分后流程 企业将证书拆分后，需要进行以下步骤 1、 将 trust 文件（通讯层公钥）发给银行，由银行布置在相关服务器上，以便建立 https 认证；

　2、 其他.cer、.key 和 store 文件由客户保存，分别是数据层公钥、数据层私钥和通讯层私钥；