Home > List of blog posts > 快递100快递信息订阅推送API接口案例代码

Blogger Information

Blog 60

fans 0

comment 0

visits 100732

Special Recommendation

More>

Related recommendations

一、订阅接口

1.1 订阅请求地址

https://poll.kuaidi100.com/poll

1.2 订阅请求类型

post

1.3 订阅输入参数

请求参数（header）

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

请求参数（body）

名称	类型	是否必需	示例值	描述
schema	String	是	json	返回的数据格式
Θparam	param	是		由其他字段拼接
└ company	String	是	ems	订阅的快递公司的编码，一律用小写字母
└ number	String	是	1136281381675	订阅的快递单号，单号的最大长度是32个字符 <a href="http://api.kuaidi100.com/manager/openapi/download/kdbm.do" target="_blank"><u>下载编码表格</u></a>
└ from	String	否	广东省深圳市南山区	出发地城市，省-市-区，非必填，填了有助于提升签收状态的判断的准确率，请尽量提供
└ to	String	否	北京市朝阳区	目的地城市，省-市-区，非必填，填了有助于提升签收状态的判断的准确率，且到达目的地后会加大监控频率，请尽量提供
└ key	String	是		授权码，请<a href="https://api.kuaidi100.com/register/enterprise" target="_blank">申请企业版</a>获取
Θparameters	parameters	是		附加参数信息
└- callbackurl	String	是		回调接口的地址
└- salt	String	否	XXXXXXXXXX	签名用随机字符串
└- resultv2	String	否	1	添加此字段表示打开行政区域解析功能
└- autoCom	String	否	1	添加此字段且将此值设为1，则表示开始智能判断单号所属公司的功能，开启后，company字段可为空,即只传运单号（number字段），我方收到后会根据单号判断出其所属的快递公司（即company字段）。建议只有在无法知道单号对应的快递公司（即company的值）的情况下才开启此功能
└- interCom	String	否	1	添加此字段表示开启国际版，开启后，若订阅的单号（即number字段）属于国际单号，会返回出发国与目的国两个国家的跟踪信息，本功能暂时只支持邮政体系（国际类的邮政小包、EMS）内的快递公司，若单号我方识别为非国际单，即使添加本字段，也不会返回destResult元素组
└- departureCountry	String	否	CN	出发国家编码
└- departureCom	String	否	ems	出发的快递公司的编码
└- destinationCountry	String	否	JP	目的国家编码
└- destinationCom	String	否	japanposten	目的的快递公司的编码
└- phone	String	否	13488888888	收、寄件人的电话号码（手机和固定电话均可，只能填写一个，顺丰单号必填，其他快递公司选填。如座机号码有分机号，分机号无需上传。）

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"
        }
    }

1.5 订阅返回信息代码含义

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

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

1.6 订阅返回示例（JSON格式）

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

二、推送接口

2.1 推送请求地址

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

2.2 推送请求类型

post

2.3 推送输入参数

请求参数（header）

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

请求参数（body）

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

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

2.7 推送返回示例

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

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

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

三、快递公司编码

四、demo下载

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

一、快递信息推送API产品介绍

快递100信息推送服务提供运单查询、追踪的功能，用于企业对寄出的物品进行物流追踪。

信息推送服务是企业提交快递单号，快递100接收到后便对这些运单进行跟踪，当运单状态发生变化的时候，快递100便通过调用回调接口将运单的跟踪信息推送给贵公司，直到这些运单号的生命周期结束（一般以“已签收”为准）。对于某个单号，当贵方正确提交订阅了后，我们一般会在15分钟左右后进行第一次监控，如果监控到单号本身有了跟踪信息，即进行第一次推送，否则等待下一次监控。此后我们一般每4小时进行一次监控，并会根据单号的状态等因素作调整。

二、快递信息推送API应用场景

让顾客登录您的网站、APP、小程序后，直接在“我的订单”页面内就能看到订单的物流状态。
能开发自动的、批量查单功能，自动筛选出“已签收”、“疑难件”等状态的单号，减轻跟单人员的压力。
改变订单的状态与交易流程，例如只要运单号变为“已签收”，就能让订单变更为可以确认退换货等。
核销销售人员，根据“已签收”的运单数，就能算出销售人员的业绩。
评估与选择快递公司，可获得快递实际在途时间，评估快递公司的时效，优化快递选择；
助结算运费，找出“已签收”的单及签收时间，便能轻松应对货到付款的结算与对账。

三、系统结构与流程

四、快递信息推送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/5f0ffa7f2977d50a94e1023b.html
https://api.kuaidi100.com/document/5eb9f79186b0df4188313a0d.html
https://api.kuaidi100.com/document/5f0ffa8f2977d50a94e1023c.html

Statement of this Website

The copyright of this blog article belongs to the blogger. Please specify the address when reprinting! If there is any infringement or violation of the law, please contact admin@php.cn Report processing!

All comments Speak rationally on civilized internet, please comply with News Comment Service Agreement

0 comments

Author's latest blog post

API文档工具是什么？附带6款好用的API文档工具介绍

2021-04-20 18:01:35