一、地图轨迹订阅接口
1.1 接口格式
1.使用http协议表单提交的方式进行信息交互，字符编码默认统一采用UTF-8，数据格式：application/x-www-form-urlencoded；
2.字段类型约定：需要严格依据字段表格中给出的参数格式和大小进行开发。
3.字段解析约定：参数字段中的必选字段是每次调用接口时都要求必须传入的；
1.2 请求地址
http://poll.kuaidi100.com/pollmap
请求报文：
| 参数名 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| schema | 否 | string | 默认是json |
| param | 是 | Object | 主体参数对象 |
param数据结构：
| 参数名 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| key | 是 | string | 授权码，请<a href="https://api.kuaidi100.com/register/enterprise" target="_blank">申请企业版</a>获取 |
| company | 是 | string | 订阅的快递公司的编码，一律用小写字母 |
| number | 是 | string | 订阅的快递单号，单号的最大长度是40个字符 |
| from | 是 | string | 快递寄件地址 |
| to | 是 | string | 快递收件地址 |
| parameters | 是 | Object | 辅助参数 |
parameters数据结构：
| 参数名 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| callbackurl | 是 | string | 回调接口的地址 |
| salt | 否 | string | 签名用随机字符串 |
| phone | 否 | string | 收寄件人的移动电话号码（只能填写一个，顺丰单号必填，其他快递公司选填） |
| ordertime | 否 | string | 订单下单时间，格式“yyyy-MM-dd HH:mm:ss” |
1.3 请求示例
schema = jsonparam = {"company": "ems","number": "1136281381675","from": "广东省深圳市南山区","to": "北京市朝阳区","key": "XXX ","parameters": {"callbackurl": "您的回调接口的地址，如http://www.您的域名.com/kuaidi?callbackid=...","salt": "*","phone": "","ordertime": "2020-12-31 08:09:00"}}
1.4 订阅返回结果
| 字段名称 | 类型 | 是否必填 | 字段含义 |
|---|---|---|---|
| result | Boolean | 是 | true表示成功，false表示失败 |
| returnCode | string | 是 | 返回状态码，详细见1.6附表 |
| message | string | 是 | 状态信息 |
1.5 订阅响应报文示例（json格式）
{"result": true,"returnCode": "200","message": "提交成功"}
1.6 状态码附表
| returnCode | massage | 描述 |
|---|---|---|
| 200 | 提交成功 | 订阅提交成功 |
| 400 | 无法解析 | 出发地目的地无法解析或下单时间无法解析 |
| 500 | 服务器错误 | 快递100的服务器出理间隙或临时性异常，有时如果因为不按规范提交请求，比如快递公司参数写错等，也会报此错误 |
| 501 | 重复订阅 | 此单已经订阅成功且目前还在跟踪过程中。若要提交多次订阅，请在收到单号的status=abort或shutdown后隔半小时再提交订阅 |
| 502 | 提交内容含有敏感关键字，被安全防护拦截 | 回调地址、提交内容包含敏感词，请联系快递100工作人员 |
| 600 | 您不是合法的订阅者（即授权Key出错） | 账号无可用单量，需要充值 |
| 601 | POLL: KEY 已过期 | 账号无可用单量，需要充值 |
| 700 | 不支持的快递公司 | 拒绝订阅的快递公司，检查快递公司编码是否有误 |
| 701 | 订阅方的订阅数据存在错误（如不支持的快递公司、单号为空、单号超长等）或错误的回调地址 | 请检查快递公司编码、对照技术文档检查参数、在后台调试工具测试回调地址 |
| 702 | POLL:识别不到该单号对应的快递公司 | 快递公司编码错误或者无可用单量，需要充值 |
二、推送接口
1.使用http协议表单提交的方式进行信息交互，字符编码默认统一采用UTF-8，数据格式：application/x-www-form-urlencoded；
2.字段类型约定：需要严格依据字段表格中给出的参数格式和大小进行开发。
3.字段解析约定：参数字段中的必选字段是每次调用接口时都要求必须传入的；
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 | 是 | Object | 主体参数对象 |
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 | Object | 最新查询轨迹结果 |
lastResult对应参数
| 字段名称 | 类型 | 字段含义 |
|---|---|---|
| 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 | 单号 |
| trailUrl | String | 轨迹地图链接 |
| arrivalTime | String | 预计到达时间 |
| totalTime | String | 平均耗时 |
| remainTime | String | 到达还需多少时间 |
| isLoop | Boolean | 是否存在环路 |
| ΘrouteInfo | 路由信息 | |
| └Θfrom | 出发地行政区信息 | |
| └number | 政区信息编码 | |
| └name | 政区信息名 | |
| └Θcur | 当前地行政区信息 | |
| └number | 政区信息编码 | |
| └name | 政区信息名 | |
| └Θto | 目的地行政区信息 | |
| └number | 政区信息编码 | |
| └name | 政区信息名 | |
| Θdata | data | 最新查询结果，数组，包含多项，全量，倒序（即时间最新的在最前），每项都是对象，对象包含字段请展开 |
| └ context | String | 内容 |
| └ time | String | 时间，原始格式 |
| └ ftime | String | 格式化后时间 |
| └status | String | 本数据元对应的签收状态，只有实时查询接口中提交resultv2标记后才会出现 |
| └areaCode | String | 本数据元对应的行政区域的编码，只有实时查询接口中提交resultv2标记后才会出现 |
| └areaName | String | 本数据元对应的行政区域的名称，只有实时查询接口中提交resultv2标记后才会出现 |
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": "上海市"}],"routeInfo": {"from": {"number": "CN3100","name": "上海市"},"cur": {"number": "CN6101","name": "陕西,西安市"},"to": {"number": "CN6101","name": "陕西,西安市"}},"isLoop": false,"trailUrl": "https://api.kuaidi100.com/tools/map/bc80574d538262aecc897a469151f0e3","arrivalTime": "2020-12-19 12:00","totalTime": "2天1小时","remainTime": "1天2小时"}}
2.5 轨迹链接应用示例
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2a1e3b91df2e4db8afb5eefc50d76c6f~tplv-k3u1fbpfcp-zoom-1.image" style="zoom:60%">
重要提醒：
（1）对于status= abort而且message中包含“3天”关键字而且comNew为空的快递单，需要增加以下处理逻辑：
- 如果有专门的工作人员，可以:将快递单罗列给工作人员，由工作人员判断此单是否为假单：如果此单是真实单，则将此单重新向快递100提交一次；如果此单是假单，则将此单标记为假单，而且不再将此单提交给快递100。如果没有专门的工作人员，请直接用以下第二种方法进行操作；
如果没有专门的工作人员，可以：在收到status=abort而且message中包含“3天”关键字而且comNew为空的提示10分钟后，将此快递单重新向快递100提交订阅，如果重新提交后仍然收到status= abort，则再次重新向快递100提交，如此，在同一月中如果重复提交3~4次都仍然收到status= abort，则此单为假单，不需要再将此单提交给快递100。
对于同一自然月内重复提交的快递单，结算时只计一次费用，对于跨了两个自然月重复提交的结算单，结算两次费用。
（2）如果判断到status=abort且comNew不为空，则不需要重新提交订阅，且将贵司原来的快递公司编码改为comNew后的值，或在贵司数据库中增加一个快递公司编码为comNew+原来单号的运单；
（3）如果判断到status=polling且autoCheck=1，则此单为纠正公司编码后的跟踪信息，应保存。
- 关于data：我方每次推送的都是完整的、全量的快递查询结果，而不是部分最新、增量的状态。由于同一快递单查询结果的数据源可能变动，不同数据源之间的结果略有差异，建议每次删除旧的数据后再写入新的数据。
- 时间建议以ftime为准，不要使用time，time的存在仅仅为了兼容。
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天无变化”）的快递单，也需要返回成功接收的响应报文及代码。
2.8 运单签收状态（已签收、退回等）增值服务说明
默认状态下，在推送时我们提供了ischeck字段表示快递单是否签收（含正常签收，退回签收两种情况），通过state字段提供签收的具体状态，state具体如下：
| 状态值 | 名称 | 含义 |
|---|---|---|
| 0 | 在途 | 快件处于运输过程中 |
| 1 | 揽收 | 快件已由快递公司揽收 |
| 2 | 疑难 | 快递100无法解析的状态，或者是需要人工介入的状态， 比方说收件人电话错误。 |
| 3 | 签收 | 正常签收 |
| 4 | 退签 | 货物退回发货人并签收 |
| 5 | 派件 | 货物正在进行派件 |
| 6 | 退回 | 货物正处于返回发货人的途中 |
| 7 | 转投 | 货物转给其他快递公司邮寄 |
| 10 | 待清关 | 货物等待清关 |
| 11 | 清关中 | 货物正在清关流程中 |
| 12 | 已清关 | 货物已完成清关流程 |
| 13 | 清关异常 | 货物在清关过程中出现异常 |
| 14 | 拒签 | 收件人明确拒收 |
签收状态服务能够对目前市面上大多数快递单状态进行准确判定。
若state=0,则condition如下值代表如下状态：
| 状态值 | 名称 | 含义 |
|---|---|---|
| CU001 | 等待清关 | 货物等待清关 |
| CU002 | 清关中 | 货物正在清关流程中 |
| CU003 | 已清关 | 货物已完成清关流程 |
| CU004 | 清关异常 | 货物在清关过程中出现异常 |
| JQ001 | 收件人拒签 | 收件人明确拒收 |
三、快递公司编码
<a href="https://api.kuaidi100.com/manager/openapi/download/kdbm.do" style="color: #027eff;" target="_blank"><u>下载表格</u></a>
一、地图轨迹推送服务API产品介绍
快递100地图轨迹推送服务接口提供快递单号的地图轨迹展示、物流节点文字信息及预计送达时间，可视化展示物流轨迹信息。
通过地图轨迹推送服务接口，企业提交快递单号，快递100接收到后便对这些运单进行跟踪，当运单状态发生变化的时候，快递100便通过调用回调接口将运单的跟踪信息和地图轨迹推送给贵公司，直到这些运单号的生命周期结束（一般以“已签收”为准）。对于某个单号，当贵方正确提交订阅了后，我们一般会在15分钟左右后进行第一次监控，如果监控到单号本身有了跟踪信息，即进行第一次推送，否则等待下一次监控。此后我们一般每4小时进行一次监控，并会根据单号的状态等因素作调整。
二、地图轨迹推送服务API应用场景
- 让顾客登录您的网站、APP、小程序后，直接在“我的订单”页面内就能看到订单的物流状态和快递地图轨迹；
- 和物流轨迹文字信息一同展示给顾客，可视化订单的在途状态；
- 获得物流途径城市的信息，监控快递时效；
- 预估包裹的到达时间，以及提示包裹还需多长时间到达，识别快递状态·，发送提醒客户签收短信；
- 能开发自动的、批量查单功能，自动筛选出“已签收”、“疑难件”等状态的单号，减轻跟单人员的压力；
- 改变订单的状态与交易流程，例如只要运单号变为“已签收”，就能让订单变更为可以确认退换货等；
- 核销销售人员，根据“已签收”的运单数，就能算出销售人员的业绩；
- 评估与选择快递公司，可获得快递实际在途时间，评估快递公司的时效，优化快递选择；
- 助结算运费，找出“已签收”的单及签收时间，便能轻松应对货到付款的结算与对账；
三、系统结构与流程
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/0fc2759fd0754030a6992d61b6e363ec~tplv-k3u1fbpfcp-zoom-1.image" alt="img" style="zoom: 67%;" />
四、快递信息推送API费用结算
1.收费方式
地图轨迹推送服务属于增值类服务，该服务同时支持物流文字信息以及地图链接，即包含了快递信息推送服务的功能。注册快递100企业账号后可以在企业管理后台查看地图轨迹套餐价格并购买。
2.收费价格
新品限时特惠，活动时间：2021年1月1日-2021年3月31日，充值后即可开通使用。
| 原价/元 | 优惠价/元 | 单量 | 赠送/单 | 优惠单价/元 |
|---|---|---|---|---|
| 2000 | 20000 | 5000 | 0.08 | |
| 1000 | 10000 | 2000 | 约0.084 | |
| 500 | 5000 | 500 | 约0.09 | |
| 100 | 1000 | 0.1 |
快递查询地图轨迹按单计费，一个自然月内同一个运单多次查询只收一次费用。该接口单独计费。
3. 开具发票
快递100支持开具增值税发票，用户购买完成后可在企业管理后台-费用中心-支付记录-请求开票。默认开具电子增值税普通发票，1000元以上可支持开具增值税专用发票。
官方源文档：
https://api.kuaidi100.com/document/603f45a0a52d305ab4d2a078.html
https://api.kuaidi100.com/document/5eb9f73186b0df4188313a03.html
https://api.kuaidi100.com/document/603f47dfa62a19500e19866f.html
