国际邮政包裹查询网

查询API接口技术文档

http://www.sao.cn

一、接口功能

输入国际邮包单号，输出邮包的最新事件，投递状态。
采用http请求方式，支持xml、json、base64、txt、map、jsonp等六种数据类型的返回。

  备注：
  1. 返回结果每天都会更新，建议不要cache数据，以免引起错误。
  2. 建议每天实时调用本接口数据来进行目标系统的邮包投递信息的更新。

二、接口使用

（1）接口概述

a. 邮包查询主接口:

http://api.sao.cn/track

b. 文字翻译辅助接口
http://api.sao.cn/translate

本API的正式域名为：api.sao.cn；

（2）接口统一请求方式

采用HTTP请求方式。 GET, POST均可以。

（3）邮包查询输入参数说明

参数名称	是否必须	类型	描述
mailNo	必须	string	跟踪查询的邮包单号, (不区分大小写)
type	选填	string	返回的数据类型。默认是Json 所有类型: xml、json、base64、txt、map、jsonp_xxx、callback_xxx (xxx是任意名字)
timeout	选填	string	查询的超时值, 单位秒，默认是:50秒
mailType	选填	string	邮包单号的类型 (具体请看邮件类型对照表)
lang	选填	string	邮包查询状态语言,目前支持: 中文和英文, 分别是 CN 和EN 。(注意数据部分并发都是中英文的)，但可以调用翻译接口作转换。
srcId	选填	string	邮包单号发件地 (具体请看国家地区对照表)
dstId	选填	string	邮包单号目的地 (具体请看国家地区对照表)
from	选填	string	接口使用方身份代码标识 (标明调用者身份名称)

（4）邮包查询请求示例

(1). 返回JSON数据

http://api.sao.cn/track?mailNo=RR040981615CR

(2). 返回XML数据

http://api.sao.cn/track?mailNo=RR040981615CR&type=xml

(3). 返回TXT文本

http://api.sao.cn/track?mailNo=RR040981615CR&type=txt

（5）邮包查询输出参数说明

参数名称	是否必有	类型	描述
mailNo	是	string	跟踪查询的邮包单号
mailType	是	string	邮包的类型。具体请参考（邮包分类编码对照表）
lang	是	string	邮包查询状态语言,目前支持: 中文和英文, 分别是 CN 和EN 。
mstatus	是	string	邮包的状态。具体请参考（邮包状态编码对照表）
mailStatus	是	string	邮包的状态描述。具体请参考（邮包状态编码对照表）
qstatus	是	string	查询的状态。具体请参考（查询状态编码对照表）
queryStatus	是	string	查询的状态描述。具体请参考（查询状态编码对照表）
waittime	是	string	查询耗时。单位毫秒
srcId	是	string	发件地国家/地区编码。具体请参考（国家地区编码对照表）
srcName	是	string	发件地国家/地区名称。具体请参考（国家地区编码对照表）
dstId	是	string	目的地国家/地区编码。具体请参考（国家地区编码对照表）
dstName	是	string	目的地地国家/地区名称。具体请参考（国家地区编码对照表）
lastEvent	否	event	最新一条邮包事件
srcEvent	否	event	发件地邮包事件
dstEvent	否	event	目的地邮包事件
srcLink	否	string	发件点邮政网站
dstLink	否	string	目的地邮政网站
step	是	string	无关联，(请略)
srcMode	是	string	无关联，(请略)
dstMode	是	string	无关联，(请略)

输出参数Event说明

参数名称	是否必须	类型	描述
datetime	否	string	邮包事件的发生时间日期(yyyy-MM-dd) + 时间
content	是	string	邮包事件的内容描述
location	否	string	邮包事件的发生地点

（6）邮包查询输出示例

a.邮包查询返回XML示例

b.邮包查询返回JSON示例

c.邮包查询返回TXT示例

d.邮包查询返回Map示例

e.邮包查询返回Base64示例

f.邮包查询返回JSONP示例

如传入参数type=jsonp_mailinfo

则返回 var jsonp_mailinfo = {JSON数据} ;

mailinfo是任意的名字

g.邮包查询返回CallBack示例

如传入参数type=callback_fuc

则返回 callback_fuc( {JSON数据} ) ;

fuc是任意的名字

（7）文字翻译输入参数说明

参数名称	是否必须	类型	描述
text	必须	string	带翻译的文本, 采用UTF-8编码提交
from	选填	string	源语言种类, 默认是auto, 自动检测
lang	必须	string	目的语言语种

（8）文字翻译请求示例

(a). 返回Txt数据

http://api.sao.cn/translate?text=you&from=EN&lang=zh-CN

（9）文字翻译输出参数说明

(a) 直接输入翻译后的文本,采用UTF-8编码。

三、接口编码对照表

（1）邮包类型编码对照表

编码代号	中文名称	英文名称	描述
REG	挂号信	Registered	邮包类型是挂号信,单号多数以R开头的。
EMS	快递EMS	Speedpost	邮包类型是快递,单号多数以E开头的。
Pack	小包裹	Parcel	邮包类型是小包裹,单号多数以C或者其它开头开头的。
DHL	DHL	DHL	国际DHL
FEDEX	FEDEX	FEDEX	国际FEDEX
TNT	TNT	TNT	国际TNT
UPS	UPS	UPS	国际UPS
EYOU	E邮宝	EYOU	国内E邮包,以CS结尾的。
GeiJu	国内给据	GeiJu	国内给据,以两个字母开头，数字结尾的。

（2）邮包状态编码对照表

编码代号	中文名称	英文名称	描述
0	查询不到	Notfound	邮包查询不到或者查询失败，无返回
1	运输途中	Shipment	邮包在运输途中，暂时无法判断具体状态，也被认为是运输途中。
2	到达待取	Arrived	邮包已经运往当地，并且快委投，或者通知收件人待取的状态。
3	成功签收	Delivered	邮包已经签收成功。
4	物件退回	Returned	邮包由于分派失败，被退回的状态。
5	运往当地	Overseas	邮包已经运往目的地国家或地区，或者通过海关的状态。

（3）查询状态编码对照表

编码代号	中文名称	英文名称	描述
0	无法识别单号	Invalid Item	邮包单号不在识别范围内
1	正常	Normal	邮包查询正常。（包括主站和子站的查询)
2	查询主站发生异常	Main Site Error	发件地国家查询，发生查询异常。
3	主站查无信息	Main Site Null	发件地国家查询，无投递信息。
4	子站查无信息	Child Site Null	目的地国家查询，无投递信息。
5	子站不能跟踪	Child Site CanNot	目的地国家无法查询。
6	无需跟踪子站	UnNeed Child Site	发件地的查询已经清楚知道邮包状态，目的地国家无需要再查询。
7	查询子站发生异常	Child Site Error	目的地国家的查询失败。
96	加入查询队列异常	Join Query Queue Error	邮包加入查询队列失败。
97	系统内部发生异常	System Error	查询系统内部发生错误，可重查试试。
98	查询队列已满，拒绝查询	Query Rejected	查询队列不能容纳更多的单号来查询。
99	查询超时	Query TimeOut	邮包查询在设定的时间内无返回，超时。

（4）国际地区编码对照表(来自sao.cn)

编码	中文名称	英文名称	编码	中文名称	英文名称
AR	阿根廷	Argentina	BI	布隆迪	Burundi
AM	亚美尼亚	Armenia	ZM	赞比亚	Zambia
AU	澳大利亚	Australia	SH	圣赫勒拿岛	Saint Helena
AT	奥地利	Austria	GM	冈比亚	Gambia
BD	孟加拉国	Bangladesh	WS	萨摩亚	Samoa
BR	巴西	Brazil	TG	多哥	Togo
BG	保加利亚	Bulgaria	XL	新西兰属土岛屿	New Zealand Other Island
KH	柬埔寨	Cambodia	ZR	扎伊尔	Zaire
CA	加拿大	Canada	SC	塞舌尔	Seychelles
CL	智利	Chile	JM	牙买加	Jamaica
CN	中国	China	HT	海地	Haiti
HR	克罗地亚	Croatia	TC	特克斯和凯科斯群岛	Turks And Caicos Islands
CY	塞浦路斯	Cyprus	GQ	赤道几内亚	Equatorial Guinea
CZ	捷克	Czech	VC	圣文森特和格林纳丁斯	Saint Vincent And The Grenadines
DK	丹麦	Denmark	TK	托克劳	Tokelau
FI	芬兰	Finland	TZ	坦桑尼亚	Tanzania
FR	法国	France	NR	瑙鲁	Nauru
DE	德国	Germany	AQ	南极洲	Antarctica
GR	希腊	Greece	ET	埃塞俄比亚	Ethiopia
IS	冰岛	Iceland	PF	法属玻利尼西亚	Polynesia
ID	印尼	Indonesia	BS	巴哈马	Bahamas
IN	印度	India	BM	百慕大	Bermuda
IE	爱尔兰	Ireland	NE	尼日尔	Niger
IL	以色列	Israel	BJ	贝宁	Benin
JP	日本	Japan	ST	圣多美和普林西比	Sao Tome And Principe
JO	约旦	Jordan	VA	梵蒂冈	Vatican City
KR	韩国	Korea	GU	关岛	Guam
MT	马耳他	Malta	FX	法属美特罗波利坦	France Metropolitan
MY	马来西亚	Malaysia	LC	Sant Lucia	Saint Lucia
MX	墨西哥	Mexico	NA	纳米比亚	Namibia
NZ	新西兰	New Zealand	DO	多米尼加共和国	Dominican Republic
NO	挪威	Norway	NF	诺福克	Norfolk
PK	巴基斯坦	Pakistan	MK	马其顿	Macedonia
PT	葡萄牙	Portugal	XC	海峡群岛	Channel Islands
QA	卡塔尔	Qatar	MW	马拉维	Malawi
RO	罗马尼亚	Romania	BB	巴巴多斯岛	Barbados
SG	新加坡	Singapore	VI	美属维尔京群岛	Vigin Islands
SK	斯洛伐克	Slovakia	UM	美国本土外小岛屿	United States Minor Outlying Islands
ES	西班牙	Spain	SN	塞内加尔	Senegal
CH	瑞士	Switzerland	SZ	斯威士兰	Swaziland
TW	台湾	Taiwan	TF	法属南部领土	French Southern Territories
TH	泰国	Thailand	VE	委内瑞拉	Venezuela
TN	突尼斯	Tunisia	ME	黑山	Montenegro
TR	土耳其	Turkey	WF	瓦利斯群岛和富图纳群岛	Wallis And Futuna Islands
AE	阿联酋	United Arab Emirates	KN	圣基茨和尼维斯	Saint Kitts And Nevis
UY	乌拉圭	Uruguay	BV	布维岛	Bouvet Island
US	美国	America	CI	科特迪瓦	Cote D'ivoire
EE	爱沙尼亚	Estonia	RS	塞尔维亚	Serbia
RU	俄罗斯	Russia	SR	苏里南	Surinam
BY	白俄罗斯	White Russia	VU	瓦努阿图	Vanuatu
BA	波黑	Bosnia and Herzegovina	TV	图瓦卢	Tuvalu
PL	波兰	Poland	XF	科西嘉岛	Corsica
EC	厄瓜多尔	Ecuador	HM	赫德岛和麦克唐岛	Heard Island And Mcdonald Islands
KZ	哈萨克斯坦	Kazakstan	MQ	马提尼克	Martinique
LV	拉脱维亚	Latvia	BT	不丹	Bhutan
LB	黎巴嫩	Lebanon	MS	蒙特塞拉特岛	Montserrat
LT	立陶宛	Lithuania	MR	毛里塔尼亚	Mauritania
LU	卢森堡	Luxemburg	PG	巴布亚新几内亚	Papua New Guinea
PE	秘鲁	Peru	LS	莱索托	Lesotho
SE	瑞典	Sweden	MG	马达加斯加	Madagascar
SA	沙特阿拉伯	Saudi Arabia	DJ	吉布提	Djibouti
SI	斯洛文尼亚	Slovenia	CC	科科斯群岛	Cocos Islands
UA	乌克兰	Ukraine	XD	阿森松	Ascension
HU	匈牙利	Hungary	SO	索马里	Somalia
IT	意大利	Italy	CV	佛得角群岛	Cape Verde Island
AF	阿富汗	Afghanistan	PW	帕劳群岛	Palau
BO	玻利维亚	Bolivia	GI	直布罗陀	Gibraltar
AZ	阿塞拜疆	Azerbaijan	XJ	巴利阿里群岛	Balearic Islands
BE	比利时	Belgium	DM	多米尼克	Dominica
CR	哥斯达尼加	Costa Rica	MC	摩纳哥	Monaco
HK	香港	Hong Kong	XE	加沙及汗尤尼斯	Gaza And Khan Yunis
MA	摩洛哥	Morocco	BW	博茨瓦纳	Botswana
NG	尼日利亚	Nigeria	XG	北非西班牙属土	Spanish Territories Of N. Africa
NL	荷兰	Holand	GS	南乔治亚岛和南桑德韦奇岛	South Georgia And The South Sandwich Is.
GH	加纳	Ghana	MH	马绍尔群岛	Marshall Islands
PH	菲律宾	Philippines	TP	东帝汶	East Timor
GL	格陵兰	Greenland	FM	密克罗尼西亚	Micronesia
KG	吉尔吉斯	Kirghizia	KI	基里巴斯	Kiribati
PY	巴拉圭	Paraguay	XI	马德拉	Madeira
XO	科索沃	Kosovo	ER	厄立特里亚	Eritrea
BL	巴勒斯坦	Palestine	UG	乌干达	Uganda
OM	阿曼	Oman	GP	瓜德罗普岛	Guadeloupe
EG	埃及	Egypt	GF	法属圭亚那	French Guiana
VN	越南	Viet Nam	CF	中非共和国	Central Africa
MV	马尔代夫	Maldives	CX	圣诞岛	Christmas Island
ZA	南非	South Africa	TD	乍得	Chadian
MO	中国澳门	Macao	AG	安提瓜和巴布达	Antigua And Barbuda
IQ	伊拉克	Iraq	ZW	津巴布韦	Zimbabwe
KP	北朝鲜	North Korea	HN	洪都拉斯	Honduras
DZ	阿尔及利亚	Algeria	XB	特里斯坦	Tristan Da Cunha
UZ	乌兹别克斯坦	Uzbekistan	SD	苏丹	Sudan
TJ	塔吉克斯坦	Tadzhikistan	PM	圣皮埃尔和密克隆群岛	Saint Pierre And Miquelon
BN	文莱	Brunei	KE	肯尼亚	Kenya
LY	利比亚	Libya	VG	英属维尔京群岛	Virgin Islands
CO	哥伦比亚	Colombia	PA	巴拿马	Panama
KW	科威特	Kuwait	NC	新喀里多尼亚	New Caledonia
MN	蒙古	Mongolia	FO	法罗群岛	Faroe Islands
LA	老挝	Laos	SB	所罗门群岛	Solomon
MM	缅甸	Burma	EH	西撒哈拉	Western Sahara
GE	格鲁吉亚	Georgia	CU	古巴	Cuba
IR	伊朗	Iran	TT	特立尼达和多巴哥	Trinidad And Tobago
SY	叙利亚	Syria	XM	威克岛	Wake Island
AL	阿尔巴尼亚	Albania	FJ	斐济	Fiji
GB	英国	United Kingdom	MZ	莫桑比克	Mozambique
PR	波多黎各	Porto Rico	ML	马里	Mali
MD	摩尔多瓦	Moldova	GD	格林纳达	Grenada
NP	尼泊尔	Nepal	CK	库克群岛	Cook Island
SV	萨尔瓦多	Salvador	CM	喀麦隆	Cameroon
RE	留尼旺	Reunion	AN	荷属安的列斯群岛	Netherlands Antilles
GA	加蓬	Gabon	SM	圣马力诺	San Marino
SJ	斯匹次卑尔根群岛	Spitsbergen	BF	布基纳法索	Burkina Faso
NU	纽埃	Niue	MU	毛里求斯	Mauritius
LK	斯里兰卡	Srilanka	GT	危地马拉	Guatemala
MP	马里亚纳群岛	Mariana	XH	亚速尔	Azores
TO	汤加	Tonga	AS	美属萨摩亚	American Samoa
LI	列支敦士登	Liechtenstein	LR	利比里亚	Liberia
YU	南斯拉夫	Yugoslavia	GY	圭亚那	Guyana
CG	刚果	Congo	SL	塞拉利昴	Sierra Leone
AI	安圭拉	Anguilla	FK	福克兰群岛	Falkland Island
GN	新几内亚	Guinea	YT	马约特岛	Mayotte
XK	加罗林群岛	Caroline Islands	AW	阿鲁巴岛	Aruba
KM	科摩罗	Comoros	NI	尼加拉瓜	Nicaragua
KY	开曼群岛	Cayman Islands	AD	安道尔共和国	Andorra
BH	巴林	Bahrain	RW	卢旺达	Rwanda
YE	也门	Yemen	AO	安哥拉	Angola
BZ	伯利兹	Belize	TM	土库曼斯坦	Turkmenistan
GW	几内亚	Guinea-bissau

（5）语言编码对照表(来自sao.cn)

编码	中文名称	英文名称
AUTO	自动检测	Auto Detect
EN	英语	English
ZH-CN	中文(简体)	Chinese(Simplified)
ZH-TW	中文(繁体)	Chinese(Traditional)
DE	德语	German
RU	俄语	Russian
FR	法语	French
KO	韩语	Korean
PT	葡萄牙语	Portuguese
JA	日语	Japanese
ES	西班牙语	Spanish
TH	泰语	Thai
SQ	阿尔巴尼亚语	Albanian
AR	阿拉伯语	Arabic
AZ	阿塞拜疆语	Azerbaijani
GA	爱尔兰语	Irish
ET	爱沙尼亚语	Estonian
BE	白俄罗斯语	Belarusian
BG	保加利亚语	Bulgarian
IS	冰岛语	Icelandic
PL	波兰语	Polish
FA	波斯语	Persian
AF	布尔文(南非荷兰语)	Afrikaans
DA	丹麦语	Danish
TL	菲律宾语	Filipino
FI	芬兰语	Finnish
KA	格鲁吉亚语	Georgian
GU	古吉拉特语	Gujarati
HT	海地克里奥尔语	Haitian Creole
NL	荷兰语	Dutch
GL	加利西亚语	Galician
CA	加泰罗尼亚语	Catalan
CS	捷克语	Czech
HR	克罗地亚语	Croatian
LA	拉丁语	Latin
LV	拉脱维亚语	Latvian
LT	立陶宛语	Lithuanian
RO	罗马尼亚语	Romanian
MT	马耳他语	Maltese
MS	马来语	Malay
MK	马其顿语	Macedonian
NO	挪威语	Norwegian
SV	瑞典语	Swedish
SR	塞尔维亚语	Serbian
SK	斯洛伐克语	Slovak
SL	斯洛文尼亚语	Slovenian
SW	斯瓦希里语	Swahili
TR	土耳其语	Turkish
CY	威尔士语	Welsh
UK	乌克兰语	Ukrainian
IW	希伯来语	Hebrew
EL	希腊语	Greek
EU	西班牙的巴斯克语	Basque
HU	匈牙利语	Hungarian
HY	亚美尼亚语	Armenian
IT	意大利语	Italian
YI	意第绪语	Yiddish
HI	印地语	Hindi
KN	印度的卡纳达语	Kannada
TE	印度的泰卢固语	Telugu
TA	印度的泰米尔语	Tamil
UR	印度乌尔都语	Urdu
ID	印尼语	Indonesian
VI	越南语	Vietnamese

四、接口报文

（1）邮包查询返回XML示例

<mailType>Registered</mailType>

<mailStatus>Arrived</mailStatus>

<queryStatus>Child Site Error</queryStatus>

<srcName>Costa Rica</srcName>

<dstName>Japan</dstName>

<content>Salida de la oficina de cambio</content>

<location>CTP CERTIFICADOS</location>

</lastEvent>

<item>

<content>Depósito/ Recogida</content>

<location>CARTAGO</location>

</item>

<item>

<content>Salida de la oficina de cambio</content>

<location>CARTAGO</location>

</item>

<item>

<content>Llegada a la oficina de cambio</content>

<location>CTP CERTIFICADOS</location>

</item>

<item>

<content>Salida de la oficina de cambio</content>

<location>CTP CERTIFICADOS</location>

</item>

</srcEvent>

略

</dstEvent>

<srcLink>http://www.correos.go.cr/rastreo/contenedor_rastreo.php</srcLink>

<dstLink>http://tracking.post.japanpost.jp/service/jsp/refi/DP311-00100.jsp?locale=en</dstLink>

</result>

（2）邮包查询返回JSON示例

{

"mailNo":"RR040981615CR",

"mailType":"Registered",

"lang":"en",

"mstatus":"2",

"mailStatus":"Arrived",

"qstatus":"1",

"queryStatus":"Normal",

"waittime":1360,

"step":2,

"srcId":"CR","srcMode":"0",

"dstId":"JP","dstMode":"0",

"srcName":"Costa Rica",

"dstName":"Japan",

"lastEvent":{"datetime":"2011-07-19 9:40","content":"Arrival at inward office of exchange - GUANGZHOU","location":"CHINA"},

"srcEvent":[

{"datetime":"2011-07-11 02:08 PM","content":"Depósito/ Recogida","location":"CARTAGO"},

{"datetime":"2011-07-11 05:36 PM","content":"Salida de la oficina de cambio","location":"CARTAGO"},

{"datetime":"2011-07-12 08:31 AM","content":"Llegada a la oficina de cambio","location":"CTP CERTIFICADOS"},

{"datetime":"2011-07-12 03:44 PM","content":"Salida de la oficina de cambio","location":"CTP CERTIFICADOS"}

"dstEvent":[

{"datetime":"2011-07-17 0:51","content":"Arrival at transit Office of Exchange - NARITA AIRPORT Branch","location":"Chiba prefecture"},

{"datetime":"2011-07-17 6:42","content":"Dispatch to overland transport - NARITA AIRPORT Branch","location":"Chiba prefecture"},

{"datetime":"2011-07-17 13:08","content":"Arrival at over land transport - TOKYO INTERNATIONAL Branch","location":"Tokyo metropolis"},

{"datetime":"2011-07-17 20:08","content":"Dispatch from outward office of exchange - TOKYO INTERNATIONAL Branch","location":"Tokyo metropolis"},

{"datetime":"2011-07-18 9:00","content":"Held by import Customs - TOKYO INTERNATIONAL Branch","location":"Tokyo metropolis"},

{"datetime":"2011-07-19 9:40","content":"Arrival at inward office of exchange - GUANGZHOU","location":"CHINA"}

"srcLink":"http://www.correos.go.cr/rastreo/contenedor_rastreo.php",

"dstLink":"http://tracking.post.japanpost.jp/service/jsp/refi/DP311-00100.jsp?locale=en"

}

（3）邮包查询返回TXT示例

查询状态：到达待取, 正常

查询详细信息：

[哥斯达尼加]投递记录

2011-07-11 02:08 PM

Depósito/ Recogida, Location:CARTAGO

2011-07-11 05:36 PM

Salida de la oficina de cambio, Location:CARTAGO

2011-07-12 08:31 AM

Llegada a la oficina de cambio, Location:CTP CERTIFICADOS

2011-07-12 03:44 PM

Salida de la oficina de cambio, Location:CTP CERTIFICADOS

[日本]投递记录

2011-07-17 0:51

Arrival at transit Office of Exchange - NARITA AIRPORT Branch, Location:Chiba prefecture

2011-07-17 6:42

Dispatch to overland transport - NARITA AIRPORT Branch, Location:Chiba prefecture

2011-07-17 13:08

Arrival at over land transport - TOKYO INTERNATIONAL Branch, Location:Tokyo metropolis

2011-07-17 20:08

Dispatch from outward office of exchange - TOKYO INTERNATIONAL Branch, Location:Tokyo metropolis

2011-07-18 9:00

Held by import Customs - TOKYO INTERNATIONAL Branch, Location:Tokyo metropolis

2011-07-19 9:40

Arrival at inward office of exchange - GUANGZHOU, Location:CHINA

查询耗时: 1.359秒

（4）邮包查询返回Map示例

（略）

（5）邮包查询返回Base64示例

(略)