记录海关165号、179号实时数据联调接口中需要注意的细节

最新推荐文章于 2025-04-12 23:44:18 发布

置顶 ccbox_net

最新推荐文章于 2025-04-12 23:44:18 发布

阅读量2.8w

点赞数 7

文章标签：跨境电商海关实时数据

本文链接：https://blog.csdn.net/ccbox_net/article/details/89031736

版权

海关165号、179号要求平台开放订单原始数据接入中碰到的问题解决办法和需要注意的细节。
文中只是记录了一些重点，不一定是全部的细节，一些操作部分的内容有所省略，可以留言提问补充。

首发CSDN，总结整理：ccbox.net

在开始之前，我们要先做一些准备：

一、准备好加签要用的卡介质

二、然后加入微信群：

三、接着准备好几个熟手的程序员，准备码代码。

在开始之前，我们要先做一些准备：

一、准备好加签要用的卡介质

先开通要用的企业操作员卡或者UKEY，准备好插着操作员卡或者UKEY的主机

（本地服务器或者办公PC随意，能保证以后能7x24不间断运行就行了。如果这台主机能开通公网访问就更方便。）

二、然后加入微信群：

数据中心实时抓取企业联调测试群。

因为测试环境要找管理员开通的，这里特别注意和留意的是，要关注管理员反复叮嘱发出来的两个内容：一个是 《数据抓取流程及常见问题.txt》 文档（以下简称常见问题），一个是“@所有人”的通知（以下简称群内通知），这个通知基本管理员每天会发好几次。
仔细阅读这两个内容，能解决开发调试过程中的90%的问题。

三、接着准备好几个熟手的程序员，准备码代码。

四、要提前阅读的通知和文档：

1、海关总署公告2018年第165号（关于实时获取跨境电子商务平台企业支付相关原始数据有关事宜的公告）
附件：《跨境电子商务零售进口统一版信息化系统原始数据实时获取方案.doc》
附件文档中简要说明了获取方案的过程。

2、海关总署公告2018年第179号（关于实时获取跨境电子商务平台企业支付相关原始数据接入有关事宜的公告）
附件：《海关跨境电商进口统一版信息化系统平台数据实时获取接口（试行）.zip》
附件中包含了一个接口文档（以下简称为： 接口文档 ），一个控件说明包，一个数据样例。
主要看接口文档，其他的可以先熟悉。

3、去群里找人要一个 《加签验签.rar》 的压缩包，这个包具体是谁给出的我也不记得了。
包里含有一个文档《海关加签调试步骤.docx》（以下简称为： 步骤文档 ）、证书导出工具包《debug.rar》、加签样例《html+js加签工具.rar》。

五、另外可以参考的一些线上经验教程：

179海关联调服务
https://blog.csdn.net/u010955036/article/details/88712577
海关实时数据企业联调接口开发步骤与概要
https://www.cnblogs.com/whtydn/p/10220209.html

好了，现在可以开始搞事了：

首先，参考步骤文档 ，将ukey或者操作员卡的证书导出，取得证书编号。
然后联系群管理员，把证书和相关的资料提交了开通测试环境先，然后再到口岸单一窗口登陆和注册相关所需的内容（可以测试通过之后再去注册）。
然后就可以开始做开发了。

业务模式：

实现前提：

跨境电商平台在订单支付的时候，需要保存发起的支付请求信息和支付成功的返回信息。
这个步骤要看目前运行的平台系统有没有对应保存的操作，没有的话，就得改一下平台系统的相关内容，增加支付原文和支付反馈的原文信息了。

业务流程：

1、海关发起数据查询通知 – 电商平台收到通知后，返回10000告知已收到通知；
2、电商平台查找对应订单信息，组成订单实时数据，将数据进行加签（发送到插有ukey的服务器进行加签）；
3、加签（通关）服务器将得到的签名和证书编码追加到订单实时数据中，发送到海关指定的服务器接口。

参考《跨境电子商务零售进口统一版信息化系统原始数据实时获取方案》配图。从图中我们可以直观的看到，这里面涉及到三个方面的服务器（或者叫做操作方？反正就是这个意思）。

业务实现：

接受海关发起的请求：

电商平台系统需要提供一个80端口的地址供海关随时发起查询。比如： http://open.xxx.com/real_time_data
【*重点说明：】
接口文档中对应的为：1.6.1. 企业实时数据获取接口（部署在电商平台）
但是，文档中只说明了这个接口的参数为三个，并未说明接口数据是怎么发送过来的，所以这里要留意【群里通知】，里面有一句话特别说明：从请求中获取openReq参数的值，该参数值是一个符合json标准的字符串，由于海关提交的请求是post方式（x-www-form-urlencoded），所以在url中是没有参数的，必须要从表单中获取该参数。也就是说，这三个参数要从一个openReq的字段中获取，获取后要进行json_decode解析成参数表。

收到海关的请求后，需要返回响应内容，表示接收到通知了，这里注意输出的是json，不是string。
{“code”:“10000”,“message”:"",“serviceTime”:1533271903898}
具体格式详情看文档即可。

生成报文和上传：

接着，电商平台需要将海关抽查的订单信息找出来，组成接口文档中的【1.6.2. 企业返回实时数据接口（部署在通关服务系统）】所需的申报数据，发送到【插着UKEY或操作员卡的通关服务器】进行数据加签。
加签（通关）服务器将申报数据按照接口文档说明，组成对应的字符串进行加签，取得签名。

【*重点说明：这里是大部分人很容易出错的地方】
接口文档中对应的为：1.6.2. 企业返回实时数据接口（部署在通关服务系统）
这里要注意阅读群里管理员发出来的【常见问题】，文档里面附有标准的报文固定样例，包括：验签拼接的原文、进行加签之前的报文、加签之后的签名、上传给海关的报文。
这里要提醒的是：用这里提供的数据，需要修改一个地方【ebpCode改成你自己的】，然后进行加签比对，如果你在你的系统里得到的验签拼接的原文、进行加签之前的报文相同，并且跟样例中的一致（重点：一致！！！除了刚才修改的ebpCode内容，其他的一个字符都不能有差异），那签名出来的就基本没有问题了。
得到签名后，将得到的certNo和signValue加入数据中，组成报文，再转为json，放到参数payExInfoStrpayExInfoStr中，就可以进行测试了。
PHP开发的同学需要注意，json字符串需要做一下urlencode，也就是：

$postdata = 'payExInfoStr='.urlencode($payExInfoJsonStr);

这个时候将报文post到联调接口去就可以了。如果严格按照以上内容去做，前面的工作也做好了，那么一般返回的结果很有可能是：
{“code”:“20006”,“message”:“上传失败,入库失败 java.sql.SQLException: ORA-00001: 违反唯一约束条件 (sessionID重复)”,“total”:0,“serviceTime”:1500000000000}
得到这个结果，就恭喜你了，签名和测试工作已经搞定了。这里的错误是因为你用的是样例数据，自己随意生成一个sessionID再跑一遍，基本就成功了。

常见错误结果和解决方法：

{“code”:“20004”,“message”:“企业实时数据获取验签证书未在服务系统注册”,“total”:0,“serviceTime”:1500000000000}
得到这个结果，说明证书没有注册，测试环境联系管理员，生产环境需要到单一窗口去注册上传。如果已经上传了的，去看看你填的ebpCode是否是你自己的。

{“code”:“20000”,“message”:“上传失败 java.lang.IllegalStateException: xxxx这里是错误信息内容”,“total”:0,“serviceTime”:1500000000000}
这个错误说明上传的数据格式不对，海关系统无法解析，注意看看是否有字段类型或者格式错误，也注意看具体看错误内容，一般都有提示。

{“code”:“20005”,“message”:“验签失败”,“total”:0,“serviceTime”:1500000000000}
得到这个信息，说明上传的内容格式没问题了，验签失败，可能加签过程不对，一般都是字符串或者加签格式不对导致的，相见加签部分的细节，注意比对加签内容的格式和样例是否一致。另外也要看看用得证书什么的有没有问题。

{“code”:“20006”,“message”:“上传失败,入库失败 java.sql.SQLException: ORA-00001: 违反唯一约束条件 (sessionID重复)”,“total”:0,“serviceTime”:1500000000000}
得到这个消息，恭喜你，测试基本成功了：加签成功、数据格式没有问题了，接下来就可以自己生成模拟数据去测试了。

{“code”:“10000”,“message”:“上传成功”,“total”:0,“serviceTime”:1500000000000}
恭喜，测试成功。

常见问题解读：

前面有提到：仔细阅读管理员频繁提出的两个内容，能解决开发调试过程中的90%的问题。
但是有的时候，越是频繁提醒的内容，大家就是这么容易忽略掉这个问题，所以这里将管理员频繁提到的内容整理和解读一下，因为基本里面的内容都是重点，所以这里只做整理：

《@所有人的通知：》

1、正式环境服务地址已经上线了，注册地址 ceb1.chinaport.gov.cn 企业自行注册。审核的时候系统随机抽查企业三天内的通关清单订单号，发送给企业，企业接收到返回10000为审核通过。跨境企业类型为电商平台才能注册，企业可以去企管科查询自己的企业类型。

2、审核不通过的原因：

企业收到调用返回的不是10000，【审核的时候如果不返回10000，则无法通过审核】
企业三天内没有订单数据，【没有数据可以抽查，无法审核】
端口需要80，【一定要80端口，不能自定义其他的端口，能通过http访问】
是否配置白名单，【这个自己理解吧，把联调审查接口拉黑了你还想过审？】
需要卡介质登陆【嗯，注册地址要用卡介质登录】

3、测试环境注册是丁鑫注册，企业自己注册的是正式环境【测试环境人工开通，生产环境自助开通】
4、证书编号需要小写！！！【注册填写的编号、上传报文中的证书编号都要小写】
5、从请求中获取openReq参数的值，该参数值是一个符合json标准的字符串，由于海关提交的请求是post方式（x-www-form-urlencoded），所以在url中是没有参数的，必须要从表单中获取该参数【详见文中的相关部分内容，这里与接口文档是有出入的，以这里为准】
6、需要重新的审核的企业，重新注册下即可【没通过的地址可以直接删除，重新注册，看后面第8条】
7、payExchangeInfoList 应该为 payExchangeInfoLists【这里与接口文档是有出入的，以这里为准】
8、！-！！-！企业地址快捷审核：把审核不通过的地址删除从新注册。状态变为未审核提高企业审核效率。！-！
9、！-！审核通过是接口通了，重要的是企业必须在接收请求后两分钟内上传数据。！-！【划重点：两分钟内上传数据！！！】
10、！-！上传数据的sessionid 必须和请求的sessionid保持一致。！-！【sessionID是海关识别抽查数据的唯一码，而不是以你的orderNo为准的，我猜这也是为什么上一条要求两分钟内要上传数据，可能sessionID的失效时间就是两分钟，我猜的。。。】

《数据抓取流程及常见问题.txt》

联调流程
1、服务注册：由于企业无法看到联调的注册页面，需要将证书（加签设备的签名证书），证书编号（证书的序列号），电商平台代码（海关十位编码）提交给对接人员完成注册，私信给丁鑫，联调需要企业提供的：证书、证书编号、电商平台代码、电商企业名称、联系人、联系人电话

2、企业在联调环境中测试上传数据：企业在联调环境中根据所提供样例，由对接人员协助完成上传，返回“上传成功”，为正确上传状态,通过联调企业返回实时数据接口地址上传请求(1. 将数据内容所有数据一级节点使用||分割符拼接为连续字符串，使用IC卡、Ukey、服务类密码设备进行加签，将certNo（证书编号）、signValue（加签结果）补充入请求中。)

3、企业模拟请求测试接口连通性
通过样模拟样例中海关实时数据获取请求，按返回格式正确返回正常调用值。在相应时间内上传支付相关原始数据。
4、线上注册，将证书和接口地址在注册页面上传注册，注册地址 ceb1.chinaport.gov.cn 企业自行注册
5、注册完成需要审核，审核的时候系统随机抽查企业三天内的通关清单订单号，发送给企业，企业接收到返回10000为审核通过.
审核不通过的原因：企业收到调用返回的不是10000，企业三天内没有订单数据，端口需要80，是否配置白名单，需要卡介质登陆
6、审核通过后企业启用审核通过的地址，确保上传数据在收到请求后两分钟内完成。
7、保持接口连通。对接完成

1、企业先进行联调测试，165和179公告有测试接口，和报文样例
2、企业将证书编号和证书和电商平台代码（海关备案十位）发给群里-丁鑫
3、服务注册正式环境已经上线，注意联调环境需要提交给我们注册（联调环境企业看不到，企业可以自己注册的是正式环境）
4、企业上传过程中提示：”企业实时数据获取验签证书未在服务系统注册的“，证书和证书编号未提供。
提供过的还提示未注册,检查上传报文内ebpcode和certno有没有修改为提供的电商平台代码和证书编号。
证书编号小写.要避免sessionid重复。
5、上传失败的检查：
1，上传数据方式有问题，建议可以先把payExchangeInfoHead里的initalRequest和initalResponse先改成简单的字符串试试
2、验签前json解析失败注意:json字符串格式（看公告样例）
3、如果带特殊字符，payInfostr的value 需要做下urlencode (使用多次就会出现汉字乱码%什么的)

6、验签失败：
1、原文不匹配(注意格式字段顺序二级字段顺序必须和固定格式一致表头表体和时间的value必须添加双引号 totalAmount不带引号)
2、证书问题(证书如果带-----BEGIN CERTIFICATE与-----END CERTIFICATE独占一行别跟在后面，影响验签结果。)
3、加签方式不对(js加签如果证书原文没问题一定可以过，不可以用法人卡要用操作员卡）一般原文不匹配几率大 仔细检查
7、数据中心请求你们的Content-Type: application/x-www-form-urlencoded，端口默认 80 从请求中获取openReq参数的值，该参数值是一个符合json标准的字符串，由于海关提交的请求是post方式（x-www-form-urlencoded），所以在url中是没有参数的，必须要从表单中获取该参数。。
8、企业服务地址端口测试环境需要为80。
9、不知道如何获取证书和证书编号的咨询群内联调成功企业
10、上传失败入库失败：检查sessionid是否重复，验证字段必填项与长度，详细看公告文档。
11、审核不通过的几种情况：
1、接口不通企业收不到调取信息。
2、企业收到调用返回的不是10000
3、企业三天内没有订单数据
4、端口不是80，是否配置白名单

报文固定样例

验签拼接的原文：

"sessionID":"fe2374-8fnejf97-55616242"||"payExchangeInfoHead":"{"guid":"9D55BA71-55DE-41F4-8B50-C36C83B3B419","initalRequest":"https://openapi.alipay.com/gateway.do?timestamp=2013-01-0108:08:08&method=alipay.trade.pay&app_id=13580&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&charset=GBK","initalResponse":"ok","ebpCode":"3301963K69","payCode":"312226T001","payTransactionId":"2018121222001354081010726129","totalAmount":100,"currency":"142","verDept":"3","payType":"1","tradingTime":"20181212041803","note":"批量订单，测试订单优化,生成多个so订单"}"||"payExchangeInfoLists":"[{"orderNo":"SO1710301150602574003","goodsInfo":[{"gname":"lhy-gnsku3","itemLink":"http://m.yunjiweidian.com/yunjibuyer/static/vue-buyer/idc/index.html#/detail?itemId=999761&shopId=453"},{"gname":"lhy-gnsku2","itemLink":"http://m.yunjiweidian.com/yunjibuyer/static/vue-buyer/idc/index.html#/detail?itemId=999760&shopId=453"}],"recpAccount":"OSA571908863132601","recpCode":"","recpName":"YUNJIHONGKONGLIMITED"}]"||"serviceTime":"1544519952469"

进行加签之前的报文：（这个和上文是一致的，和上面的原文一样，ebpCode值换成你自己的）

"sessionID":"fe2374-8fnejf97-55616242"||"payExchangeInfoHead":"{"guid":"9D55BA71-55DE-41F4-8B50-C36C83B3B419","initalRequest":"https://openapi.alipay.com/gateway.do?timestamp=2013-01-0108:08:08&method=alipay.trade.pay&app_id=13580&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&charset=GBK","initalResponse":"ok","ebpCode":"3301963K69","payCode":"312226T001","payTransactionId":"2018121222001354081010726129","totalAmount":100,"currency":"142","verDept":"3","payType":"1","tradingTime":"20181212041803","note":"批量订单，测试订单优化,生成多个so订单"}"||"payExchangeInfoLists":"[{"orderNo":"SO1710301150602574003","goodsInfo":[{"gname":"lhy-gnsku3","itemLink":"http://m.yunjiweidian.com/yunjibuyer/static/vue-buyer/idc/index.html#/detail?itemId=999761&shopId=453"},{"gname":"lhy-gnsku2","itemLink":"http://m.yunjiweidian.com/yunjibuyer/static/vue-buyer/idc/index.html#/detail?itemId=999760&shopId=453"}],"recpAccount":"OSA571908863132601","recpCode":"","recpName":"YUNJIHONGKONGLIMITED"}]"||"serviceTime":"1544519952469"

加签之后的签名（ebpCode值换成你自己的后，出来的签名肯定不是这个，所以这个值不用看）

J1shnr986MzgvwOBIMD0QMpkTTTARsGgwM9RkRAAmZOWA1ZAi8KNR+h5WtqXy6qdiW9KTfLyx9kgseWX/udghOOMVJrYlGelhwg26L7bq5gj72AU40zXq69bNoOgH/ccSQzHFRvbGug2gJ4Pv8dSNVVY8rFzX+8AMNnHTdIWo74=

上传给海关的报文（这里的格式是一个标准的json格式，加入了certNo和signValue值，如果带特殊字符，payInfostr的value 需要做下urlencode (使用多次就会出现汉字乱码%什么的)）

{"sessionID":"fe2374-8fnejf97-55616242","payExchangeInfoHead":{"guid":"9D55BA71-55DE-41F4-8B50-C36C83B3B419","initalRequest":"https://openapi.alipay.com/gateway.do?timestamp=2013-01-0108:08:08&method=alipay.trade.pay&app_id=13580&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&charset=GBK","initalResponse":"ok","ebpCode":"3301963K69","payCode":"312226T001","payTransactionId":"2018121222001354081010726129","totalAmount":100,"currency":"142","verDept":"3","payType":"1","tradingTime":"20181212041803","note":"批量订单，测试订单优化,生成多个so订单"},"payExchangeInfoLists":[{"orderNo":"SO1710301150602574003","goodsInfo":[{"gname":"lhy-gnsku3","itemLink":"http://m.yunjiweidian.com/yunjibuyer/static/vue-buyer/idc/index.html#/detail?itemId=999761&shopId=453"},{"gname":"lhy-gnsku2","itemLink":"http://m.yunjiweidian.com/yunjibuyer/static/vue-buyer/idc/index.html#/detail?itemId=999760&shopId=453"}],"recpAccount":"OSA571908863132601","recpCode":"","recpName":"YUNJIHONGKONGLIMITED"}],"serviceTime":"1544519952469","certNo":"01010000000019f1","signValue":"J1shnr986MzgvwOBIMD0QMpkTTTARsGgwM9RkRAAmZOWA1ZAi8KNR+h5WtqXy6qdiW9KTfLyx9kgseWX/udghOOMVJrYlGelhwg26L7bq5gj72AU40zXq69bNoOgH/ccSQzHFRvbGug2gJ4Pv8dSNVVY8rFzX+8AMNnHTdIWo74="}

最后再提醒一句：很多细节需要去慢慢查，一个字符可能都会翻车。

感谢群管理员丁鑫一直都在不厌其烦的跟进答疑，大家有问题可以留言相互交流，祝大家早日接通。

首发CSDN，总结整理：ccbox.net