文档中心
一、订阅接口 二、推送接口 三、快递公司编码 四、demo下载 五、实时关注推送情况

快递订阅查询快递api接口技术文档

一、订阅接口

1.1 订阅请求地址

https://poll.kuaidi100.com/poll

1.2 订阅请求类型

post

1.3 订阅输入参数

请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

名称类型是否必需示例值描述
schemaStringjson返回的数据格式
Θparamparam 由其他字段拼接
└ companyStringems订阅的快递公司的编码,一律用小写字母
└ numberString1136281381675订阅的快递单号,单号的最大长度是32个字符 下载编码表格
└ fromString广东省深圳市南山区出发地城市,省-市-区,非必填,填了有助于提升签收状态的判断的准确率,请尽量提供
└ toString北京市朝阳区目的地城市,省-市-区,非必填,填了有助于提升签收状态的判断的准确率,且到达目的地后会加大监控频率,请尽量提供
└ keyString 授权码,请申请企业版获取
Θparametersparameters 附加参数信息
└- callbackurlString 回调接口的地址
└- saltStringXXXXXXXXXX签名用随机字符串
└- resultv2String1添加此字段表示打开行政区域解析功能
└- autoComString1添加此字段且将此值设为1,则表示开启智能判断单号所属公司的功能,开启后,需确保company字段为空,即只传运单号(number字段),我方收到后会根据单号判断出其所属的快递公司(即company字段)。建议只有在无法知道单号对应的快递公司(即company的值)的情况下才开启此功能。
└- interComString1添加此字段表示开启国际版,开启后,若订阅的单号(即number字段)属于国际单号,会返回出发国与目的国两个国家的跟踪信息,本功能暂时只支持邮政体系(国际类的邮政小包、EMS)内的快递公司,若单号我方识别为非国际单,即使添加本字段,也不会返回destResult元素组
└- departureCountryStringCN出发国家编码
└- departureComStringems出发的快递公司的编码
└- destinationCountryStringJP目的国家编码
└- destinationComStringjapanposten目的的快递公司的编码
└- phoneString13488888888收、寄件人的电话号码(手机和固定电话均可,只能填写一个,顺丰速运和丰网速运必填,其他快递公司选填。如座机号码有分机号,分机号无需上传。)

1.4 订阅请求参数示例

schema = json
param = {
    "company": "ems",
    "number": "1136281381675",
    "from": "广东省深圳市南山区",
    "to": "北京市朝阳区",
    "key": "XXX ",
    "parameters": {
        "callbackurl": "您的回调接口的地址,如http://www.您的域名.com/kuaidi?callbackid=...",
        "salt": "XXXXXXXXXX",
        "resultv2": "1",
        "autoCom": "1",
        "interCom": "1",
        "departureCountry": "CN",
        "departureCom": "ems",
        "destinationCountry": "JP",
        "destinationCom": "japanposten",
        "phone": "13800138000"
    }
}

1.5 订阅返回信息代码含义

result: true表示成功,false表示失败

信息代码信息内容描述原因及建议处理方式
200提交成功订阅提交成功
500服务器错误快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
501重复订阅此单已经订阅成功且目前还在跟踪过程中。若要提交多次订阅,请在收到单号的status=abort或shutdown后隔半小时再提交订阅
502提交内容含有敏感关键字,被安全防护拦截回调地址、提交内容包含敏感词,请联系快递100工作人员
600您不是合法的订阅者(即授权Key出错)账号无可用单量,需要充值
601POLL: KEY 已过期账号无可用单量,需要充值
700不支持的快递公司拒绝订阅的快递公司,检查快递公司编码是否有误
701订阅方的订阅数据存在错误(如不支持的快递公司、单号为空、单号超长等)或错误的回调地址请检查快递公司编码、对照技术文档检查参数、在后台调试工具测试回调地址
702POLL:识别不到该单号对应的快递公司快递公司编码错误或者无可用单量,需要充值

1.6 订阅返回示例(JSON格式)

{
    "result": true,
    "returnCode": "200",
    "message": "提交成功"
}
         

二、推送接口

2.1 推送请求地址

由贵司在订阅请求中通过callbackurl字段提供

2.2 推送请求类型

post

2.3 推送输入参数

请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

名称类型示例值描述
signString 订阅参数salt值不为null时,推送数据将包含该加密签名,加密方式:md5(param+salt)。注意: salt值为空串时,推送的数据也会包含sign。
Θparam 由其他字段拼接
└ statusStringpolling监控状态:polling:监控中,shutdown:结束,abort:中止,updateall:重新推送。其中当快递单为已签收时status=shutdown,当message为“3天查询无记录”或“60天无变化时”status= abort ,对于status=abort的状态,需要增加额外的处理逻辑
└ billstatusStringgot包括got、sending、check三个状态,由于意义不大,已弃用,请忽略
└ messageString 监控状态相关消息,如:3天查询无记录,60天无变化
└ autoCheckString1快递公司编码是否出错,0为本推送信息对应的是贵司提交的原始快递公司编码,1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果,我方会(1)判断一次贵司提交的快递公司编码是否正确,如果正确,给贵司的回调接口(callbackurl)推送带有如下字段的信息:autoCheck=0、comOld与comNew都为空;(2)如果贵司提交的快递公司编码出错,我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控(后续如果监控到单号有更新就给贵司的回调接口(callbackurl)推送带有如下字段的信息:autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码);并且给贵方的回调接口(callbackurl)推送一条含有如下字段的信息:status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。
└ comOldStringyuantong贵司提交的原始的快递公司编码。详细见autoCheck后说明。若开启了国际版(即在订阅请求中增加字段interCom=1),则回调请求中暂无此字段
└ comNewStringems我司纠正后的新的快递公司编码。详细见autoCheck后说明。若开启了国际版(即在订阅请求中增加字段interCom=1),则回调请求中暂无此字段
ΘlastResultlastResult 最新查询结果,若在订阅报文中通过interCom字段开通了国际版,则此lastResult表示出发国的查询结果,全量,倒序(即时间最新的在最前)
└- messageString 消息体,请忽略
└- stateString0快递单当前状态,包括0在途,1揽收,2疑难,3签收,4退签,5派件,6退回,7转单,10待清关,11清关中,12已清关,13清关异常,14收件人拒签等13个状态
└- statusString200通讯状态,请忽略
└- conditionStringF00快递单明细状态标记,暂未实现,请忽略
└- ischeckString0是否签收标记
└- comStringyuantong快递公司编码,一律用小写字母
└- nuStringV030344422单号
└- dataObject 数组,包含多个对象,每个对象字段如展开所示
└-- contextString上海分拨中心/装件入车扫描内容
└-- timeString2012-08-28 16:33:19时间,原始格式
└-- ftimeString2012-08-28 16:33:19格式化后时间
└-- statusString在途本数据元对应的签收状态。在订阅接口中提交resultv2 = 1字段后才会出现
└-- areaCodeString310000000000本数据元对应的行政区域的编码,在订阅接口中提交resultv2 = 1字段后才会出现
└-- areaNameString上海市本数据元对应的行政区域的名称,在订阅接口中提交resultv2 = 1字段后才会出现
Θ destResultdestResult 表示最新的目的国家的查询结果,只有在订阅报文中通过interCom=1字段开通了国际版才会显示此数据元,全量,倒序(即时间最新的在最前)
└- messageString 消息体,请忽略
└- stateString0快递单当前状态,包括0在途,1揽收,2疑难,3签收,4退签,5派件,6退回等8个状态
└- statusString200通讯状态,请忽略
└- conditionStringF00快递单明细状态标记,暂未实现,请忽略
└- ischeckString0是否签收标记
└- comStringyuantong快递公司编码,一律用小写字母
└- nuStringV030344422单号
Θ datadata 数组,包含多个对象,每个对象字段如展开所示
└-- contextString上海分拨中心/装件入车扫描内容
└-- timeString2012-08-28 16:33:19时间,原始格式
└-- ftimeString2012-08-28 16:33:19格式化后时间
└-- statusString在途本数据元对应的签收状态,在订阅接口中提交resultv2 = 1字段后才会出现
└-- areaCodeString310000000000本数据元对应的行政区域的编码,在订阅接口中提交resultv2 = 1字段后才会出现
└-- areaNameString上海市本数据元对应的行政区域的名称,在订阅接口中提交resultv2 = 1字段后才会出现

2.4 推送输入参数示例

    param = {
        "status": "polling",
        "billstatus": "got",
        "message": "",
        "autoCheck": "1",
        "comOld": "yuantong",
        "comNew": "ems",
        "lastResult": {
            "message": "ok",
            "state": "0",
            "status": "200",
            "condition": "F00",
            "ischeck": "0",
            "com": "yuantong",
            "nu": "V030344422",
            "data": [
	        {
                    "context": "上海分拨中心/装件入车扫描 ",
                    "time": "2012-08-28 16:33:19",
                    "ftime": "2012-08-28 16:33:19",
                    "status": "在途",
                    "areaCode": "310000000000",
                    "areaName": "上海市"
                },
                {
                    "context": "上海分拨中心/下车扫描 ",
                    "time": "2012-08-27 23:22:42",
                    "ftime": "2012-08-27 23:22:42",
                    "status": "在途",
                    "areaCode": "310000000000",
                    "areaName": "上海市"
                }
            ]
        },
        "destResult": {
            "message": "ok",
            "state": "0",
            "status": "200",
            "condition": "F00",
            "ischeck": "0"     ,
            "com": "speedpost",
            "nu": "EX015142583SG",
            "data": [
	        {
                    "context": "[01000]Final delivery Delivered to: SLOVESNOV",
                    "time": "2016-05-24 14:00:00",
                    "ftime": "2016-05-24 14:00:00",
                    "status": "签收",
                    "areaCode": null,
                    "areaName": null
                }
            ]
        }
    }

2.5 运单签收状态服务说明

状态值名称含义
0在途快件处于运输过程中
1揽收快件已由快递公司揽收
2疑难快递100无法解析的状态,或者是需要人工介入的状态, 比方说收件人电话错误。
3签收正常签收
4退签货物退回发货人并签收
5派件货物正在进行派件
6退回货物正处于返回发货人的途中
7转投货物转给其他快递公司邮寄
10待清关货物等待清关
11清关中货物正在清关流程中
12已清关货物已完成清关流程
13清关异常货物在清关过程中出现异常
14拒签收件人明确拒收

2.6 推送响应报文及错误码解释

字段名称字段含义
resulttrue表示成功,false表示失败。如果提交回调接口的地址失败,30分钟后重新回调,3次仍旧失败的,自动放弃
returnCode200: 提交成功 500: 服务器错误 其他错误请自行定义
message返回的提示

2.7 推送返回示例

当我方调用贵方的回调接口(callbackurl)时,贵方需要先将我方提交的数据保存至贵方的数据库,接着向我方返回是否成功接收的响应报文及代码,即贵公司直接在回调接口的地址的response中填写如下内容:

{
    "result":true,
    "returnCode":"200",
    "message":"成功"
}      

注意:对于status= abort(message中包含“3天查询无记录”或者“60天无变化”)的快递单,也需要返回成功接收的响应报文及代码。

三、快递公司编码

下载表格

如果您需要的公司不在此列表,请联系在线客服添加

四、demo下载

JAVA示例代码    PHP示例代码    PYTHON示例代码    .NET示例代码

五、实时关注推送情况

扫码打开企业助手小程序实时关注账号里的推送成功情况,确保系统稳定运行。 https://cdn.kuaidi100.com/images/openApiWeb/common/code_1.jpg