一. 什么是物流追踪

Tracking API 的主要特性如下：

• 一次订阅自动跟踪并推送查询结果，期间不再扣费（异步接口，不建议使用在前台网页、小程序、APP中）。
• 企业级的数据处理能力，每小时可订阅 40万个物流单号。
• 集成全球 2000+ 运输商，统一的调用方式、响应结构、状态节点，从而降低开发成本。
• 强烈建议在您的服务器或存储服务中保留物流信息。
• 数据的唯一标识通过物流单号 + 运输商组合实现。
• 运行流程概述：订阅单号 >> 服务定时跟踪 >> 服务检查变更 >> 推送结果

二. 使用前必备事项

2.1 创建 17TRACK 账号

2.2 物流单号和运输商代码

• 准备好的物流单号，可以访问 17TRACK - 全球物流查询平台 进行验证。
• 可以访问 运输商列表 查看已集成的运输商。
• 什么是运输商代码？运输商代码是专为使用 Tracking API 制定参数规范，请参考 运输商代码。举例：USPS的运输商代码 是 21051

三. 对接指引

3.1 自研系统对接方案

用户画像

第一步

1.  请确认服务器能被公网访问（防火墙、网关等配置已完成调整）。
2.  请完成接收信息的接口开发，确认接口能承受高并发的访问，建议有独立服务来分发数据（如：队列、缓存等）。
3.  在接收信息接口中完成签名验证逻辑，以保证信息来源安全有效。请参考 验证签名流程，示例代码如下：

/**
* requestText {String} 原始通知报文
* key      {String} 密钥
* return    {String} 生成签名内容
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {

    String src = requestText + "/" + key;

    MessageDigest md = MessageDigest.getInstance("SHA-256");
    byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));

    BigInteger number = new BigInteger(1, hash);
     StringBuilder hexString = new StringBuilder(number.toString(16));
    while (hexString.length() < 64) {
        hexString.insert(0, '0');
    }
    return hexString.toString();
}

第二步

1. 获取密钥，请登录 访问 API 设置页 Api-设置
2. 设置接收信息接口，请登录 访问 API 设置页 Api-设置，在 WebHook 区域填入接口 URL。

第三步

1. 调用注册接口（/register）订阅物流单号，建议把业务系统中数据 ID 通过 tag 传入，以方便接收到推送结果后使用。（接口参考：注册物流单号）

第四步

1. 监听接收信息接口运行情况，为保证跟踪结果及时有效的被业务使用，要注意：推送可能是持续的并发状态， 每次推送是全量数据，若无法正常接收时临时返回非 200 状态码，17侧补偿推送参见这里 推送策略 ，如果找不到跟踪结果，有可能是以下几种情况：
   • 正在跟踪需要等待。（正常情况下首次抓取在 1 分钟内会有结果，后续每 24 小时抓取 3~4 次直到签收）
   • 检查物流单号，如果有错误，请调用删除单号接口 (/deletetrack)，再重新订阅。
   • 检查运输商，如果有错误，请调用修改运输商接口 (/changecarrier)处理。
   • 有可能是因为运输商接口异常导致未返回数据。
   • 有可能是运输商未更新数据（未上网）。
   • 有可能是部分渠道订阅时未填附加跟踪参数，如：手机尾号、邮编等。
   • 有可能是连续 30 天运输商未更新数据系统将停止自动跟踪。

3.2 第三方系统商对接方案

用户画像

• 中小型物流商、中型商家
• 系统产品：ERP、TMS、WMS、CRM等

第一步

1. 请系统商确认，当前所使用的系统可支持 Webhook 方式接收推送跟踪数据。[区别于自研系统]
2. 请系统商确认，如果不支持推送，是否支持备选方案：通过调用获取详情接口 (/gettrackinfo) 定时拉取数据。（此方式不能保证与推送方式一样的数据回传效率，也是17不推荐的方式。）[区别于自研系统]
3. 请系统商确认，是否支持17TRACK API接入使用？如支持则要确认目前的接入版本是否能满足业务需要，如不能则要与系统商协商选择版本再接入。[区别于自研系统]
4. 如果支持推送，那么在接收信息接口中完成签名验证逻辑，以保证信息来源安全有效。请参考 验证签名流程，示例代码如下：

/**
* requestText {String} 原始通知报文
* key      {String} 密钥
* return    {String} 生成签名内容
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {

   String src = requestText + "/" + key;

   MessageDigest md = MessageDigest.getInstance("SHA-256");
   byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));

   BigInteger number = new BigInteger(1, hash);
 StringBuilder hexString = new StringBuilder(number.toString(16));
   while (hexString.length() < 64) {
       hexString.insert(0, '0');
   }
   return hexString.toString();
}

第二步

1. 获取密钥，登录 API 控制台，在设置页获取密钥并将密钥交给系统商负责接入业务的服务人员。（请访问 Api-设置）[区别于自研系统]
2. 若系统商不支持推送方式则跳过此步骤。若支持请联系系统商提供推送接口(URL)。（请访问 Api-设置）[区别于自研系统]

第三步

1. 建议客户让系统商在调用注册接口（/register）订阅物流单号时，把业务系统中数据 ID 通过 tag 传入，以方便接收到推送结果后使用。（接口参考：注册物流单号）[区别于自研系统]

第四步

1. 请客户登录所使用的系统，在物流跟踪板块查看抓取情况（具体请系统商客服来支持和解答）。[区别于自研系统]
2. 监听接收信息接口运行情况，为保证跟踪结果及时有效的被业务使用，要注意：推送可能是持续的并发状态， 每次推送是全量数据，若无法正常接收时临时返回非 200 状态码，17侧有补偿推送参见这里 推送策略 ，如果找不到跟踪结果，有可能是以下几种情况：
   • 正在查询中需要等待。（正常情况下首次抓取 1 分钟内会有结果，后续每 24 小时抓取 3~4 次直到签收）
   • 检查物流单号，如果错误请删除单号重新订阅。
   • 检查运输商，如果指定错误，请调用修改运输商接口(/changecarrier)处理。
   • 有可能是因为接口异常运输商未返回数据。
   • 有可能是运输商未更新数据（未上网）。
   • 有可能是部分渠道订阅时未填附加跟踪参数，如：手机尾号、邮编等。

   • 有可能是连续 30 天运输商未更新数据系统自动停止跟踪。

四. 版本说明

主版本

子版本

1. 增加 3 个清关子状态，
2. 增加事件状态节点。
3. 注册接口支持订单编号和备注参数。
4. 获取列表接口增加订单编号、时效等信息返回。

1. 增加物流事件发生时间的原始信息结构。