目錄

在開始之前，我們要先做一些準備：

一、準備好加簽要用的卡介質

二、然后加入微信群：

三、接著準備好幾個熟手的程序員，準備碼代碼。

四、要提前閱讀的通知和文檔：

五、另外可以參考的一些線上經驗教程：

好了，現在可以開始搞事了：

業務模式：

實現前提：

業務流程：

業務實現：

接受海關發起的請求：

生成報文和上傳：

常見錯誤結果和解決方法：

常見問題解讀：

《@所有人 的通知：》

《數據抓取流程及常見問題.txt》

報文固定樣例

在開始之前，我們要先做一些準備：

一、準備好加簽要用的卡介質

先開通要用的企業操作員卡或者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為審核通過?？缇称髽I類型為電商平臺才能注冊，企業可以去企管科查詢自己的企業類型。

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的失效時間就是兩分鐘，我猜的。。?！?/span>

《數據抓取流程及常見問題.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、驗簽失?。?br />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、上傳失敗入庫失?。簷z查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="}

最后再提醒一句：很多細節需要去慢慢查，一個字符可能都會翻車。

感謝群管理員丁鑫一直都在不厭其煩的跟進答疑，大家有問題可以留言相互交流，祝大家早日接通。