【电子回单】中国工商银行开放平台版（ICBC_CLOUD）回单配置指南

一、功能说明

    中国工商银行开放平台版（ICBC_CLOUD）的电子回单是通过银行sftp方式推送。客户使用注册的sftp用户名以及登录私钥，通过SFTP方式登录到银行文件服务器上下载回单。

• 生产上文件服务地址：gw.open.icbc.com.cn ，端口：8001

• 电子回单下载路径：/Ebillsend/download （总行旧版的话一般是这个路径，最好用winscp连上工行sftp确认下）

    电子回单推送是每天早上7点左右开始推送T-1日交易的电子回单，根据交易量大小推送耗时可能会略有不同。推送时是以zip文件为单位推送。电子回单3天内可以一直重复获取，过期会被自动清理，所以需要及时下载备份。若出现了未及时下载备份的情况，需要联系银行技术人员补推电子回单。补推后，立刻生效，使用winscp连接银行SFTP服务，就可以查看到补退日期的电子回单了。

二、申请开通电子回单功能

    实施顾问（及客户）向银行申请开通电子回单功能，有些分行会要求填写一个《API开放平台信息维护新增申请表.doc》；不同分行的处理方式可能有所差别，具体请跟银行技术人员沟通。银行方一般会要求客户提供登录公钥、签名公钥（格式：选择PKCS8），以及登录用户名（客户自己定义的一个用户名）。另，客户需要生成ssh密钥公私钥对，并将公钥提供给银行方进行配置。

三、如何生成ssh密钥公私钥对？

    一般来说，银行方会提供生成密钥对的工具，请按照银行方提供的文档进行操作，生成的登录公钥、签名公钥给到银行方。而金蝶电子回单代理程序，在配置银行sftp时，“SFTP本机秘钥文件路径”需要配置 ssh格式的登录私钥文件。

    另，也可参考《电子回单程序部署说明V1.0.XXXXXXXX.docx》文档的“四、银行特殊的业务配置,4.工商银行推广版（ICBC_CMP）工行生成公钥私钥”章节进行操作（下载回单安装包并解压，\ebgProxy_XXXXXXXX 目录下就有这个文件）。具体操作步骤如下：

1. 下载winscp软件，点击[工具 - 运行PuttyGen]，打开puttyGen工具

2. 先点击[Generate]生成密钥对，再点击[Save public key]保存公钥文件

3. 再点击[Save private key]保存私钥，这是一个ppk文件（存档即可，电子回单代理程序这里用不上这个文件）。点击[Conversions]，再点击[Export OpenSSH key]，对话框提示点击"是"，输入文件名称后点【保存】，这样就生成完毕了。

    生成完毕后，把公钥文件和登录用户名（自己定义一个）提供给银行方。

4、有些客户可能是通过其它工具（例如银行方也有提供文档指导如何生成公私钥对）生成的私钥，名字往往叫“id_rsa”（或者提供的秘钥文件为ppk格式的文件），在回单系统配置SFTP本机秘钥文件路径为这个文件后，测试连接SFTP会提示：sftp连接失败：invalid privatekey：[B@xxxxxxxx]，如下图

    这种情况，是因为这个私钥文件不是回单系统要求的RSA格式的密钥，需要使用winscp的puttyGen工具转一下，操作如下：打开puttyGen工具，点【Load】导入这个id_rsa或ppk文件，然后点击【Conversions】-【Export OpenSSH key】。

四、开通电子回单功能后登录验证

    这一步骤不是必须的操作，但建议您验证一下。

    银行方开通回单功能之后，会推送文件到工行SFTP服务上，压缩包zip的文件命名包含日期，pdf回单文件名称的格式为 "账号_日期_流水号_xxx"开头。此时，可以用winscp登录工行SFTP，如下图所示，文件协议选择SFTP，输入主机名、端口、用户名后，点【高级】后选择SSh - 验证，选择密钥文件后，再去登录：

    登录之后，可以看到/Ebillsend/download子路径下已经有银行推送的zip文件了。例如下图所示的这种文件格式，金蝶电子回单代理程序定义其为【总行旧版】：

    zip文件解压下来后，双击打开看，如下图这样：

    特别说明：近期发现部分客户上线之后，银行方推送的回单PDF文件命名是下面截图的这种格式（银行方称之为“可验证PDF”）。这种文件命名规则，目前回单平台这边不能解析，请联系银行技术人员推送“PDF加签”这种格式的回单文件（上面截图的这种格式； 压缩包文件名称格式：xxx_日期 或者  xxx_日期_...      回单文件名称格式：账号_日期_流水号_....pdf）。

五、电子回单系统 - 配置项 - 银行配置，选[工商银行开放平台版]

• 银行SFTP服务器IP地址：gw.open.icbc.com.cn 

• 银行SFTP端口：8001

• 银行SFTP文件保存子路径：/Ebillsend/download

• 登录SFTP服务器使用的用户名：“如何生成ssh密钥公私钥对？”章节中提供给银行的登录用户名

• 登录SFTP服务器使用的密码：不需要配置，或随便输入一个值

• SFTP本机秘钥文件路径：“如何生成ssh密钥公私钥对？”章节中生成的那个ssh登录私钥文件的全路径

六、任务的[创建]->[预处理] ->[下载] ->[扫描]阶段

    可参考《电子回单程序部署说明V1.0.20240701.docx》文档的第三章“7.回单下载配置”操作，这里不再赘述。

    另，工行开放平台版支持采用新模式下载回单，在银行配置页面增加了一个配置项，如下：

配置名：工行开放版是否采用新模式下载回单

配置说明：新版下载模式去掉了扫描调度，预处理和下载调度完了就可以看到下载结果，不需要再等待扫描调度进行扫描才能看到下载结果。

七、说明

1、推送的文件格式

    注意：修改该配置项必须重启回单服务。

    目前，工行开放平台版支持的回单文件格式有3种，如下：

1） 总行旧版：压缩包文件名格式为040690000600123_20200604_1_00000.zip，PDF文件名为3602004409001385770_20201112_20317000085.PDF;

2） 总行银账通：压缩包文件名格式为渠道编号_协议编号_19位账号_币种_日期_回单类型_第几个子包.zip，PD