文档中心
一、实时快递查询接口 二、快递公司编码 三、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查询的快递单号, 单号的最小长度6个字符,最大长度32个字符
└ phonestring13888888888收、寄件人的电话号码(手机和固定电话均可,只能填写一个,顺丰速运顺丰快运必填,其他快递公司选填。如座机号码有分机号,分机号无需传入;如号码是电商虚拟号码需传入“-“后的后四位。查看详情
└ fromstring广东深圳出发地城市
└ tostring北京朝阳目的地城市,到达目的地后会加大监控频率
└ resultv2string1添加此字段表示开通行政区域解析功能。空:关闭(默认),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 破损 快件破损
210 销单 寄件人申请撤销寄件
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格式
408快递公司参数异常:验证码错误电话号码校验不通过,检查是否提交了收、寄件人正确的电话号码
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(查询无结果,请隔段时间再查)。需要注意的是:该次调用的单号会列入贵司的调用数据内,列入计费账单内。