文档中心
一、实时快递查询接口 二、快递公司编码 三、demo下载 四、注意事项 API调试工具

实时快递单号查询技术文档

一、实时快递查询接口

用户向接口提交快递单号后,接口会实时调取快递公司的单号信息并返回此单号最新的物流信息,包括物流轨迹、状态、时间等。

注意:请控制每一单查询频率至少在半小时以上,否则会造成锁单。

1.1 请求地址

https://poll.kuaidi100.com/poll/query.do

1.2 请求类型

post

1.3 输入参数

请求参数(header)

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

请求参数(body)

名称类型是否必需示例值描述
customerString 授权码,请申请企业版获取
signString 签名, 用于验证身份, 按param + key + customer 的顺序进行MD5加密(注意加密后字符串一定要转32位大写), 不需要加上“+”号
ΘparamObject 由其他字段拼接
└ comstringyuantong查询的快递公司的编码, 一律用小写字母 下载编码表格
└ numstring12345678查询的快递单号, 单号的最小长度4个字符,最大长度32个字符
└ phonestring13888888888收、寄件人的电话号码(手机和固定电话均可,只能填写一个,顺丰速运和丰网速运必填,其他快递公司选填。如座机号码有分机号,分机号无需传入。)
└ fromstring广东深圳出发地城市
└ tostring北京朝阳目的地城市,到达目的地后会加大监控频率
└ resultv2int1添加此字段表示开通行政区域解析功能。空:关闭(默认),1:开通行政区域解析功能以及物流轨迹增加物流状态名称 4: 开通行政解析功能以及物流轨迹增加物流高级状态名称、状态值并且返回出发、目的及当前城市信息
└showString0返回格式:0:json格式(默认),1:xml,2:html,3:text
└orderStringdesc返回结果排序:desc降序(默认),asc 升序

1.4 请求参数示例

    customer = **********
    sign = ******************
    param = {
        "com": "ems",
        "num": "em263999513jp",
        "phone": "13868688888",
        "from": "广东省深圳市南山区",
        "to": "北京市朝阳区",
        "resultv2": "4",
        "show": "0",
        "order": "desc"
    }

1.5 返回结果

字段名称类型字段含义
messageString消息体,请忽略
stateString快递单当前状态,默认为0在途,1揽收,2疑难,3签收,4退签,5派件,8清关,14拒签等10个基础物流状态,如需要返回高级物流状态,请参考 resultv2 传值
statusString通讯状态,请忽略
conditionString快递单明细状态标记,暂未实现,请忽略
ischeckString是否签收标记,0未签收,1已签收,请忽略,明细状态请参考state字段
comString快递公司编码,一律用小写字母
nuString单号
Θdatadata最新查询结果,数组,包含多项,全量,倒序(即时间最新的在最前),每项都是对象,对象包含字段请展开
└ contextString内容
└ timeString时间,原始格式
└ ftimeString格式化后时间
└statusString本数据元对应的物流状态名称或者高级状态名称,实时查询接口中提交resultv2=1或者resultv2=4标记后才会出现
└statusCodeString本数据元对应的高级物流状态值,实时查询接口中提交resultv2=4标记后才会出现
└areaCodeString本数据元对应的行政区域的编码,实时查询接口中提交resultv2=1或者resultv2=4标记后才会出现
└areaNameString本数据元对应的行政区域的名称,实时查询接口中提交resultv2=1或者resultv2=4标记后才会出现
└areaCenterString本数据元对应的行政区域经纬度,实时查询接口中提交resultv2=4标记后才会出现
└locationString本数据元对应的快件当前地点,实时查询接口中提交resultv2=4标记后才会出现
└areaPinYinString本数据元对应的行政区域拼音,实时查询接口中提交resultv2=4标记后才会出现


1.6 运单快递状态(state)说明

物流状态值 物流状态名称 高级物流状态值 高级物流状态名称 含义
1 揽收 1 揽收 快件揽件
101 已下单 已经下快件单
102 待揽收 待快递公司揽收
103 已揽收 快递公司已经揽收
0 在途 0 在途 快件在途中
1001 到达派件城市 快件到达收件人城市
1002 干线 快件处于运输过程中
1003 转递 快件发往到新的收件地址
5 派件 5 派件 快件正在派件
501 投柜或驿站 快件已经投递到快递柜或者快递驿站
3 签收 3 签收 快件已签收
301 本人签收 收件人正常签收
302 派件异常后签收 快件显示派件异常,但后续正常签收
303 代签 快件已被代签
304 投柜或站签收 快件已由快递柜或者驿站签收
6 退回 6 退回 快件正处于返回发货人的途中
4 退签 4 退签 此快件单已退签
401 已销单 此快件单已撤销
14 拒签 收件人拒签快件
7 转投 7 转投 快件转给其他快递公司邮寄
2 疑难 2 疑难 快件存在疑难
201 超时未签收 快件长时间派件后未签收
202 超时未更新 快件长时间没有派件或签收
203 拒收 收件人发起拒收快递,待发货方确认
204 派件异常 快件派件时遇到异常情况
205 柜或驿站超时未取 快件在快递柜或者驿站长时间未取
206 无法联系 无法联系到收件人
207 超区 超出快递公司的服务区范围
208 滞留 快件滞留在网点,没有派送
209 破损 快件破损
8 清关 8 清关 快件清关
10 待清关 快件等待清关
11 清关中 快件正在清关流程中
12 已清关 快件已完成清关流程
13 清关异常 货物在清关过程中出现异常
14 拒签 \ \ 收件人拒签快件

注:如需物流状态高级状态名称及状态值需要 resultv2 传 “4” 返回

1.7 正确返回示例

JSON格式

{
    "message": "ok",
    "nu": "JT0004301991791",
    "ischeck": "0",
    "com": "jtexpress",
    "status": "200",
    "data": [
        {
            "time": "2021-12-15 17:19:28",
            "context": "【杭州市】您的包裹已存放至【驿站】,记得早点来取它回家!",
            "ftime": "2021-12-15 17:19:28",
            "areaCode": "CN330102000000",//本数据元对应的行政区域编码,resultv2=1或者resultv2=4才会展示
            "areaName": "浙江,杭州市,上城区",//本数据元对应的行政区域名称,resultv2=1或者resultv2=4才会展示
            "status": "投柜或驿站",//本数据元对应的物流状态名称或者高级物流状态名称,resultv2=1或者resultv2=4才会展示
            "location": "浙江省 杭州市 上城区", //本数据元对应的快件当前地点,resultv2=4才会展示
            "areaCenter": "120.184349,30.25446", //本数据元对应的行政区域经纬度,resultv2=4才会展示
            "areaPinYin": "shang cheng qu",//本数据元对应的行政区域拼音,resultv2=4才会展示
            "statusCode": "501"//本数据元对应的高级物流状态值,resultv2=4才会展示
        },
        {
            "time": "2021-12-15 14:17:31",
            "context": "【杭州市】【杭州网点】的极兔小哥正在派件",
            "ftime": "2021-12-15 14:17:31",
            "areaCode": "CN330102000000",
            "areaName": "浙江,杭州市,上城区",
            "status": "派件",
            "location": "浙江省 杭州市 上城区",
            "areaCenter": "120.184349,30.25446",
            "areaPinYin": "shang cheng qu",
            "statusCode": "5"
        },
        {
            "time": "2021-12-15 13:58:18",
            "context": "【杭州市】 快件到达【杭州网点】",
            "ftime": "2021-12-15 13:58:18",
            "areaCode": "CN330102000000",
            "areaName": "浙江,杭州市,上城区",
            "status": "在途",
            "location": "浙江省 杭州市 上城区",
            "areaCenter": "120.184349,30.25446",
            "areaPinYin": "shang cheng qu",
            "statusCode": "0"
        },
        {
            "time": "2021-12-15 04:11:20",
            "context": "【杭州市】快件离开【杭州转运中心】已发往【杭州江干四季青网点】",
            "ftime": "2021-12-15 04:11:20",
            "areaCode": "CN330109000000",
            "areaName": "浙江,杭州市,萧山区",
            "status": "干线",
            "location": "浙江省 杭州市 萧山区",
            "areaCenter": "120.493286,30.28333",
            "areaPinYin": "xiao shan qu",
            "statusCode": "1002"
        },
        {
            "time": "2021-12-15 02:09:52",
            "context": "【杭州市】 快件到达【杭州转运中心】",
            "ftime": "2021-12-15 02:09:52",
            "areaCode": "CN330109000000",
            "areaName": "浙江,杭州市,萧山区",
            "status": "干线",
            "location": "浙江省 杭州市 萧山区",
            "areaCenter": "120.493286,30.28333",
            "areaPinYin": "xiao shan qu",
            "statusCode": "1002"
        },
        {
            "time": "2021-12-14 21:08:34",
            "context": "【上海市】快件离开【上海浦西转运中心】已发往【杭州转运中心】",
            "ftime": "2021-12-14 21:08:34",
            "areaCode": "CN310118000000",
            "areaName": "上海,上海,青浦区",
            "status": "干线",
            "location": "上海 上海市 青浦区",
            "areaCenter": "121.124178,31.150681",
            "areaPinYin": "qing pu qu",
            "statusCode": "1002"
        },
        {
            "time": "2021-12-14 20:54:22",
            "context": "【上海市】 快件到达【上海浦西转运中心】",
            "ftime": "2021-12-14 20:54:22",
            "areaCode": "CN310118000000",
            "areaName": "上海,上海,青浦区",
            "status": "干线",
            "location": "上海 上海市 青浦区",
            "areaCenter": "121.124178,31.150681",
            "areaPinYin": "qing pu qu",
            "statusCode": "1002"
        },
        {
            "time": "2021-12-14 17:25:58",
            "context": "【上海市】快件离开【上海杨浦黄兴路网点】已发往【上海浦西转运中心】",
            "ftime": "2021-12-14 17:25:58",
            "areaCode": "CN310110000000",
            "areaName": "上海,上海,杨浦区",
            "status": "干线",
            "location": "上海 上海市 杨浦区",
            "areaCenter": "121.526077,31.259541",
            "areaPinYin": "yang pu qu",
            "statusCode": "1002"
        },
        {
            "time": "2021-12-14 09:03:58",
            "context": "【上海市】【上海杨浦黄兴路网点】已取件。",
            "ftime": "2021-12-14 09:03:58",
            "areaCode": "CN310110000000",
            "areaName": "上海,上海,杨浦区",
            "status": "揽收",
            "location": "上海 上海市 杨浦区",
            "areaCenter": "121.526077,31.259541",
            "areaPinYin": "yang pu qu",
            "statusCode": "1"
        }  
    ],
    "state": "5",
    "condition": "00",
    "routeInfo": {
        "from": {
            "number": "CN310110000000",
            "name": "上海,上海,杨浦区"
        },//本数据元对应的出发地城市信息,resultv2=4才会展示
        "cur": {
            "number": "CN330102000000",
            "name": "浙江,杭州市,上城区"
        },//本数据元对应的当前城市信息,resultv2=4才会展示
        "to": null
    },//本数据元对应的目的地城市信息,resultv2=4才会展示
    "isLoop": false
}
}

1.8 错误返回示例

JSON格式

{
    "result": false,
    "returnCode": "400",
    "message": "找不到对应公司"
}

1.8 信息代码含义

信息代码信息内容描述原因及建议处理方式
200查询成功查询成功
400找不到对应公司提交数据不完整或者账号未充值, 检查提交的格式是否为x-www-form-urlencoded的post格式
500查询无结果,请隔段时间再查表示查询失败,或没有POST提交
501服务器错误快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数没有按照文档规定填写等,也会报此错误
502服务器繁忙快递100的服务器出现间歇或临时性异常,请联系快递100排查原因
503验证签名失败请检查加密方式,param + key + customer 的顺序进行MD5加密,加密后字符串转大写
601key已过期没有可用单量,账号需要充值使用

二、快递公司编码

下载表格

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

三、demo下载

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

四、注意事项

1、贵司连续5次com字段为空或者不符合《快递100快递公司编码规则》,快递100API将会通过快递单号的数据自动调用智能识别接口,判断合适的快递公司编号,返回对应的快递信息。

2、贵司com字段数据符合《快递100快递公司编码规则》时,同一错误快递单号连续调用接口5次,快递100API接口将返回500(查询无结果,请隔段时间再查)。需要注意的是:该次调用的单号会列入贵司的调用数据内,列入计费账单内。