国际在线产品-新版国际在线发运系统API规范

国际在线产品-新版国际在线发运系

统API规范

1

1

2

3

E邮宝、e包裹、e特快、e速宝API综述 ........................................................................... 1 1.1 业务简介 ....................................................................................................................... 1 1.2 适用范围 ....................................................................................................................... 1 1.3 API功能域分类 ........................................................................................................... 1 1.4 API开发说明 ............................................................................................................... 1 E邮宝、e包裹、e特快、e速宝API规范 ........................................................................... 1 2.1 SHIP（发运服务） ...................................................................................................... 1

2.1.1 运单信息接收服务 ........................................................................................... 2 2.1.2 运单信息验证服务 ........................................................................................... 9 2.1.3 运单信息取消服务 ......................................................................................... 10 2.1.4 运单信息查询服务 ......................................................................................... 10 2.2 TRACK（跟踪信息服务） ....................................................................................... 11

2.2.1 实时跟踪信息查询 ......................................................................................... 11 2.3 RATE(费率服务) ........................................................................................................ 11

2.3.1 国际E邮宝费率计算 .................................................................................... 11 2.4 Address(地址服务) ..................................................................................................... 12

2.4.1 国内地址行政区划查询 ................................................................................. 12 2.5 LABEL(标签服务) ..................................................................................................... 13

2.5.1 标签静态文件下载服务 ................................................................................. 13 2.5.2 批量获取标签服务 ......................................................................................... 14 2.5.3 批量获取标签服务（增强版） ..................................................................... 15 附录......................................................................................................................................... 16 3.1 附录一：集成及用户权限验证方法 ......................................................................... 16 3.2 附录二：国家和地区名称以及邮编规则 ................................................................. 16 3.3 附录三：澳大利亚-州列表 ....................................................................................... 17 3.4 附录四：版本信息更新记录 ..................................................................................... 18

2

1 E邮宝、e包裹、e特快、e速宝API综述

1.1 业务简介

E邮宝、E包裹、E特快、E速宝API提供在线的运单生成、标签打印、全程跟踪等信息服务，覆盖运单的完整生命周期。

1.2 适用范围

具备一定软件开发能力并拥有自建订单系统的大中小型B2C、C2C商家，可根据自身情况，进行个性化的开发，以达到API系统对接的目的。API基于HTTP协议实现，需要双方系统能够通过internet互联，并使用http方式进行通讯。本文档描述不涉及具体的开发语言，集成过程可使用合适的编程技术，实现基于http的数据交换方式。

1.3 API功能域分类

API数量较多，在后续建设过程中可能不断增加，但总体可划分几个域进行完善和扩充： SHIP(发运服务)、TRACK（跟踪信息服务）、RATE（费率服务）、ADDRESS（地址服务）、LABEL（标签服务）。

1.4 API开发说明

接口入网参数version（版本号）和authenticate（授权码）在一些接口是必填项，具体请参照附录一：集成及用户权限验证方法 如果您在开发中出现：商品名称填写中文，但返回错误还是提示“商品中文名称不能为空，且必须包含至少2个汉字”时，请检查在调用api接口时所用的编码方式必须为UTF-8。

2 E邮宝、e包裹、e特快、e速宝API规范

2.1 SHIP（发运服务）

发运服务域包含与运单信息相关的服务，主要包括运单信息接收服务、运单信息验证服务、运单信息取消服务、运单信息查询服务。

1

2.1.1 运单信息接收服务

资源地址：http://shipping.ems.com.cn/partner/api/public/p/order/ HTTP方法：POST

E邮宝、E包裹、E特快、E速宝(永兴专线)传送内容：XML格式的订单信息，示例：

SO1231231 0

0

deve360 00000000000001 1 false Abandoned 123 2011-03-01T22:22:22 2011-03-11T02:22:11

01

Wang Lin 100055 2131231 1123333333313 CN 441402 441402 441402 Teamsun

2

Lotus Street mail@team.com Tom.k 10005 1111111 212-222-0111 UNITED STATES OF AMERICA LA San Francisco St. Lotus Street

王大琳 100067 123456-908-098 1233333333333 CN 441402 441402 441402 莲花池东路126号 bin@team.com

盒子 box 1 0.1 1 CN

12345678

电脑 computer 2 unit 0.23

3

20.34 CN Computer Machine 12345678 http://www.http://www.wodefanwen.com/

返回值：XML格式文档，示例：

LN334458969CN

E速宝（赛诚专线）传送内容：XML格式的订单信息，示例：

CSDN1111 3 3 1111 00000000000001 1 false Returned 123 2011-03-01T22:22:22 2011-03-11T02:22:11 客户自定义信息1 客户自定义信息2

4

Wang Lin 100055 2131231 1123333333313 CN 441402 441402 441402 Teamsun Lotus Street mail@team.com Michael K Bristow2 3043 111111 212-222-0111 AU VIC Roeland Park 123123123 baigong xiaobushijia

王大琳 100067 123456-908-098 1233333333333 CN 441402 441402 441402 莲花池东路126号 bin@team.com

5

3043

AUSTRALIA VIC Tullamarine StarTrack International,38 Annandale Road 电脑22 Kansas 2 xxx 0.1 20.34 CN orderid

http://www.http://www.wodefanwen.com/

注：

1、e速宝赛诚专线的退货地址，国家必填，如果省、市、县、详细地址都不填写则取默认地址。

默认全地址为：StarTrack International,38 Annandale Road Tullamarine VIC 3043 AUS 退回地址：StarTrack International,38 Annandale Road 退回地址城市：Tullamarine 退回地址省份：VIC 退回地址邮编：3043 退回地址国家：AUS

2、澳大利亚-州为固定值，详见附录三。

返回值：XML格式文档，示例：

A000000000001

6

入参规范说明： 订单主体信息 订单标识，此标识由使用者提供，应为订单在使用者系统中的唯一标识。如使用者订单需拆分多个邮包（包裹），时，此标识可重复。 业务类型（默认0，如果不填或者没有该节点就取默认值） 0:e 邮宝 1:e 包裹 2:e 特快 3:e 速宝 产品种类（默认0） 2:国际包裹签收 3:赛程专线 4:永兴专线 如果选择 e 包裹业务：必填2 如果选择 e 速宝业务：必填3或4 使用者系统中的客户编码。即实际提交 此订单的用户在使用者系统中的身份标 识。中邮物流平台会依据此信息项对客 户进行区分，此项不能为空，但使用者 可提供加密或者编码后的客户身份标 识。 orderid string 4-32 operationtype integer 0|1|2|3 producttype integer 1|2|3|4 customercode string 4-64 vipcode string 14 使用者如果拥有 EMS 大客户代码， 应填入此字段 clcttype pod integer boolean 0|1 false|true Abandoned|AND I ASSURE TO PAY FOR THE CHARGE OF RETURN|Returned 2011-03-01T22:22:22 2011-03-01T22:22:22 0-128 0-1024 揽收类型，1上门揽收或0用户自送 电子签收（目前默认为false） 退回类型，默认为Returned Abandoned: 丢弃 AND I ASSURE TO PAY FOR THE CHARReturned: 退回 GE OF RETURN: 保证支付退回的邮件 untread string volweight startdate enddate remark sku1

Integer date date string string 体积重量=长（单位：厘米）×宽（单位：厘米）×高（单位：厘米）/6000，客户需填写长、宽、高及体积重量 起始预约时间 终止预约时间 备注 客户自定义信息1 7

sku2 barcode string String 0-256 0-64 客户自定义信息2 订单条码，如果需要打印出标志该订单的条码，就填写该值 该订单要求的的打印格式，00表示A4，01表示 4×4标签，03表示4×6标签，默认值是01 姓名 邮编 电话 手机 国家 省份代码 城市代码 区县代码 公司 街道 电子邮箱 printcode Char （00|01|03） name phone mobile country city county street email name postcode phone mobile country province city company street street_extra_1 street_extra_2 email 货品信息 cnname enname count

string string string string string string string string string string string string string string string string string string string string string string integer 2-16 6 6-36 13 固定为CN 6 6 6 0-128 8-256 0-128 1-256 0-16 0-50 0-50 1-24 1-128 1-128 0-128 1-256 1-256 1-256 0-128 1-64 1-128 1-99999 国内名址信息(寄件人地址sender、揽收地址collect) postcode string province string company string 国外名址信息（收件人信息receiver） 姓名（英文） 邮编 请查看附录二：国家和地区名称以及邮编规则 注：必须按照附录中规则要求验证 电话 手机 国家或地区名称 请查看附录二：国家和地区名称以及邮编规则 注：必须填写附录的简称或全称(不区分大小写) 省份(澳大利亚e速宝赛诚专线必须采用附录三的州) 城市 公司（英文） 街道（英文） 如果地址出现多行时使用这两个字段来存储 电子邮箱 中文名称(必填，至少包含2个汉字) 英文名称 数量 8

unit weight delcarevalue origin description taxationid sellurl string float money string string string string 0-16 0.001-9999.000 0.01-99999.00 默认为CN 0－64 2-10 0-200 单位 重量，千克（三位小数），该重量是单个商品重量*数量 报关价格(两位小数)，该价格是单个商品的报关价格*数量 原寄地，固定填写CN 描述（英文） 1、普通税则号：选填项，填写2-8位的数字 2、e速宝赛诚专线：选填项， 2-10位数字 3、e速宝永兴专线：必填项，6-10位数字 销售链接 PS:各个业务下开通的国家或者地区路向：

1.e 邮宝：美国、澳大利亚、加拿大、法国、英国、俄罗斯、以色列、乌克兰、沙特、巴西

德国、挪威

2.e 包裹：美国

3.e 特快：澳大利亚、加拿大、台湾、香港、日本、法国、韩国、巴西、西班牙、乌克兰、新加波、荷兰、俄罗斯、白俄罗斯、英国、德国 4.e 速宝（赛诚专线）：澳大利亚 5.e速宝（永兴专线）：德国、美国、法国、英国、荷兰、西班牙、意大利、比利时、卢森堡、

爱尔兰、丹麦、希腊、葡萄牙、瑞典、芬兰、奥地利、塞浦路斯、捷克共和国、爱沙尼亚、匈牙利、拉脱维亚、立陶宛、马耳他、波兰、斯洛伐克、斯洛文尼亚、罗马尼亚、保加利亚、克罗地亚

2.1.2 运单信息验证服务

资源地址：http://shipping2.ems.com.cn/partner/api/public/p/validate HTTP方法：POST

传送内容：与运单接收服务相同 返回内容：XML文档 成功示例：

..

success V00

验证成功 失败示例：

.. error

9

V01

错误信息....

该服务旨在为集成过程中出现的格式、字段类型、字段长度等问题提供帮助，对于运单信息的合规性进行判断和说明。服务返回结果仅供开发人员参考，因此在正式运行后，不需要每个运单都调用此服务，只在出现问题后，使用此服务排查原因。

2.1.3 运单信息取消服务

资源地址：http://shipping2.ems.com.cn/partner/api/public/p/order/{mail_num} HTTP方法：DELETE

该服务用于将运单信息标记为无效。

2.1.4 运单信息查询服务

资源地址：http://shipping2.ems.com.cn/partner/api/public/p/order/{mail_num} HTTP方法：GET 返回内容：

SO1231231 deve360 00000000000001 1 false Abandoned 123 2011-03-01T22:22:22 ……………..

在order节点下增加元素,表示实收资费、实收重量。

10

2.2 TRACK（跟踪信息服务）

跟踪服务域围绕运单的流转信息提供服务。主要包括实时跟踪信息的查询：

2.2.1 实时跟踪信息查询

资源地址：http://shipping2.ems.com.cn/partner/api/public/p/track/query/{cn|en}/{mail_num} HTTP方式：GET

返回结果：XML格式文档 中英文返回

2011-12-01 11:13:49 南京 收寄 ……

{en|cn}表示选用en或cn任意值，en为英文信息，cn为中文信息。

2.3 RATE(费率服务)

提供运单费率的估算服务。

2.3.1 国际E邮宝费率计算

资源地址：http://shipping2.ems.com.cn/partner/api/public/p/rate/epacket/ HTTP方式：POST 传入参数：

0 1200

US CN 650000 返回值：

11

0 1200

US CN 650000 130.0

备注信息

返回值为请求报文信息， 再加估算费用 （以人民币计费，单位为元） 和 remark （备注信息） 。 入参规范： 业务类型 （默认 0， 如果不填 或者没有该节点就取默认值） 0：e 邮宝 1：e包裹 2：e特快 3：e速宝 重量信息，单位为克 operationtype integer weight recvcountry sendcountry sdprov double string string string 国家或地区 请查看附录二：国家和地区名称以及邮编规则 原寄国家简称，中国为 CN 省级代码 说明：目前暂不支持国际包裹邮件资费查询。

2.4 Address(地址服务)

地址服务域提供国内、国外标准地名或编码的查询：

2.4.1 国内地址行政区划查询

资源地址：http://shipping2.ems.com.cn/partner/api/public/p/area/cn/province/list http://shipping2.ems.com.cn/partner/api/public/p/area/cn/city/list/{no} http://shipping2.ems.com.cn/partner/api/public/p/area/ cn/county/list/{no} HTTP方式：GET 示例：

获取国内省级行政区划：

http://shipping2.ems.com.cn/partner/api/public/p/area/cn/province/list

12

获取省份内城市行政区划：

http://shipping2.ems.com.cn/partner/api/public/p/area/cn/city/list/130000

获取城市下辖区县列表：

http://shipping2.ems.com.cn/partner/api/public/area/p/cn/county/list/130100

2.5 LABEL(标签服务)

提供不同规格的打印标签下载服务。

2.5.1 标签静态文件下载服务

资源地址：

http://labels.ems.com.cn/partner/api/public/p/static/label/download/{md5auth}/{mail_num}.pdf

13

HTTP方式：GET

可以使用浏览器直接访问该资源，{md5auth}的生成方式是对“用户验证码+运单号”使用md5取摘要信息。

此方式适用于服务器在境外的商家，直接将下载链接提供给国内的工作人员，进行标签下载及打印的工作。C2C商家应先将标签文件下载到自己的服务器，再提供给自身客户下载。

由于该下载地址包含处理后的用户验证码，同时api服务只供商家使用，请勿将地址暴露给第三方用户，避免由此带来的数据风险。

标签的格式由提交运单信息时选择的类型决定。

2.5.2 批量获取标签服务

资源地址：http://shipping2.ems.com.cn/partner/api/public/p/print/batch HTTP方式：POST 传入参数：

LN000000005CN LN000000006CN LN000000007CN

返回值：

international_eub_us_1.1 success V04

http://labels.ems.com.cn/partner/sample/batch/c5abaa6096f44be08150d16b9c3f4e83.zip

可以使用返回值中的URL进行标签下载。 该服务具有两个版本： 1.0版的用户，使用该服务可以自定义批量生成的格式，直接在URL后加参数a4或4_6，默认生成4×4标签。

1.1版的用户，批量打印服务生成标签的格式由提交运单时定义的类型决定，不支持自定义参数，后续版本的生成速度快于1.0版。（建议使用1.1版）

目前该接口的版本为最终版，后续将不做维护与升级。

14

2.5.3 批量获取标签服务（增强版）

资源地址：http://shipping2.ems.com.cn/partner/api/public/p/print/downloadLabels HTTP方式：POST 传入参数：

01 1

LN000000005CN CX000000006CN LN000000007CN

返回值：

international_eub_us_1.1 success V04

http://labels.ems.com.cn/partner/sample/batch/c5abaa6096f44be08150d16b9c3f4e83.zip

CX000000006CN 不支持A4格式的标签。

url:标签的下载地址。

description：对不符合要求的邮件的一些描述。 入参规范说明：

标签要求的的打印格式，00表示A4，01表示 4×4标签，03表示4×6标签 下载文件的文件类型，0标示pdf文件，1标示zip文件，默认printcode string （00|01|03） filetype integer 0|1 15

为0 如果printcode参数没有填写，批量打印服务生成标签的格式由提交运单时定义的类型决定， 并且filetype参数会被忽略，直接返回一个zip文件。

3 附录

3.1 附录一：集成及用户权限验证方法

系统间对接使用http协议，双方联调前，我方会为客户设置使用的版本信息和验证码，用户方每次发起http请求时，需要在http header部填入两个属性：version及authenticate，

version对应版本信息，当前版本号为：international_eub_us_1.1

authenticate对应用户的验证码，也就是客户从shippingtool获取到的授权码。

3.2 附录二：国家和地区名称以及邮编规则

中文名称 美国 澳大利亚 加拿大 法国 英国 俄罗斯 以色列 乌克兰 沙特 台湾 香港 日本 韩国 巴西 西班牙

简称 US AU CA FR GB RU IL UA SA TW HK JP KR BR ES 全称 邮编规则 UNITED STATES OF 必填项，5数字，如：12345；或5数字+短横线+4AMERICA 数字，如：12345-1234 AUSTRALIA CANADA FRANCE UNITED KINGDOM RUSSIA ISRAEL UKRAINE 必填项，4位数字，如：1234 必填项，字母+数字+字母+空格+数字+字母+数字，如：a1B 2C3 必填项，5位数字，如：12345 必填项，2-4位数字或字母+空格+3位数字或字母，如：1a2c 33d 必填项，6位数字，如：123456 必填项，格式如5位数字，7位数字或5位数字+4位数字，如：12345；或1234567；或12345-1234 必填项，5位数字，如：12345 KINGDOM OF 必填项，格式如5位数字，7位数字或5位数字+4SAUDI ARABIA 位数字，如：12345；或1234567；或12345-1234 TAIWAN HONG KONG JAPAN KOREA BRAZIL SPAIN 必填项，5位数字，如：12345 没有邮编,不用填写 必填项，3位数字+短横线+4位数字，如：123-1234 必填项，5位数字，如：12345 必填项，5位数字+短横线+3位数字，如：12345-123 必填项，5位数字，如：12345 16

新加坡 荷兰 白俄罗斯 德国 挪威 意大利 比利时 卢森堡 爱尔兰 丹麦 希腊 葡萄牙 瑞典 芬兰 奥地利 塞浦路斯 捷克共和国 爱沙尼亚 匈牙利 拉脱维亚 立陶宛 SG NL BY DE NO IT BE LU IE DK GR PT SE FI AT SINGAPORE NETHERLANDS BELARUS DEUTSCHLAND NORWAY ITALY BELGIUM LUXEMBOURG IRELAND DENMARK GREECE PORTUGAL SWEDEN FINLAND AUSTRIA 必填项，6位数字，如：123456 必填项，4位数字+空格+2位数字或字母，如：1234 8f 必填项，6位数字，如：123456 必填项，5位数字，如：12345 必填项，4位数字 必填项，5位数字，或\位数字，或\位数字 必填项，4位数字 必填项，4位数字 没有邮编,不用填写 必填项，4位数字 必填项，3位数字+空格+2位数字，如：123 45 必填项，4数字+短横线+3数字，如：1234-567 必填项，5位数字 必填项，5位数字 必填项，4位数字 必填项，4位数字 必填项，3位数字+空格+2位数字，如：123 45 必填项，5位数字 必填项，4位数字 必填项，4位数字 必填项，5位数字，或\位数字 必填项，3位字母+空格+3位数字+空格+1位数字，如：MLH 204 2；或者3位字母+空格+4位数字，如：MLH 1234 必填项，2位数字+短横线+3位数字，如：12-345 必填项，3位数字+空格+2位数字，如：123 45 必填项，4位数字，或\位数字 必填项，6位数字 必填项，4位数字 必填项，5位数字，或\位数字 CY CYPRUS CZ CZECH REPUBLIC EE LV LT ESTONIA LATVIA LITHUANIA HU HUNGARY 马耳他 波兰 斯洛伐克 斯洛文尼亚 罗马尼亚 保加利亚 克罗地亚

MT MALTA PL SI POLAND SLOVENIA SK SLOVAKIA RO ROMANIA BG BULGARIA HR CROATIA 3.3 附录三：澳大利亚-州列表

州（英文，选择填写） NSW ACT VIC 州（中文） 新南威尔斯州 澳洲首都区 维多利亚 17

SA 南澳洲 TAS 塔斯马尼亚 QLD 昆士兰 NT 北领地 WA 西澳洲

3.4 附录四：版本信息更新记录

本文档对应api系统1.1版。

18

本文来源：https://www.bwwdw.com/article/5hzf.html