1、 企业开发手册 1. 文档属性文档属性 内容文档名称 中国工商银行银企互联系统企业开发手册文档版本号 A3文档状态 正式稿文档编写完成日期 2012-11-1作 者 高小伟（北京开发三部），丁孚旌（北京开发三部）2. 文档变更历史清单文档版本号 变更日期 修改人 备注A0 2011-11-21 高小伟 给文档加了首页，版本号，作者等信息。A1 2012-4-10 高小伟 修正 4.1.3.2” 企业接收交易响应数据过程” , 4.1.3.2” 企业接收交易响应数据过程”对于推广版交易来说，企业收到的同步返回包，Base64解码后就是明文，不需要验签。A2 2012-9-5 高小伟 增加了第 8
2、 章 交易规则A3 2012-11-1 丁孚旌 修正签名验签接口用例中的内容A4 2013-7-31 高小伟 补充了“第 9 章 大批量指令提交”3. 本次修改变更说明序号 变更内容简述1. 第 9 章：增加了大批量提交接口“人事发工资指令提交”2.3.4.5.目录第 1 章 概述 .4第 2 章 总体方案介绍 .42.1 总体网络结构图 .42.2 企业端安全服务器简介 .42.3 安全控制介绍 .5第 3 章 重点说明 .6第 4 章 银企互联 NC 方式接入客户 .84.1 企业端系统环境要求 .84.1.1 软件环境 .84.1.2 网络环境 .84.1.3 企业开发过程描述 .8第
3、5 章 银企互联 非 NC 方式接入客户 .125.1 企业端系统环境要求 .125.1.1 软件环境 .125.1.2 网络环境 .135.1.3 企业开发过程描述 .13第 6 章 关于通讯证书和银行证书的说明 .19第 7 章 磁盘证书拆分 .197.1 证书拆分方法 .197.2 证书拆分后流程 .19第 1 章 概述银企互联面向大的集团客户，提供与企业 ERP 系统直连的平台，为工行的现金管理服务提供多渠道和客户化支持。企业 ERP 系统通过 HTTPS 协议与工行系统进行连接并向银企互联前置发送数据，数据的接口格式使用标准的 xml 数据格式，但双方通讯的过程中则需要遵守下文描述的
4、规定。银企互联前置接到企业数据后进行一系列的检查后完成交易，并将处理结果以企业便于处理的形式返回给企业。在安全保证方面，通讯层的安全保证是 HTTPS 协议。企业如需使用银企互联系统，要办理有关注册手续，并审领证书。企业进行结算类交易时，如果涉及到授权过程，企业需要在企业网银系统中完成相关授权动作。银企互联系统将企业提交的支付指令或者授权成功后的指令当作最终转账指令，根据提交指令的证书 ID 检查收付方帐号等合法性，以保证所提交指令在权限允许范围内进行操作。第 2 章 总体方案介绍2.1 总体网络结构图I n t e r n e t / I n t r a n e tI n t e r n e
5、 t / I n t r a n e t企业 E R P 系统 2银企互联系统N e t S a f e 服务器企业 E R P 系统 1h t t p sN e t S a f e C l i e n th t t ph t t p s上图企业 ERP 系统 1 采用的是非 NC 方式接入的客户；企业 ERP 系统 2 采用的是 NC 方式接入的客户；2.2 企业端安全服务器简介此服务器只对使用 NC 方式接入的客户有效。企业端安全服务器被称为 NetSafe Client。它有两个可以配置的端口分别用于加密和签名验签服务，如下图所示（假设为加密端口，为签名验签端口）。加密Netsafe C
6、lient签名4.https 交易请求包5.https 交易返回包1.签名请求包2.签名结果3.http 交易请求包6、http 交易返回包结算类具体使用时，企业应用向工行提交交易请求时，可以依照 http 协议向 NetSafe Client的端口发送请求。接到请求后，NetSafe Client 使用企业证书将 http 请求包转换成 https请求包发往工行端服务器(如上图 “查询类”) ；如果需要对某些交易数据进行签名，则企业应用需要与签名端口建立 Socket 连接并将待签名数据发往端口，然后接收端口的签名结果，之后再将包含签名信息的交易请求发往端口而完成整个交易请求过程(如上图“结
7、算类”) 。对签名还是验签名请求的区分则是通过 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 分别用于标识签名和验签名的返回结果。为方便起见，可以将 NetSafe Client 的两个服务端口逻辑地称为两台服务器，NetSafe Client 的加密服务器和签名服务器。
8、2.3 安全控制介绍对于 NC 方式接入的客户 企业向工行提交的交易数据，必须通过企业方的 NetSafe Client 进行与工行服务器的连接，接口确定需要签名的数据也必须由 NetSafe Client 的签名服务器加密Netsafe Client4.http 交易返回包1.http 交易请求包 2.https 交易请求包3.https 交易返回包查询类签名后组成规定的数据包格式后，通过 NetSafe Client 提交工行，这样可以保证企业数据以及相关信息不被恶意篡改。 数据全部由 NetSafe Client 负责转发，使 NetSafe Client 成为架设在企业现场的工行接入服
9、务器。而企业与工行之间安全的连接，由 NetSafe Client 和工行安全代理服务器 NetSafe 保证； 工行接收到企业提交过来的部分关键交易数据后，需要解密并验证企业的数字签名，以防止第三方假冒企业的行为。对于非 NC 方式接入的客户 企业向工行提交交易数据时的安全控制企业 ERP 与银企互联系统之间使用 HTTPS 协议通讯。企业可以选择是否对交易数据进行对称加密，目前系统支持的算法有 DES 与3DES。进行对称加密可以防止第三方截获交易的信息。而加密中需要用到的密钥由企业与工行共同约定。（加密功能暂不支持）企业需要对其发送的指令数据进行数字签名，签名中使用的证书可以是企业证书也
10、可以是工行证书，其中签名使用的算法是 SHA1withRSA。进行数字签名可以防止第三方假冒企业的行为。 工行向企业发送结果信息时的安全控制企业 ERP 与银企互联系统之间使用 HTTPS 协议通讯。企业可选择是否对返回数据进行对称加密，方法与上文相同。工行对部分关键交易返回信息进行数字签名。第 3 章 重点说明xml 格式要支持业界公认的标准格式，例如：等同于；上送数据格式尽量简单，避免使用 CDData 等文本格式。所有的交易请求包中“包序列 ID”字段（PackageID）由企业产生，产生规则为当前日期（北京时间，格式为 yyyyMMdd）7 位序列号（例如 20021223000000
11、1，为2002 年 12 月 23 日发送的一个交易请求包的包序列 ID） 。在一个企业代码下当日包序列 ID 必须唯一。工行处理完毕之后将该字段原值返回，即所有的交易返回包中“包序列 ID”字段（PackageID）。转帐交易请求包中“签名时间”字段（SignTime），格式为yyyyMMddHHmmssSSS（例如 20021223092710568，表示 2002 年 12 月 23 日 9 点 27分 10 秒 568 毫秒）。签名时间应为北京时间。签名时间如果与交易请求到达工行服务器时的北京标准时间误差过大（暂定为 15 分钟），交易将无法进行。此措施将可以有效地防止黑客采用重放攻击
12、进行干扰帐务活动的行为。同一笔交易如果因为网络不正常等因素需要重新提交时，要修改转账交易请求包的“签名时间字段”并重新签名。所有请求包和返回包中备用字段的使用主要是出于对今后扩展的考虑，如果以后需要增加企业上送的项目或者返回给企业的信息，不必再改变交易包格式。目前对企业请求包来说这些备用字段的值可以送空；企业对银行返回包中的备用字段也不必作处理。请求包中的备用字段标签为“ReqReserved*”，返回包中的备用字段标签为“RepReserved*”（其中*为 1、2、3 或 4，详见接口说明文档）。查询历史明细返回数据包中交易时间（）数值如为空，则说明该笔指令是银行的计息交易明细。支付查询指
13、令接口，方便企业对可疑、有疑问（如网络中断，交易长时间没有返回等）或处理完毕的转帐指令进行查询。企业提交要查询的结算请求的包序列 ID，工行返回该笔转帐指令的基本信息和状态。本接口说明中所有涉及金额的字段都是以分为单位（不带小数点）。如企业系统需要代理汇兑功能则企业应用需同步开发网点信息下载交易，以便为代理汇兑交易中收方为它行情况时提供工行网点名称。否则，无需开发网点信息下载交易。在网点信息下载功能中，由于下载数据过大且数据不会经常更新，所以此交易控制了企业每日下载次数。目前暂定次数为每日 2 次。个人联名卡签权指令只支持币种是人民币的账号/卡号。企业端传输数据时，指定 xml 编码方式为 G
14、BK。银企互联提交包中包含“签名时间（yyyyMMddHHmmssSSS）”此标签的，说明该交易需要进行签名处理。企业端的程序需要对银行返回的数据有可扩展性，以便适应今后业务的不断发展。银企互联系统支持两种接入方式，客户可以任何选择一种。第一种：使用第三方 NC软件方式接入银企互联系统；第二种：使用非 NC 方式企业直接接入银企互联系统；一些接口中，返回包分文件级返回包和指令级返回包两种。文件级返回包是作为客户请求的响应信息同步返回的。而指令级返回包是银行主动发起的异步返回信息，表示指令处理的结果，指令级返回包首先会返回整批指令的处理结果，然后对于其中指令状态非最终状态（成功和失败）的指令，银
15、行会实时更新每一条指令的状态，然后再每条分别以指令级返回包的格式返回给客户。建议客户使用 HTTP/1.1 协议。 HTTP/1.0 及其以下协议版本可能无法正常发送指令到银行端。下面将区分两类客户分别对接入方式等相关信息进行说明。第 4 章 银企互联NC 方式接入客户4.1 企业端系统环境要求4.1.1软件环境对企业的 ERP 系统无要求；工行企业端证书服务器软件 NetSafe Client 需安装在一台 PC 机上。4.1.2网络环境企业财务系统通过局域网与工商银行提供的 NetSafe Client 连接；企业端的 NetSafe Client 可以通过专线或 INTERNET 与中国
16、工商银行银企互联系统互联。4.1.3企业开发过程描述4.1.3.1 企业提交交易请求数据过程企业提交的交易分为两大类：查询类和结算类（需要进行签名处理）。1、 查询类：（1） 企业按照工行提供的 xml 包格式进行打包，在局域网内通过 http 协议以 POST 方式将交易包发送到 NetSafe Client 的安全 http 协议服务器。http 请求格式：action=” http:/客户端 NetSafe Client 的地址和加密端口号/servlet/ICBCCMPAPIReqServlet?userID= 证书 ID&PackageID=包序列 ID &SendTime=请求时间
17、 ”http 请求包头信息：Content-Type 应为 application/x-www-form-urlencoded请求数据格式（post 方式）：Version=版本号（目前支持 0.0.0.1 和0.0.1.0 两个版本。不同版本号对应的接口格式不同，请参考具体交易的接口文档) &TransCode=交易代码（区分交易类型，每个交易固定)&BankCode=客户的归属单位 &GroupCIS=客户的归属编码&ID=客户的证书 ID（无证书客户可空)&PackageID= 客户的指令包序列号（由客户 ERP 系统产生，不可重复)&Cert=客户的证书公钥信息（进行BASE64 编码
18、；NC 客户送空) &reqData=客户的 xml 请求数据 (需要URLEN)其中：包序列 ID、证书 ID 应根据实际情况进行更改，请求时间为企业发出该交易请求包的当前系统时间。post 方式最后不允许有回车等其他乱字符，TransCode 交易名称应与 xml 包内标签中的值一致，action 中的证书ID、PackageID 与请求数据格式中的证书 ID、PackageID、xml 包中的证书 ID、PackageID 的值三者相一致。（2） NetSafe Client 将 xml 包加密后按照 https 协议，通过互联网/专线发送到银行端的 NetSafe Server。（本步
19、由 NetSafe Client 完成，企业无需处理）；（3） NetSafe Server 将交易请求送银企互联系统进行处理。2、 结算类：（1） 企业按照工行提供的 xml 包格式进行打包，在局域网内与 NetSafe Client 的签名端口建立 Socket 连接，通过此连接向签名端口发送 http数据包。http 包头中需包含“Content-Length”和“Content-Type”两个属性。其中“Content-Length:”后面是需要签名的二进制数据包的长度，“Content-Type:”后面是需要签名的标记，为企业NetSafe ClientNetSafe Server（1） （2）工行（3）
