快递100快递实时快递查询接口API案例代码

一、实时快递查询接口

1.1 请求地址

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

1.2 请求类型

post

1.3 输入参数

请求参数（header）

名称	类型	默认值
Content-Type	string	application/x-www-form-urlencoded

请求参数（body）

名称	类型	是否必需	示例值	描述
customer	String	是		授权码，请<a href="https://api.kuaidi100.com/register/enterprise" target="_blank">申请企业版</a>获取
sign	String	是		签名， 用于验证身份， 按param + key + customer 的顺序进行MD5加密（注意加密后字符串一定要转32位大写）， 不需要加上“+”号
Θparam	Object	是		由其他字段拼接
└ com	string	是	yuantong	查询的快递公司的编码， 一律用小写字母 <a href="http://api.kuaidi100.com/manager/openapi/download/kdbm.do" target="_blank"><u>下载编码表格</u></a>
└ num	string	是	12345678	查询的快递单号， 单号的最大长度是32个字符
└ phone	string	否	13888888888	收、寄件人的电话号码（手机和固定电话均可，只能填写一个，顺丰单号必填，其他快递公司选填。如座机号码有分机号，分机号无需上传。）
└ from	string	否	广东深圳	出发地城市
└ to	string	否	北京朝阳	目的地城市，到达目的地后会加大监控频率
└ resultv2	int	否	1	添加此字段表示开通行政区域解析功能。0：关闭（默认），1：开通行政区域解析功能以及物流轨迹增加物流状态值，2：开通行政解析功能以及物流轨迹增加物流状态值并且返回出发、目的及当前城市信息
└show	String	否	0	返回格式：0：json格式（默认），1：xml，2：html，3：text
└order	String	否	desc	返回结果排序:desc降序（默认）,asc 升序

1.4 请求参数示例

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

1.5 返回结果

字段名称	类型	字段含义
message	String	消息体，请忽略
state	Integer	快递单当前状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回，7转单，10待清关，11清关中，12已清关，13清关异常，14收件人拒签等13个状态
status	Integer	通讯状态，请忽略
condition	String	快递单明细状态标记，暂未实现，请忽略
ischeck	Integer	是否签收标记，请忽略，明细状态请参考state字段
com	String	快递公司编码,一律用小写字母
nu	String	单号
Θdata	data	最新查询结果，数组，包含多项，全量，倒序（即时间最新的在最前），每项都是对象，对象包含字段请展开
└ context	String	内容
└ time	String	时间，原始格式
└ ftime	String	格式化后时间
└status	String	本数据元对应的签收状态，只有实时查询接口中提交resultv2标记后才会出现
└areaCode	String	本数据元对应的行政区域的编码，只有实时查询接口中提交resultv2标记后才会出现
└areaName	String	本数据元对应的行政区域的名称，只有实时查询接口中提交resultv2标记后才会出现

1.6 运单签收状态服务说明

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

1.7 正确返回示例

JSON格式

{
    "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",
        },
        {
            "context": "上海分拨中心/下车扫描 ",
            "time": "2012-08-27 23:22:42",
            "ftime": "2012-08-27 23:22:42",
        }
    ]
}

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加密，加密后字符串转大写
601	key已过期	没有可用单量，账号需要充值使用

二、快递公司编码

<a href="https://api.kuaidi100.com/manager/openapi/download/kdbm.do" style="color: #027eff;" target="_blank"><u>下载表格</u></a>

三、demo下载

<a href="https://github.com/kuaidi100-api/java-demo" style="color: #027eff;" target="_blank" rel="nofollow noopener noreferrer"><u>JAVA示例代码</u></a>    <a href="https://github.com/kuaidi100-api/php-demo" style="color: #027eff;" target="_blank" rel="nofollow noopener noreferrer"><u>PHP示例代码</u></a>    <a href="https://github.com/kuaidi100-api/python-demo" style="color: #027eff;" target="_blank" rel="nofollow noopener noreferrer"><u>PYTHON示例代码</u></a>    <a href="https://github.com/kuaidi100-api/.net-demo" style="color: #027eff;" target="_blank" rel="nofollow noopener noreferrer"><u>.NET示例代码</u></a>

一、实时查询API产品介绍

快递100实时查询接口提供给企业及最终用户实时查询物流轨迹的功能。

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

二、实时查询API应用场景

1. 在电商网页/APP/小程序中，顾客在订单详情里查询购买商品的物流轨迹；

2. 客服人员查看订单的实时轨迹情况，确保商品的发货状态正常；

3. 企业邮寄礼品、文件等，业务人员根据单号追踪发货状态，确保签收；

4. 可集成到网站、APP、ERP、SAAS平台、小程序里；

​ 由于快递公司系统的承压能力是有限的，所以请勿大批量地、高频率地、重复性地调用本接口，仅用于如贵司网站或APP的最终用户主动点击时才触发调用本接口进行查询，其他的系统自动更新运单签收状态等管理类需求请继续使用快递100信息推送服务。

注：对于实时查询API，请控制每一单查询频率至少在半小时以上，否则会造成锁单。

三、实时查询API收费方式

1. 收费方式

实时查询接口属于查询类接口，企业注册快递100账号后可以在企业管理后台<a href="https://api.kuaidi100.com/service/query" target="_blank">查看查询类接口套餐</a>价格并购买。

2. 收费价格

查询类接口预充值收费套餐：充值即可开通使用，无需合同流程。

价格/元	单量	赠送/单	单价/元
2000	20000	5000	0.08
1000	10000	2000	约0.083
500	5000	500	约0.09

查询类接口按单收费，一个自然月内同一个运单多次查询只收一次费用。

3. 开具发票

快递100支持开具增值税发票，用户购买完成后可在企业管理后台-费用中心-支付记录-请求开票。默认开具电子增值税普通发票，1000元以上可支持开具增值税专用发票。

官方源文档：

https://api.kuaidi100.com/document/5f0ffb52bc8da837cbd8aefb.html
https://api.kuaidi100.com/document/5f0ffb5ebc8da837cbd8aefc.html