一、地图轨迹订阅接口

1.1 接口格局

1. 应用 http 协定表单提交的形式进行信息交互，字符编码默认对立采纳 UTF-8，数据格式：application/x-www-form-urlencoded；

2. 字段类型约定：须要严格根据字段表格中给出的参数格局和大小进行开发。

3. 字段解析约定：参数字段中的必选字段是每次调用接口时都要求必须传入的；

1.2 申请地址

http://poll.kuaidi100.com/pol…

申请报文：

param 数据结构：

parameters 数据结构：

1.3 申请示例

schema = json
 
  param = {
 
    "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 订阅返回后果

1.5 订阅响应报文示例（json 格局）

{
 
  "result": true,
 
  "returnCode": "200",
 
  "message": "提交胜利"
 
}

1.6 状态码附表

二、推送接口

1. 应用 http 协定表单提交的形式进行信息交互，字符编码默认对立采纳 UTF-8，数据格式：application/x-www-form-urlencoded；

2. 字段类型约定：须要严格根据字段表格中给出的参数格局和大小进行开发。

3. 字段解析约定：参数字段中的必选字段是每次调用接口时都要求必须传入的；

2.1 推送申请地址

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

2.2 推送申请形式

post

2.3 推送输出参数

申请参数（header）

申请报文（body）

param 对应参数

lastResult 对应参数

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 推送响应报文及错误码解释

2.7 推送返回示例

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

{
 
  "result":true,
 
  "returnCode":"200",
 
  "message":"胜利"
 
} 

留神：对于 status= abort（message 中蕴含“3 天查问无记录”或者“60 天无变动”）的快递单，也须要返回胜利接管的响应报文及代码。

2.8 运单签收状态（已签收、退回等）增值服务阐明

​ 默认状态下，在推送时咱们提供了 ischeck 字段示意快递单是否签收（含失常签收，退回签收两种状况），通过 state 字段提供签收的具体状态，state 具体如下：

签收状态服务可能对目前市面上大多数快递单状态进行精确断定。

若 state=0, 则 condition 如下值代表如下状态：

三、快递公司编码

<u> 下载表格 </u>

一、地图轨迹推送服务 API 产品介绍

快递 100 地图轨迹推送服务接口提供快递单号的地图轨迹展现、物流节点文字信息及预计送达工夫，可视化展现物流轨迹信息。

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

二、地图轨迹推送服务 API 利用场景

1. 让顾客登录您的网站、APP、小程序后，间接在“我的订单”页面内就能看到订单的物流状态和快递地图轨迹；
2. 和物流轨迹文字信息一起展现给顾客，可视化订单的在途状态；
3. 取得物流路径城市的信息，监控快递时效；
4. 预估包裹的达到工夫，以及提醒包裹还需多长时间达到，辨认快递状态·，发送揭示客户签收短信；
5. 能开发主动的、批量查单功能，主动筛选出“已签收”、“疑难件”等状态的单号，加重跟单人员的压力；
6. 扭转订单的状态与交易流程，例如只有运单号变为“已签收”，就能让订单变更为能够确认退换货等；
7. 核销销售人员，依据“已签收”的运复数，就能算出销售人员的业绩；
8. 评估与抉择快递公司，可取得快递理论在途工夫，评估快递公司的时效，优化快递抉择；
9. 助结算运费，找出“已签收”的单及签收工夫，便能轻松应答货到付款的结算与对账；

三、系统结构与流程

<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 日，充值后即可开明应用。

快递查问地图轨迹按单计费，一个天然月内同一个运单屡次查问只收一次费用。该接口独自计费。

3. 开具发票

快递 100 反对开具增值税发票，用户购买实现后可在企业治理后盾 - 费用核心 - 领取记录 - 申请开票。默认开具电子增值税普通发票，1000 元以上可反对开具增值税专用发票。

官网源文档：

http://api.kuaidi100.com/docu…
https://api.kuaidi100.com/doc…
http://api.kuaidi100.com/docu…