国际在线产品-新版国际在线发运系统API规范(共21页)

1、PAGE PAGE 22国际(guj)在线产品-新版国际在线发运(f yn)系统API规范(gufn) TOC o 1-3 h z u HYPERLINK l _Toc421030259 1E邮宝、e包裹(bogu)、e特快、e速宝API综述(zngsh) PAGEREF _Toc421030259 h 1 HYPERLINK l _Toc421030260 1.1业务(yw)简介 PAGEREF _Toc421030260 h 1 HYPERLINK l _Toc421030261 1.2适用范围 PAGEREF _Toc421030261 h 1 HYPERLINK l _Toc42103

2、0262 1.3API功能域分类 PAGEREF _Toc421030262 h 1 HYPERLINK l _Toc421030263 1.4API开发说明 PAGEREF _Toc421030263 h 1 HYPERLINK l _Toc421030264 2E邮宝、e包裹、e特快、e速宝API规范 PAGEREF _Toc421030264 h 2 HYPERLINK l _Toc421030265 2.1SHIP（发运服务） PAGEREF _Toc421030265 h 2 HYPERLINK l _Toc421030266 2.1.1运单信息接收服务 PAGEREF _Toc42

3、1030266 h 2 HYPERLINK l _Toc421030267 2.1.2运单信息验证服务 PAGEREF _Toc421030267 h 9 HYPERLINK l _Toc421030268 2.1.3运单信息取消服务 PAGEREF _Toc421030268 h 10 HYPERLINK l _Toc421030269 2.1.4运单信息查询服务 PAGEREF _Toc421030269 h 10 HYPERLINK l _Toc421030270 2.2TRACK（跟踪信息服务） PAGEREF _Toc421030270 h 11 HYPERLINK l _Toc42

4、1030271 2.2.1实时跟踪信息查询 PAGEREF _Toc421030271 h 11 HYPERLINK l _Toc421030272 2.3RATE(费率服务) PAGEREF _Toc421030272 h 11 HYPERLINK l _Toc421030273 2.3.1国际E邮宝费率计算 PAGEREF _Toc421030273 h 11 HYPERLINK l _Toc421030274 2.4Address(地址服务) PAGEREF _Toc421030274 h 12 HYPERLINK l _Toc421030275 2.4.1国内地址行政区划查询 PAGE

5、REF _Toc421030275 h 12 HYPERLINK l _Toc421030276 2.5LABEL(标签服务) PAGEREF _Toc421030276 h 13 HYPERLINK l _Toc421030277 2.5.1标签静态文件下载服务 PAGEREF _Toc421030277 h 13 HYPERLINK l _Toc421030278 2.5.2批量获取标签服务 PAGEREF _Toc421030278 h 14 HYPERLINK l _Toc421030279 2.5.3批量获取标签服务（增强版） PAGEREF _Toc421030279 h 15 H

6、YPERLINK l _Toc421030280 3附录 PAGEREF _Toc421030280 h 16 HYPERLINK l _Toc421030281 3.1附录一：集成及用户权限验证方法 PAGEREF _Toc421030281 h 16 HYPERLINK l _Toc421030282 3.2附录二：国家和地区名称以及邮编规则 PAGEREF _Toc421030282 h 16 HYPERLINK l _Toc421030283 3.3附录三：澳大利亚-州列表 PAGEREF _Toc421030283 h 18 HYPERLINK l _Toc421030284 3.4

7、附录四：版本信息更新记录 PAGEREF _Toc421030284 h 18E邮宝、e包裹(bogu)、e特快、e速宝API综述(zngsh)业务(yw)简介E邮宝、E包裹、E特快、E速宝API提供在线的运单生成、标签打印、全程跟踪等信息服务，覆盖运单的完整生命周期。适用范围具备一定软件开发能力并拥有自建订单系统的大中小型B2C、C2C商家，可根据自身情况，进行个性化的开发，以达到API系统对接的目的。API基于HTTP协议实现，需要双方系统能够通过internet互联，并使用http方式进行通讯。本文档描述不涉及具体的开发语言，集成过程可使用合适的编程技术，实现基于http的数据交换方式。

8、API功能域分类API数量较多，在后续建设过程中可能不断增加，但总体可划分几个域进行完善和扩充：SHIP(发运服务)、TRACK（跟踪信息服务）、RATE（费率服务）、ADDRESS（地址服务）、LABEL（标签服务）。API开发说明接口入网参数version（版本号）和authenticate（授权码）在一些接口是必填项，具体请参照 HYPERLINK l _附录一：集成及用户权限验证方法 附录一：集成及用户权限验证方法如果您在开发中出现：商品名称填写中文，但返回错误还是提示“商品中文名称不能为空，且必须包含至少2个汉字”时，请检查在调用api接口时所用的编码方式必须为UTF-8。E邮宝、e

9、包裹(bogu)、e特快、e速宝API规范(gufn)SHIP（发运(f yn)服务）发运服务域包含与运单信息相关的服务，主要包括运单信息接收服务、运单信息验证服务、运单信息取消服务、运单信息查询服务。运单信息接收服务资源地址：/partner/api/public/p/order/HTTP方法：POSTE邮宝、E包裹、E特快、E速宝(永兴专线)传送内容：XML格式的订单信息，示例：SO123123100deve360000000000000011falseAbandoned1232011-03-01T22:22:222011-03-11T02:22:1101Wang Lin100055213

10、12311123333333313CN441402441402441402TeamsunLotus StreetmailTom.k100051111111212-222-0111UNITED STATES OF AMERICALASan FranciscoSt.Lotus Street王大琳100067123456-908-0981233333333333CN441402441402441402莲花池东路(dn l)126号bin 盒子box10.11CN12345678电脑(dinno)computer 2unit0.2320.34CNComputer Machine12345678返回值：

11、XML格式(g shi)文档，示例：LN334458969CNE速宝（赛诚专线(zhunxin)）传送内容：XML格式的订单信息，示例：CSDN1111331111000000000000011falseReturned1232011-03-01T22:22:222011-03-11T02:22:11客户自定义信息1客户自定义信息2Wang Lin10005521312311123333333313CN441402441402441402TeamsunLotus StreetmailMichael K Bristow23043111111212-222-0111AUVIC Roeland Pa

12、rk123123123baigongxiaobushijia王大琳100067123456-908-0981233333333333CN441402441402441402莲花池东路(dn l)126号bin3043AUSTRALIAVICTullamarineStarTrack International,38 Annandale Road电脑22Kansas 2xxx0.120.34CNorderid注：1、e速宝赛诚专线的退货地址，国家必填，如果省、市、县、详细地址都不填写则取默认地址。默认全地址为：StarTrack International,38 Annandale Road Tu

13、llamarine VIC 3043 AUS退回地址：StarTrack International,38 Annandale Road退回地址城市：Tullamarine退回地址省份：VIC退回(tuhu)地址邮编：3043退回(tuhu)地址国家：AUS2、澳大利亚(o d l y)-州为固定值，详见 HYPERLINK l _澳大利亚-州列表 附录三。返回值：XML格式文档，示例：A000000000001入参规范说明：订单主体信息orderidstring4-32订单标识，此标识由使用者提供，应为订单在使用者系统中的唯一标识。如使用者订单需拆分多个邮包（包裹），时，此标识可重复。ope

14、rationtypeinteger0|1|2|3业务类型（默认0，如果不填或者没有该节点就取默认值）0:e 邮宝1:e 包裹2:e 特快3:e 速宝producttypeinteger1|2|3|4产品种类（默认0）2:国际包裹签收3:赛程专线4:永兴专线如果选择 e 包裹业务：必填2如果选择 e 速宝业务：必填3或4 customercodestring4-64使用者系统中的客户编码。即实际提交 此订单的用户在使用者系统中的身份标 识。中邮物流平台会依据此信息项对客 户进行区分，此项不能为空，但使用者 可提供加密或者编码后的客户身份标 识。vipcodestring14使用者如果拥有 EMS

15、 大客户代码， 应填入此字段clcttypeinteger0|1揽收类型，1上门揽收或0用户自送podbooleanfalse|true电子签收（目前默认为false）untreadstringAbandoned|AND I ASSURE TO PAY FOR THE CHARGE OF RETURN|Returned退回类型，默认为ReturnedAbandoned: 丢弃ANDIASSURETOPAYFORTHECHARGEOFRETURN: 保证支付退回的邮件Returned: 退回volweightInteger体积重量=长（单位：厘米）宽（单位：厘米）高（单位：厘米）/6000，客户

16、需填写长、宽、高及体积重量startdatedate2011-03-01T22:22:22起始预约时间enddatedate2011-03-01T22:22:22终止预约时间remarkstring0-128备注sku1string0-1024客户自定义信息1sku2string0-256客户自定义信息2barcodeString0-64订单条码，如果需要打印出标志该订单的条码，就填写该值printcodeChar（00|01|03）该订单要求的的打印格式，00表示A4，01表示44标签，03表示46标签，默认值是01国内名址信息(寄件人地址sender、揽收地址collect)namestr

17、ing2-16姓名postcodestring6邮编phonestring6-36电话mobilestring13手机countrystring固定为CN国家provincestring6省份代码citystring6城市代码countystring6区县代码companystring0-128公司streetstring8-256街道emailstring0-128电子邮箱国外名址信息（收件人信息receiver）namestring1-256姓名（英文）postcodestring0-16邮编请查看附录二： HYPERLINK l _附录二：国家和地区名称以及邮编规则 国家和地区名称以及邮

18、编规则注：必须按照附录中规则要求验证phonestring0-50电话mobilestring0-50手机countrystring1-24国家或地区名称请查看附录二： HYPERLINK l _附录二：国家和地区名称以及邮编规则 国家和地区名称以及邮编规则注：必须填写附录的简称或全称(不区分大小写)provincestring1-128省份(澳大利亚e速宝赛诚专线必须采用附录三的州)citystring1-128城市companystring0-128公司（英文）streetstring1-256街道（英文）street_extra_1string1-256如果地址出现多行时使用这两个字段来

19、存储street_extra_2string1-256emailstring0-128电子邮箱货品信息cnnamestring1-64中文名称(必填，至少包含2个汉字)ennamestring1-128英文名称countinteger1-99999数量unitstring0-16单位weightfloat0.001-9999.000重量，千克（三位小数），该重量是单个商品重量*数量delcarevaluemoney0.01-99999.00报关价格(两位小数)，该价格是单个商品的报关价格*数量originstring默认为CN原寄地，固定填写CNdescriptionstring064描述（英

20、文）taxationidstring2-101、普通税则号：选填项，填写2-8位的数字2、e速宝赛诚专线：选填项， 2-10位数字3、e速宝永兴专线：必填项，6-10位数字sellurlstring0-200销售链接PS:各个业务(yw)下开通的国家或者地区路向：1.e 邮宝：美国、澳大利亚、加拿大、法国(f u)、英国、俄罗斯、以色列、乌克兰、沙特、巴西(b x)德国、挪威2.e 包裹(bogu)：美国3.e 特快：澳大利亚(o d l y)、加拿大、台湾、香港、日本、法国、韩国、巴西、西班牙、乌克兰、新加波、荷兰、俄罗斯、白俄罗斯、英国、德国4.e 速宝（赛诚专线(zhunxin)）：澳大

21、利亚5.e速宝（永兴专线）：德国、美国、法国、英国、荷兰、西班牙、意大利、比利时、卢森堡、爱尔兰、丹麦、希腊、葡萄牙、瑞典、芬兰、奥地利、塞浦路斯、捷克共和国、爱沙尼亚、匈牙利、拉脱维亚、立陶宛、马耳他、波兰、斯洛伐克、斯洛文尼亚、罗马尼亚、保加利亚、克罗地亚运单信息验证服务资源地址：/partner/api/public/p/validateHTTP方法：POST传送内容：与运单接收服务相同返回内容：XML文档成功示例：. success V00 验证成功失败示例：. error V01 错误信息该服务旨在为集成过程中出现的格式、字段类型、字段长度等问题提供帮助，对于运单信息的合规性进行判断

22、和说明。服务返回结果仅供开发人员参考，因此在正式运行后，不需要每个运单都调用此服务，只在出现问题后，使用此服务排查原因。运单信息取消服务资源地址：/partner/api/public/p/order/mail_numHTTP方法：DELETE该服务(fw)用于将运单信息标记为无效。运单(yn dn)信息查询服务资源(zyun)地址：/partner/api/public/p/order/mail_numHTTP方法：GET返回内容：SO1231231deve360000000000000011falseAbandoned1232011-03-01T22:22:22.在order节点下增加元素

23、,表示实收资费、实收重量。TRACK（跟踪信息服务）跟踪服务域围绕运单的流转信息提供服务。主要包括实时跟踪信息的查询：实时跟踪信息查询资源地址：/partner/api/public/p/track/query/cn|en/mail_numHTTP方式：GET返回结果：XML格式文档 中英文返回2011-12-01 11:13:49南京收寄en|cn表示选用(xunyng)en或cn任意值，en为英文信息，cn为中文信息。RATE(费率服务(fw)提供运单(yn dn)费率的估算服务。国际E邮宝费率计算资源地址：/partner/api/public/p/rate/epacket/HTTP方式

24、：POST传入参数：01200USCN650000返回值：01200USCN650000130.0备注信息返回值为请求报文信息， 再加估算费用 （以人民币计费，单位为元） 和 remark （备注信息） 。入参规范：operationtypeinteger业务类型 （默认 0， 如果不填或者没有该节点就取默认值）0：e 邮宝1：e包裹2：e特快3：e速宝weightdouble重量信息，单位为克recvcountrystring国家或地区请查看附录二： HYPERLINK l _附录二：国家和地区名称以及邮编规则 国家和地区名称以及邮编规则sendcountrystring原寄国家简称，中国为

25、 CNsdprovstring省级代码说明：目前暂不支持(zhch)国际包裹邮件资费查询。Address(地址(dzh)服务)地址服务(fw)域提供国内、国外标准地名或编码的查询：国内地址行政区划查询资源地址：/partner/api/public/p/area/cn/province/list /partner/api/public/p/area/cn/city/list/no /partner/api/public/p/area/ cn/county/list/noHTTP方式：GET示例：获取国内省级行政区划：/partner/api/public/p/area/cn/province/

26、list北京天津河北省山西省内蒙古自治区获取省份内城市行政区划：/partner/api/public/p/area/cn/city/list/130000石家庄市(sh ji zhun sh)唐山市秦皇岛市(qn hun do sh)邯郸市邢台市保定市张家口市(zhn ji ku sh)承德市沧州市廊坊市衡水市获取城市下辖区县列表：/partner/api/public/area/p/cn/county/list/130100长安区桥东区LABEL(标签服务)提供不同规格的打印标签下载服务。标签静态文件下载服务资源地址：/partner/api/public/p/static/label/d

27、ownload/md5auth/mail_num.pdfHTTP方式：GET可以使用浏览器直接访问该资源，md5auth的生成方式是对“用户验证码+运单号”使用md5取摘要信息。此方式适用于服务器在境外的商家，直接将下载链接提供给国内的工作人员，进行标签下载及打印的工作。C2C商家应先将标签文件下载到自己的服务器，再提供给自身客户下载。由于该下载地址包含处理后的用户验证码，同时api服务只供商家使用，请勿将地址暴露给第三方用户，避免由此带来的数据风险。标签的格式由提交运单信息时选择的类型决定。批量(p lin)获取标签服务资源(zyun)地址：/partner/api/public/p/pri

28、nt/batchHTTP方式(fngsh)：POST传入参数：LN000000005CNLN000000006CNLN000000007CN返回值：international_eub_us_1.1successV04/partner/sample/batch/c5abaa6096f44be08150d16b9c3f4e83.zip可以使用返回值中的URL进行标签下载。该服务具有两个版本：1.0版的用户，使用该服务可以自定义批量生成的格式，直接在URL后加参数a4或4_6，默认生成44标签。1.1版的用户，批量打印服务生成标签的格式由提交运单时定义的类型决定，不支持自定义参数，后续版本的生成速度

29、快于1.0版。（建议使用1.1版）目前该接口的版本为最终版，后续将不做维护与升级。批量获取标签服务（增强版）资源地址：/partner/api/public/p/print/downloadLabelsHTTP方式：POST传入参数：011LN000000005CNCX000000006CNLN000000007CN返回值：international_eub_us_1.1successV04/partner/sample/batch/c5abaa6096f44be08150d16b9c3f4e83.zipCX000000006CN 不支持(zhch)A4格式的标签。url:标签的下载(xi z

30、i)地址。description：对不符合要求的邮件(yujin)的一些描述。入参规范说明：printcodestring（00|01|03）标签要求的的打印格式，00表示A4，01表示44标签，03表示46标签filetypeinteger0|1下载文件的文件类型，0标示pdf文件，1标示zip文件，默认为0如果printcode参数没有填写，批量打印服务生成标签的格式由提交运单时定义的类型决定，并且filetype参数会被忽略，直接返回一个zip文件。附录(fl)附录一：集成及用户权限(qunxin)验证方法系统间对接使用http协议，双方(shungfng)联调前，我方会为客户设置使用的

31、版本信息和验证码，用户方每次发起http请求时，需要在http header部填入两个属性：version及authenticate，version对应版本信息，当前版本号为：international_eub_us_1.1authenticate对应用户的验证码，也就是客户从shippingtool获取到的授权码。附录二：国家和地区名称以及邮编规则中文名称简称全称邮编规则美国USUNITED STATES OF AMERICA必填项，5数字，如：12345；或5数字+短横线+4数字，如：12345-1234澳大利亚AUAUSTRALIA必填项，4位数字，如：1234加拿大CACANADA必填

32、项，字母+数字+字母+空格+数字+字母+数字，如：a1B 2C3法国FRFRANCE必填项，5位数字，如：12345英国GBUNITED KINGDOM必填项，2-4位数字或字母+空格+3位数字或字母，如：1a2c 33d俄罗斯RURUSSIA必填项，6位数字，如：123456以色列ILISRAEL 必填项，格式如5位数字，7位数字或5位数字+4位数字，如：12345；或1234567；或12345-1234乌克兰UAUKRAINE必填项，5位数字，如：12345沙特SAKINGDOM OF SAUDI ARABIA必填项，格式如5位数字，7位数字或5位数字+4位数字，如：12345；或1234567；或12345-1234台湾TWTAIWAN必填项，5位数字，如：12345香港HKHONG KONG没有邮编,不用填写日本JPJAPAN必填项，3位数字+短横线+4位数字，如：123-1234韩国KRK