中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范v100

1、文件類(lèi)別：技術(shù)規(guī)范文件類(lèi)別：技術(shù)規(guī)范 密級(jí)：協(xié)議發(fā)布密級(jí)：協(xié)議發(fā)布中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)（訂單系統(tǒng)）上游客戶系統(tǒng)標(biāo)準(zhǔn)接口規(guī)范版本號(hào)：版本號(hào)：V1.0.0文檔編號(hào)：文檔編號(hào)：YT-NPP-API-01YT-NPP-API-01編制單位：編制單位：國(guó)內(nèi)小包項(xiàng)目組國(guó)內(nèi)小包項(xiàng)目組編編 制制 人：人： 黃春鳳黃春鳳編制日期：編制日期：20142014 年年 3 3 月月 2 2 日日審審 核核 人：人：徐黎春徐黎春審核日期：審核日期：20142014 年年 3 3 月月 3 3 日日中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 2 / 23批批 準(zhǔn)準(zhǔn) 人：人：李傳波李傳波批準(zhǔn)日期：批準(zhǔn)日

2、期：20142014 年年 5 5 月月 8 8 日日 Copyright 2001-2014, HLJ Post YiTong Info-net Co.,Ltd.網(wǎng)址：http:/www.e- 電話：086址：中國(guó)哈爾濱市南崗區(qū)西大直街 133 號(hào) 傳真：086國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 3 / 23變更歷史變更歷史日期日期變更描述變更描述變更者變更者2014-3-2新建黃春鳳2015-11-17增加重量字段中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 4 / 23目目 錄錄1概述概述.41.1

3、文檔目的.41.2 技術(shù)支持.43 參數(shù)、安全及數(shù)據(jù)完整性參數(shù)、安全及數(shù)據(jù)完整性.42.1 參數(shù)定義.42.1.1 上游客戶系統(tǒng)發(fā)送給中國(guó)郵政的參數(shù).42.1.2 中國(guó)郵政發(fā)送給上游客戶系統(tǒng)的參數(shù).52.1.3 消息格式.52.2 安全及數(shù)據(jù)完整性.52.3 數(shù)據(jù)發(fā)送和接收處理流程.63 接口描述接口描述.73.1 訂單接口.73.1.1 字段含義.73.1.2 請(qǐng)求格式.83.1.3 參數(shù)描述.103.1.4 返回格式.103.1.5 補(bǔ)充信息.103.2 訂單信息更新接口.113.2.1 字段含義.113.2.2 請(qǐng)求格式.123.2.3 參數(shù)描述.183.2.4 補(bǔ)充信息.184 系統(tǒng)交

4、互處理流程系統(tǒng)交互處理流程.194.1 流程圖.194.2 格式.194.1.1 接口反饋結(jié)果.194.3 補(bǔ)充信息.204.4 業(yè)務(wù)錯(cuò)誤信息.214.5 系統(tǒng)錯(cuò)誤信息.215 其它問(wèn)題和注意事項(xiàng)其它問(wèn)題和注意事項(xiàng).22中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 5 / 231 1概述概述1.1 文檔目的文檔目的本文檔主要規(guī)范中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)與上游客戶（如電商客戶）系統(tǒng)的數(shù)據(jù)接口。1.2 技術(shù)支持技術(shù)支持本接口開(kāi)發(fā)由黑龍江郵政易通信息網(wǎng)絡(luò)有限責(zé)任公司提供支持，如有疑問(wèn)請(qǐng)聯(lián)系易通公司。3 3 參數(shù)、安全及數(shù)據(jù)完整性參數(shù)、安全及數(shù)據(jù)完整性 2.1 參數(shù)定義參數(shù)定義 2.1.

5、1 上游客戶系統(tǒng)發(fā)送給中國(guó)郵政的參數(shù)上游客戶系統(tǒng)發(fā)送給中國(guó)郵政的參數(shù) 參數(shù)名稱(chēng) 用途 logistics_interface 消息內(nèi)容 data_digest 消息簽名 msg_type 消息類(lèi)型 （無(wú)需區(qū)分大小寫(xiě)） ecCompanyId 電商標(biāo)識(shí)，如“TAOBAO” （無(wú)需區(qū)分大小寫(xiě)） 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 6 / 232.1.2 中國(guó)郵政發(fā)送給上游客戶系統(tǒng)的參數(shù)中國(guó)郵政發(fā)送給上游客戶系統(tǒng)的參數(shù) 參數(shù)名稱(chēng) 用途 logistics_interface 消息內(nèi)容 logistic_provider_id TP編號(hào) msg_type 消息類(lèi)型 data_dig

6、est 消息正文的摘要 msg_type的值固定： 屬性值 說(shuō)明 默認(rèn)消息格式 ORDERCREATE 創(chuàng)建訂單 XML UPDATE 訂單更新（更新面單號(hào)、取消訂單、接單、不接單、不攬收） XML 2.1.3 消息格式消息格式 請(qǐng)求和響應(yīng)的消息格式將全部是XML2.2 安全及數(shù)據(jù)完整性安全及數(shù)據(jù)完整性 1、 以HTTP POST方式發(fā)送，請(qǐng)求方法的編碼格式：“application/x-www-form-urlencoded; charset=GBK” ； 2、 用“l(fā)ogistics_interface”字段表示要發(fā)送的XML內(nèi)容； 3、 用“data_digest”字段進(jìn)行簽名驗(yàn)證。簽名

7、使用MD5方式，對(duì)logistics_interface的內(nèi)容進(jìn)行簽名。原理為：通知內(nèi)容xml+parternID，然后進(jìn)行MD5，轉(zhuǎn)換為Base64字符串。 詳細(xì)解釋如下： 假設(shè)xml內(nèi)容為： ， partnered為123456 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 7 / 23 那么要簽名的內(nèi)容為123456，經(jīng)過(guò)md5和base64后的內(nèi)容就為L(zhǎng)ghTkEmsD2tbQ3fsIBRcBg= ,方法如下：MessageDigest md5 = MessageDigest.getInstance(MD5);BASE64Encoder base64en = new BASE

8、64Encoder();Ret=base64en.encode(md5.digest(str+partnered).getBytes(GBK); 然后需要對(duì)xml內(nèi)容（）進(jìn)行URL編碼（字符集為GBK） ，為：%3Corder%3E%3C%2Forder%3E 同樣需要對(duì)簽名的字符串進(jìn)行URL編碼，LghTkEmsD2tbQ3fsIBRcBg=的內(nèi)容為：LghTkEmsD2tbQ3fsIBRcBg%3D%3D 最終要發(fā)送的數(shù)據(jù)為：logistics_interface=%3Corder%3E%3C%2Forder%3E&data_digest= LghTkEmsD2tbQ3fsIBRc

9、Bg%3D%3D&msg_type =? 4、收到消息后，一定要驗(yàn)證數(shù)據(jù)是否完整及正確； 5、傳輸通道安全（https） ，目前不要求實(shí)現(xiàn)。 6、內(nèi)容不正確？請(qǐng)檢查字符集是否為GBK；所有的參數(shù)都是通過(guò)URL編碼傳送的，符合HTTP協(xié)議，注意客戶端是否解碼正確，有些控件已經(jīng)自帶URL解碼功能，請(qǐng)開(kāi)發(fā)人員注意。 2.3 數(shù)據(jù)發(fā)送和接收處理流程數(shù)據(jù)發(fā)送和接收處理流程 數(shù)據(jù)發(fā)送流程：數(shù)字簽名- 發(fā)送； 數(shù)據(jù)接收流程：接收- 數(shù)字簽名校驗(yàn)-處理； 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 8 / 233 3 接口描述接口描述3.1 訂單接口訂單接口3.1.1 字段含義字段含義字段

10、名含義類(lèi)型長(zhǎng)度是否為空ecCompanyId電商標(biāo)識(shí)（如：TAOBAO）String64NlogisticProviderID物流公司 IDString64NcustomerId客戶標(biāo)識(shí)String64YtxLogisticID物流訂單號(hào)String64NtradeNo業(yè)務(wù)交易號(hào)（新業(yè)務(wù)類(lèi)型待定：業(yè)務(wù)交易號(hào)（新業(yè)務(wù)類(lèi)型待定：252國(guó)內(nèi)小包）國(guó)內(nèi)小包）String64YmailNo物流運(yùn)單號(hào)String64NorderType訂單類(lèi)型(0-COD 1-普通訂單 3 - 退貨單)intNserviceType服務(wù)類(lèi)型(0-自己聯(lián)系 1-在線下單（上門(mén)攬收）4-限時(shí)物流 8-快捷COD 16-快遞保

11、障)longNname用戶姓名String32NpostCode用戶郵編String6Nphone用戶電話，包括區(qū)號(hào)、電話號(hào)碼及分機(jī)號(hào)，中間用“-”分隔；String32Ymobile用戶移動(dòng)電話, 手機(jī)和電話兩者必需提供一個(gè)String32Yprov用戶所在省String32Ncity用戶所在市縣（區(qū)） ，市區(qū)中間用“,”分隔；注意有些市下面是沒(méi)有String32N中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 9 / 23區(qū)address用戶詳細(xì)地址String256NsendStartTimetimestampYsendEndTime物流公司上門(mén)取貨時(shí)間段，通過(guò)“yyyy-MM-

12、dd HH:mm:ss”格式化，本文中所有時(shí)間格式相同。timestampYgoodsValue商品金額，包括優(yōu)惠和運(yùn)費(fèi)，但無(wú)服務(wù)費(fèi)longNitemName商品名稱(chēng)String256Nnumber商品數(shù)量intNitemValue商品單價(jià)（單位：分 兩位小數(shù)）longNspecial商品類(lèi)型（保留字段，暫時(shí)不用）intYremark備注String512YtotalServiceFee總服務(wù)費(fèi)COD：（單位：分）longYbuyServiceFee買(mǎi)家服務(wù)費(fèi)COD ：（單位：分）longYcodSplitFee物流公司分潤(rùn)C(jī)OD ：（單位：分） longYweight商品重量（單位：克）lo

13、ngN3.1.2 請(qǐng)求格式請(qǐng)求格式XML格式： TAOBAO POSTB a92266073246b3ed2a2f0ff4d0b2bf5e LP07082300225709 2007082300225709 124579546621 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 10 / 233200 2000 1000 1 0 張三 310013 231234134浙江 杭州,西湖區(qū) 華星科技大廈9層 李四 100000 231234134北京 北京市 華星科技大廈9層 2005-08-24 08:00:00 2005-08-24

14、 12:00:00 1900 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 11 / 23 Nokia N73 2 2 Nokia N72 1 2 0 易碎品 10 3.1.3 參數(shù)描述參數(shù)描述 訂單創(chuàng)建信息由電商物流平臺(tái)發(fā)送給中國(guó)郵政，電商物流平臺(tái)以HTTP POST方式發(fā)送消息，參數(shù)格式如下：參數(shù)名稱(chēng) 用途 logistics_interface 4.1.2節(jié)描述的XML字符串 data_digest logistics_interface的MD5簽名 msg_type 固定“ORDERCREATE” (不區(qū)分大小寫(xiě)) ecCompanyId 固定為“TAOBAO”(不區(qū)分大小寫(xiě)

15、) 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 12 / 233.1.4 返回格式返回格式返回標(biāo)準(zhǔn)的系統(tǒng)交互格式，詳情見(jiàn)4 系統(tǒng)交互處理流程3.1.5 補(bǔ)充信息補(bǔ)充信息1、物流訂單號(hào)在上游客戶系統(tǒng)中要具有唯一性 2、賣(mài)家發(fā)貨后，電商物流平臺(tái)實(shí)時(shí)發(fā)送訂單到郵政物流公司，這是系統(tǒng)交互，跟后面的業(yè)務(wù)處理是分開(kāi)的；3.23.2 訂單信息更新接口訂單信息更新接口 3.2.1 字段含義字段含義字段名含義類(lèi)型長(zhǎng)度是否為空l(shuí)ogisticProviderID物流公司編號(hào)String64NecCompanyId電商標(biāo)識(shí)；如淘寶的消息，此字段填寫(xiě)為“TAOBAO” ；String64YtxLogist

16、icID物流平臺(tái)的物流號(hào)（不能為空）String64NfieldName可更新字段：1、mailNo；2、weight；3、statusString64NfieldValue字段新值String64NfieldList(field1.20)remark取消訂單、不接單、不攬收時(shí)，此字段用于填寫(xiě)原因String215Y注：可以同時(shí)更新多筆訂單，但最多不超過(guò)20個(gè)； status 字段可選值：中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 13 / 23名稱(chēng) 說(shuō)明 WITHDRAW 取消訂單 ACCEPT 接單成功 UNACCEPT 接單失敗 NOT_SEND 攬收失敗 3.2.2 請(qǐng)求格

17、式請(qǐng)求格式XML格式： POSTB TAOBAO LP07082300225709 mailNo 32323232 LP07082300225709 weight 10 LP07082300225709 status ACCEPT 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 14 / 23 LR07082300224123 status WITHDRAW 沒(méi)貨 LR07082300227456 status ACCEPT LR07082300227456 mailNo 45875213 LR07082300224719 status UNACCEPT B04 LR070823002

18、28529 status NOT_SEND 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 15 / 23不送了 LP07082300789542 status ACCEPT LP07082300745289 mailNo 87561245 注： 1、面單號(hào)更新，可以是電商物流平臺(tái)發(fā)送給郵政物流公司，也可以是郵政物流公司發(fā)送給電商物流平臺(tái)。 2、更新重量信息，由郵政物流公司發(fā)送給電商物流平臺(tái)； 3、取消訂單消息由電商物流平臺(tái)發(fā)送給郵政物流公司； 4、接單成功、接單失敗、攬收失敗消息由郵政物流公司發(fā)送給電商物流平臺(tái)，接單失敗和攬收失敗需要在remark中填寫(xiě)原因； 5、可以一次性更新同一

19、筆訂單的多個(gè)字段，可以一次性更新多筆訂單的同一字段，還可以一次性更新多筆訂單的多個(gè)字段。但” fieldList”中” field”最多不超過(guò) 20，最少不少于 1。 更多請(qǐng)求格式舉例更多請(qǐng)求格式舉例 示例1 1：淘寶要更新LP07082300712367和LP07082300723465的面單號(hào)；下面消息由淘寶發(fā)送中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 16 / 23給郵政： POSTB TAOBAO LP07082300712367 mailNo 123457890 LP07082300723465 mailNo 234670641 示例2 2

20、：郵政要更新LP07082300711603和LP07082300723763的面單號(hào)；下面消息由郵政發(fā)送給淘寶： POSTB TAOBAO LP07082300711603 mailNo 237543899 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 17 / 23 LP07082300723763 mailNo 2348065433 示例3 3：郵政要更新LP07082300725671的面單號(hào)，更新LP07082300727340的重量，并且LP07082300712569接單成功；下面消息由郵政發(fā)送給淘寶： POSTB TAOBAO LP07082300711603 mai

21、lNo 237543899 LP07082300727340 weight 16 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 18 / 23 LP07082300712569 status ACCEPT 示例4 4：淘寶要取消訂單LP07082300716792，以下消息由淘寶發(fā)送給郵政： POSTB TAOBAO LP07082300716792 status WITHDRAW 沒(méi)貨了 示例5 5：郵政訂單LP07082300123674接單失敗，訂單LP07082300456239攬收失敗，以下消息由郵政發(fā)送給淘寶： POSTB TAOBAO LP07082300123674

22、中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 19 / 23status UNACCEPT S02 LP07082300456239 status NOT_SEND B04 3.2.3 參數(shù)描述參數(shù)描述 電商物流平臺(tái)發(fā)送給物流公司參數(shù)描述電商物流平臺(tái)發(fā)送給物流公司參數(shù)描述 參數(shù)名稱(chēng) 用途 logistics_interface 4.2.2節(jié)描述的XML字符串 data_digest logistics_interface的MD5簽名 msg_type 固定為“UPDATE” (不區(qū)分大小寫(xiě)) ecCompanyId 固定為“TAOBAO”(不區(qū)分大小寫(xiě))

23、 物流公司發(fā)送給電商物流平臺(tái)的參數(shù)描述物流公司發(fā)送給電商物流平臺(tái)的參數(shù)描述 參數(shù)名稱(chēng) 用途 logistics_interface 4.2.2節(jié)描述的XML字符串 logistic_provider_id TP編號(hào) msg_type 固定為“UPDATE” (不區(qū)分大小寫(xiě)) data_digest logistics_interface的MD5簽名 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 20 / 返回格式返回格式 返回標(biāo)準(zhǔn)的系統(tǒng)交互格式，詳情見(jiàn)4 系統(tǒng)交互處理流程訂單更新結(jié)果。 3.2.4 補(bǔ)充信息補(bǔ)充信息 1、用戶下單后在物流公司返回?cái)埵障⑶岸伎梢赃M(jìn)行取消操作； 2、物流狀態(tài)更新要求嚴(yán)格按照主流程圖發(fā)送，否則返回相應(yīng)的業(yè)務(wù)錯(cuò)誤信息； 中國(guó)郵政國(guó)內(nèi)小包綜合服務(wù)平臺(tái)訂單接口規(guī)范 v1.0.0 21 / 234 4 系統(tǒng)交互處理流程系統(tǒng)交互處理流程4.1 流程圖流程圖4.2 格式格式4.1.1 接口反饋結(jié)果接口反饋結(jié)果 XML