國際在線產(chǎn)品-新版國際在線發(fā)運(yùn)系統(tǒng)API規(guī)范

1、PAGE PAGE 18國際在線產(chǎn)品-新版國際在線發(fā)運(yùn)系統(tǒng)API規(guī)范 TOC o 1-3 h z u HYPERLINK l _Toc421030259 1E郵寶、e包裹、e特快、e速寶API綜述 PAGEREF _Toc421030259 h 1 HYPERLINK l _Toc421030260 1.1業(yè)務(wù)簡介 PAGEREF _Toc421030260 h 1 HYPERLINK l _Toc421030261 1.2適用范圍 PAGEREF _Toc421030261 h 1 HYPERLINK l _Toc421030262 1.3API功能域分類 PAGEREF _Toc42103

2、0262 h 1 HYPERLINK l _Toc421030263 1.4API開發(fā)說明 PAGEREF _Toc421030263 h 1 HYPERLINK l _Toc421030264 2E郵寶、e包裹、e特快、e速寶API規(guī)范 PAGEREF _Toc421030264 h 2 HYPERLINK l _Toc421030265 2.1SHIP（發(fā)運(yùn)服務(wù)） PAGEREF _Toc421030265 h 2 HYPERLINK l _Toc421030266 2.1.1運(yùn)單信息接收服務(wù) PAGEREF _Toc421030266 h 2 HYPERLINK l _Toc421030

3、267 2.1.2運(yùn)單信息驗(yàn)證服務(wù) PAGEREF _Toc421030267 h 9 HYPERLINK l _Toc421030268 2.1.3運(yùn)單信息取消服務(wù) PAGEREF _Toc421030268 h 10 HYPERLINK l _Toc421030269 2.1.4運(yùn)單信息查詢服務(wù) PAGEREF _Toc421030269 h 10 HYPERLINK l _Toc421030270 2.2TRACK（跟蹤信息服務(wù)） PAGEREF _Toc421030270 h 11 HYPERLINK l _Toc421030271 2.2.1實(shí)時跟蹤信息查詢 PAGEREF _Toc

4、421030271 h 11 HYPERLINK l _Toc421030272 2.3RATE(費(fèi)率服務(wù)) PAGEREF _Toc421030272 h 11 HYPERLINK l _Toc421030273 2.3.1國際E郵寶費(fèi)率計(jì)算 PAGEREF _Toc421030273 h 11 HYPERLINK l _Toc421030274 2.4Address(地址服務(wù)) PAGEREF _Toc421030274 h 12 HYPERLINK l _Toc421030275 2.4.1國內(nèi)地址行政區(qū)劃查詢 PAGEREF _Toc421030275 h 12 HYPERLINK l

5、 _Toc421030276 2.5LABEL(標(biāo)簽服務(wù)) PAGEREF _Toc421030276 h 13 HYPERLINK l _Toc421030277 2.5.1標(biāo)簽靜態(tài)文件下載服務(wù) PAGEREF _Toc421030277 h 13 HYPERLINK l _Toc421030278 2.5.2批量獲取標(biāo)簽服務(wù) PAGEREF _Toc421030278 h 14 HYPERLINK l _Toc421030279 2.5.3批量獲取標(biāo)簽服務(wù)（增強(qiáng)版） PAGEREF _Toc421030279 h 15 HYPERLINK l _Toc421030280 3附錄 PAGER

6、EF _Toc421030280 h 16 HYPERLINK l _Toc421030281 3.1附錄一：集成及用戶權(quán)限驗(yàn)證方法 PAGEREF _Toc421030281 h 16 HYPERLINK l _Toc421030282 3.2附錄二：國家和地區(qū)名稱以及郵編規(guī)則 PAGEREF _Toc421030282 h 16 HYPERLINK l _Toc421030283 3.3附錄三：澳大利亞-州列表 PAGEREF _Toc421030283 h 18 HYPERLINK l _Toc421030284 3.4附錄四：版本信息更新記錄 PAGEREF _Toc421030284

7、 h 18E郵寶、e包裹、e特快、e速寶API綜述業(yè)務(wù)簡介E郵寶、E包裹、E特快、E速寶API提供在線的運(yùn)單生成、標(biāo)簽打印、全程跟蹤等信息服務(wù)，覆蓋運(yùn)單的完整生命周期。適用范圍具備一定軟件開發(fā)能力并擁有自建訂單系統(tǒng)的大中小型B2C、C2C商家，可根據(jù)自身情況，進(jìn)行個性化的開發(fā)，以達(dá)到API系統(tǒng)對接的目的。API基于HTTP協(xié)議實(shí)現(xiàn)，需要雙方系統(tǒng)能夠通過internet互聯(lián)，并使用http方式進(jìn)行通訊。本文檔描述不涉及具體的開發(fā)語言，集成過程可使用合適的編程技術(shù)，實(shí)現(xiàn)基于http的數(shù)據(jù)交換方式。API功能域分類API數(shù)量較多，在后續(xù)建設(shè)過程中可能不斷增加，但總體可劃分幾個域進(jìn)行完善和擴(kuò)充：SHI

8、P(發(fā)運(yùn)服務(wù))、TRACK（跟蹤信息服務(wù)）、RATE（費(fèi)率服務(wù)）、ADDRESS（地址服務(wù)）、LABEL（標(biāo)簽服務(wù)）。API開發(fā)說明接口入網(wǎng)參數(shù)version（版本號）和authenticate（授權(quán)碼）在一些接口是必填項(xiàng)，具體請參照 HYPERLINK l _附錄一：集成及用戶權(quán)限驗(yàn)證方法 附錄一：集成及用戶權(quán)限驗(yàn)證方法如果您在開發(fā)中出現(xiàn)：商品名稱填寫中文，但返回錯誤還是提示“商品中文名稱不能為空，且必須包含至少2個漢字”時，請檢查在調(diào)用api接口時所用的編碼方式必須為UTF-8。E郵寶、e包裹、e特快、e速寶API規(guī)范SHIP（發(fā)運(yùn)服務(wù)）發(fā)運(yùn)服務(wù)域包含與運(yùn)單信息相關(guān)的服務(wù)，主要包括運(yùn)單信息

9、接收服務(wù)、運(yùn)單信息驗(yàn)證服務(wù)、運(yùn)單信息取消服務(wù)、運(yùn)單信息查詢服務(wù)。運(yùn)單信息接收服務(wù)資源地址：/partner/api/public/p/order/HTTP方法：POSTE郵寶、E包裹、E特快、E速寶(永興專線)傳送內(nèi)容：XML格式的訂單信息，示例：SO123123100deve360000000000000011falseAbandoned1232011-03-01T22:22:222011-03-11T02:22:1101Wang Lin10005521312311123333333313CN441402441402441402TeamsunLotus StreetmailTom.k1000

10、51111111212-222-0111UNITED STATES OF AMERICALASan FranciscoSt.Lotus Street王大琳100067123456-908-0981233333333333CN441402441402441402蓮花池東路126號bin 盒子box10.11CN12345678電腦computer 2unit0.2320.34CNComputer Machine12345678返回值：XML格式文檔，示例：LN334458969CNE速寶（賽誠專線）傳送內(nèi)容：XML格式的訂單信息，示例：CSDN1111331111000000000000011f

11、alseReturned1232011-03-01T22:22:222011-03-11T02:22:11客戶自定義信息1客戶自定義信息2Wang Lin10005521312311123333333313CN441402441402441402TeamsunLotus StreetmailMichael K Bristow23043111111212-222-0111AUVIC Roeland Park123123123baigongxiaobushijia王大琳100067123456-908-0981233333333333CN441402441402441402蓮花池東路126號bin

12、3043AUSTRALIAVICTullamarineStarTrack International,38 Annandale Road電腦22Kansas 2xxx0.120.34CNorderid注：1、e速寶賽誠專線的退貨地址，國家必填，如果省、市、縣、詳細(xì)地址都不填寫則取默認(rèn)地址。默認(rèn)全地址為：StarTrack International,38 Annandale Road Tullamarine VIC 3043 AUS退回地址：StarTrack International,38 Annandale Road退回地址城市：Tullamarine退回地址省份：VIC退回地址郵編：3

13、043退回地址國家：AUS2、澳大利亞-州為固定值，詳見 HYPERLINK l _澳大利亞-州列表 附錄三。返回值：XML格式文檔，示例：A000000000001入?yún)⒁?guī)范說明：訂單主體信息orderidstring4-32訂單標(biāo)識，此標(biāo)識由使用者提供，應(yīng)為訂單在使用者系統(tǒng)中的唯一標(biāo)識。如使用者訂單需拆分多個郵包（包裹），時，此標(biāo)識可重復(fù)。operationtypeinteger0|1|2|3業(yè)務(wù)類型（默認(rèn)0，如果不填或者沒有該節(jié)點(diǎn)就取默認(rèn)值）0:e 郵寶1:e 包裹2:e 特快3:e 速寶producttypeinteger1|2|3|4產(chǎn)品種類（默認(rèn)0）2:國際包裹簽收3:賽程專線4:永

14、興專線如果選擇 e 包裹業(yè)務(wù)：必填2如果選擇 e 速寶業(yè)務(wù)：必填3或4 customercodestring4-64使用者系統(tǒng)中的客戶編碼。即實(shí)際提交 此訂單的用戶在使用者系統(tǒng)中的身份標(biāo) 識。中郵物流平臺會依據(jù)此信息項(xiàng)對客 戶進(jìn)行區(qū)分，此項(xiàng)不能為空，但使用者 可提供加密或者編碼后的客戶身份標(biāo) 識。vipcodestring14使用者如果擁有 EMS 大客戶代碼， 應(yīng)填入此字段clcttypeinteger0|1攬收類型，1上門攬收或0用戶自送podbooleanfalse|true電子簽收（目前默認(rèn)為false）untreadstringAbandoned|AND I ASSURE TO PA

15、Y FOR THE CHARGE OF RETURN|Returned退回類型，默認(rèn)為ReturnedAbandoned: 丟棄ANDIASSURETOPAYFORTHECHARGEOFRETURN: 保證支付退回的郵件Returned: 退回volweightInteger體積重量=長（單位：厘米）寬（單位：厘米）高（單位：厘米）/6000，客戶需填寫長、寬、高及體積重量startdatedate2011-03-01T22:22:22起始預(yù)約時間enddatedate2011-03-01T22:22:22終止預(yù)約時間remarkstring0-128備注sku1string0-1024客戶自

16、定義信息1sku2string0-256客戶自定義信息2barcodeString0-64訂單條碼，如果需要打印出標(biāo)志該訂單的條碼，就填寫該值printcodeChar（00|01|03）該訂單要求的的打印格式，00表示A4，01表示44標(biāo)簽，03表示46標(biāo)簽，默認(rèn)值是01國內(nèi)名址信息(寄件人地址sender、攬收地址collect)namestring2-16姓名postcodestring6郵編phonestring6-36電話mobilestring13手機(jī)countrystring固定為CN國家provincestring6省份代碼citystring6城市代碼countystring

17、6區(qū)縣代碼companystring0-128公司streetstring8-256街道emailstring0-128電子郵箱國外名址信息（收件人信息receiver）namestring1-256姓名（英文）postcodestring0-16郵編請查看附錄二： HYPERLINK l _附錄二：國家和地區(qū)名稱以及郵編規(guī)則 國家和地區(qū)名稱以及郵編規(guī)則注：必須按照附錄中規(guī)則要求驗(yàn)證phonestring0-50電話mobilestring0-50手機(jī)countrystring1-24國家或地區(qū)名稱請查看附錄二： HYPERLINK l _附錄二：國家和地區(qū)名稱以及郵編規(guī)則 國家和地區(qū)名稱以及

18、郵編規(guī)則注：必須填寫附錄的簡稱或全稱(不區(qū)分大小寫)provincestring1-128省份(澳大利亞e速寶賽誠專線必須采用附錄三的州)citystring1-128城市companystring0-128公司（英文）streetstring1-256街道（英文）street_extra_1string1-256如果地址出現(xiàn)多行時使用這兩個字段來存儲street_extra_2string1-256emailstring0-128電子郵箱貨品信息cnnamestring1-64中文名稱(必填，至少包含2個漢字)ennamestring1-128英文名稱countinteger1-99999數(shù)

19、量unitstring0-16單位weightfloat0.001-9999.000重量，千克（三位小數(shù)），該重量是單個商品重量*數(shù)量delcarevaluemoney0.01-99999.00報(bào)關(guān)價格(兩位小數(shù))，該價格是單個商品的報(bào)關(guān)價格*數(shù)量originstring默認(rèn)為CN原寄地，固定填寫CNdescriptionstring064描述（英文）taxationidstring2-101、普通稅則號：選填項(xiàng)，填寫2-8位的數(shù)字2、e速寶賽誠專線：選填項(xiàng)， 2-10位數(shù)字3、e速寶永興專線：必填項(xiàng)，6-10位數(shù)字sellurlstring0-200銷售鏈接PS:各個業(yè)務(wù)下開通的國家或者地區(qū)

20、路向：1.e 郵寶：美國、澳大利亞、加拿大、法國、英國、俄羅斯、以色列、烏克蘭、沙特、巴西德國、挪威2.e 包裹：美國3.e 特快：澳大利亞、加拿大、臺灣、香港、日本、法國、韓國、巴西、西班牙、烏克蘭、新加波、荷蘭、俄羅斯、白俄羅斯、英國、德國4.e 速寶（賽誠專線）：澳大利亞5.e速寶（永興專線）：德國、美國、法國、英國、荷蘭、西班牙、意大利、比利時、盧森堡、愛爾蘭、丹麥、希臘、葡萄牙、瑞典、芬蘭、奧地利、塞浦路斯、捷克共和國、愛沙尼亞、匈牙利、拉脫維亞、立陶宛、馬耳他、波蘭、斯洛伐克、斯洛文尼亞、羅馬尼亞、保加利亞、克羅地亞運(yùn)單信息驗(yàn)證服務(wù)資源地址：/partner/api/public/

21、p/validateHTTP方法：POST傳送內(nèi)容：與運(yùn)單接收服務(wù)相同返回內(nèi)容：XML文檔成功示例：. success V00 驗(yàn)證成功失敗示例：. error V01 錯誤信息該服務(wù)旨在為集成過程中出現(xiàn)的格式、字段類型、字段長度等問題提供幫助，對于運(yùn)單信息的合規(guī)性進(jìn)行判斷和說明。服務(wù)返回結(jié)果僅供開發(fā)人員參考，因此在正式運(yùn)行后，不需要每個運(yùn)單都調(diào)用此服務(wù)，只在出現(xiàn)問題后，使用此服務(wù)排查原因。運(yùn)單信息取消服務(wù)資源地址：/partner/api/public/p/order/mail_numHTTP方法：DELETE該服務(wù)用于將運(yùn)單信息標(biāo)記為無效。運(yùn)單信息查詢服務(wù)資源地址：/partner/api

22、/public/p/order/mail_numHTTP方法：GET返回內(nèi)容：SO1231231deve360000000000000011falseAbandoned1232011-03-01T22:22:22.在order節(jié)點(diǎn)下增加元素,表示實(shí)收資費(fèi)、實(shí)收重量。TRACK（跟蹤信息服務(wù)）跟蹤服務(wù)域圍繞運(yùn)單的流轉(zhuǎn)信息提供服務(wù)。主要包括實(shí)時跟蹤信息的查詢：實(shí)時跟蹤信息查詢資源地址：/partner/api/public/p/track/query/cn|en/mail_numHTTP方式：GET返回結(jié)果：XML格式文檔 中英文返回2011-12-01 11:13:49南京收寄en|cn表示選用

23、en或cn任意值，en為英文信息，cn為中文信息。RATE(費(fèi)率服務(wù))提供運(yùn)單費(fèi)率的估算服務(wù)。國際E郵寶費(fèi)率計(jì)算資源地址：/partner/api/public/p/rate/epacket/HTTP方式：POST傳入?yún)?shù)：01200USCN650000返回值：01200USCN650000130.0備注信息返回值為請求報(bào)文信息， 再加估算費(fèi)用 （以人民幣計(jì)費(fèi)，單位為元） 和 remark （備注信息） 。入?yún)⒁?guī)范：operationtypeinteger業(yè)務(wù)類型 （默認(rèn) 0， 如果不填或者沒有該節(jié)點(diǎn)就取默認(rèn)值）0：e 郵寶1：e包裹2：e特快3：e速寶weightdouble重量信息，單位為

24、克recvcountrystring國家或地區(qū)請查看附錄二： HYPERLINK l _附錄二：國家和地區(qū)名稱以及郵編規(guī)則 國家和地區(qū)名稱以及郵編規(guī)則sendcountrystring原寄國家簡稱，中國為 CNsdprovstring省級代碼說明：目前暫不支持國際包裹郵件資費(fèi)查詢。Address(地址服務(wù))地址服務(wù)域提供國內(nèi)、國外標(biāo)準(zhǔn)地名或編碼的查詢：國內(nèi)地址行政區(qū)劃查詢資源地址：/partner/api/public/p/area/cn/province/list /partner/api/public/p/area/cn/city/list/no /partner/api/public/p

25、/area/ cn/county/list/noHTTP方式：GET示例：獲取國內(nèi)省級行政區(qū)劃：/partner/api/public/p/area/cn/province/list北京天津河北省山西省內(nèi)蒙古自治區(qū)獲取省份內(nèi)城市行政區(qū)劃：/partner/api/public/p/area/cn/city/list/130000石家莊市唐山市秦皇島市邯鄲市邢臺市保定市張家口市承德市滄州市廊坊市衡水市獲取城市下轄區(qū)縣列表：/partner/api/public/area/p/cn/county/list/130100長安區(qū)橋東區(qū)LABEL(標(biāo)簽服務(wù))提供不同規(guī)格的打印標(biāo)簽下載服務(wù)。標(biāo)簽靜態(tài)文件下

26、載服務(wù)資源地址：/partner/api/public/p/static/label/download/md5auth/mail_num.pdfHTTP方式：GET可以使用瀏覽器直接訪問該資源，md5auth的生成方式是對“用戶驗(yàn)證碼+運(yùn)單號”使用md5取摘要信息。此方式適用于服務(wù)器在境外的商家，直接將下載鏈接提供給國內(nèi)的工作人員，進(jìn)行標(biāo)簽下載及打印的工作。C2C商家應(yīng)先將標(biāo)簽文件下載到自己的服務(wù)器，再提供給自身客戶下載。由于該下載地址包含處理后的用戶驗(yàn)證碼，同時api服務(wù)只供商家使用，請勿將地址暴露給第三方用戶，避免由此帶來的數(shù)據(jù)風(fēng)險(xiǎn)。標(biāo)簽的格式由提交運(yùn)單信息時選擇的類型決定。批量獲取標(biāo)簽服

27、務(wù)資源地址：/partner/api/public/p/print/batchHTTP方式：POST傳入?yún)?shù)：LN000000005CNLN000000006CNLN000000007CN返回值：international_eub_us_1.1successV04/partner/sample/batch/c5abaa6096f44be08150d16b9c3f4e83.zip可以使用返回值中的URL進(jìn)行標(biāo)簽下載。該服務(wù)具有兩個版本：1.0版的用戶，使用該服務(wù)可以自定義批量生成的格式，直接在URL后加參數(shù)a4或4_6，默認(rèn)生成44標(biāo)簽。1.1版的用戶，批量打印服務(wù)生成標(biāo)簽的格式由提交運(yùn)單時定義

28、的類型決定，不支持自定義參數(shù)，后續(xù)版本的生成速度快于1.0版。（建議使用1.1版）目前該接口的版本為最終版，后續(xù)將不做維護(hù)與升級。批量獲取標(biāo)簽服務(wù)（增強(qiáng)版）資源地址：/partner/api/public/p/print/downloadLabelsHTTP方式：POST傳入?yún)?shù)：011LN000000005CNCX000000006CNLN000000007CN返回值：international_eub_us_1.1successV04/partner/sample/batch/c5abaa6096f44be08150d16b9c3f4e83.zipCX000000006CN 不支持A4格式

29、的標(biāo)簽。url:標(biāo)簽的下載地址。description：對不符合要求的郵件的一些描述。入?yún)⒁?guī)范說明：printcodestring（00|01|03）標(biāo)簽要求的的打印格式，00表示A4，01表示44標(biāo)簽，03表示46標(biāo)簽filetypeinteger0|1下載文件的文件類型，0標(biāo)示pdf文件，1標(biāo)示zip文件，默認(rèn)為0如果printcode參數(shù)沒有填寫，批量打印服務(wù)生成標(biāo)簽的格式由提交運(yùn)單時定義的類型決定，并且filetype參數(shù)會被忽略，直接返回一個zip文件。附錄附錄一：集成及用戶權(quán)限驗(yàn)證方法系統(tǒng)間對接使用http協(xié)議，雙方聯(lián)調(diào)前，我方會為客戶設(shè)置使用的版本信息和驗(yàn)證碼，用戶方每次發(fā)起ht

30、tp請求時，需要在http header部填入兩個屬性：version及authenticate，version對應(yīng)版本信息，當(dāng)前版本號為：international_eub_us_1.1authenticate對應(yīng)用戶的驗(yàn)證碼，也就是客戶從shippingtool獲取到的授權(quán)碼。附錄二：國家和地區(qū)名稱以及郵編規(guī)則中文名稱簡稱全稱郵編規(guī)則美國USUNITED STATES OF AMERICA必填項(xiàng)，5數(shù)字，如：12345；或5數(shù)字+短橫線+4數(shù)字，如：12345-1234澳大利亞AUAUSTRALIA必填項(xiàng)，4位數(shù)字，如：1234加拿大CACANADA必填項(xiàng)，字母+數(shù)字+字母+空格+數(shù)字+字

31、母+數(shù)字，如：a1B 2C3法國FRFRANCE必填項(xiàng)，5位數(shù)字，如：12345英國GBUNITED KINGDOM必填項(xiàng)，2-4位數(shù)字或字母+空格+3位數(shù)字或字母，如：1a2c 33d俄羅斯RURUSSIA必填項(xiàng)，6位數(shù)字，如：123456以色列ILISRAEL 必填項(xiàng)，格式如5位數(shù)字，7位數(shù)字或5位數(shù)字+4位數(shù)字，如：12345；或1234567；或12345-1234烏克蘭UAUKRAINE必填項(xiàng)，5位數(shù)字，如：12345沙特SAKINGDOM OF SAUDI ARABIA必填項(xiàng)，格式如5位數(shù)字，7位數(shù)字或5位數(shù)字+4位數(shù)字，如：12345；或1234567；或12345-1234臺灣TWTAIWAN必填項(xiàng)，5位數(shù)字，如：12345香港HKHONG KONG沒有郵編,不用填寫日本JPJAPAN必填項(xiàng)，3位數(shù)字+短