快速开始

Tracksuite 为企业提供统一的多承运商运单追踪能力。通过 Tracksuite API，你可以创建跟踪并查询当前状态和完整轨迹；结合 Webhook，可在状态或轨迹变化时自动接收更新，用于同步订单系统和构建售后追踪体验。

本指南面向首次接入 Tracksuite 的开发者。你将通过三个实际接入用例，了解 Tracksuite API 的工作方式，以及 API 与 Webhook 的推荐接入方式。

1. 获取 API 密钥

Tracksuite 使用 API 密钥识别并验证用户身份。要完成身份验证，请确保将您的密钥放在 Authorization 请求标头中。

API token 在账户注册时自动生成。获取方式如下：

2. API 地址

所有 Gateway API 端点都基于以下 URL，并通过 HTTPS 调用：

https://api.tracksuite.net

3. 常见用例

以下三个用例组成一次完整的运单追踪接入。

用例 1：创建跟踪

在本文档中，“跟踪”是指 Tracksuite 中的一条运单追踪记录，包含业务标识、运单号和可选的承运商编码。

创建跟踪时，需要提供 referId 和 rawTrackingNumber。referId 来自你自己的系统，例如订单号；rawTrackingNumber 是快递公司提供的运单号。承运商编码 metadata.carrierCode 可以不传，Tracksuite 会根据运单号自动识别。

方式 1：v1 批量创建

POST https://api.tracksuite.net/api/v1/routers/create

每次可以创建 1–40 条跟踪，并获得包含实时跟踪信息的响应。以下示例创建一条 USPS 跟踪：

curl 'https://api.tracksuite.net/api/v1/routers/create' \
  -H 'Authorization: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"data":[{"referId":"order-10001","rawTrackingNumber":"9400111899223857461234","metadata":{"carrierCode":"usps"}}]}'

方式 2：v2 异步创建

POST https://api.tracksuite.net/api/v2/trackings/create

每次可以创建 1–1000 条跟踪。请求受理后，Tracksuite 会在后台异步处理：

curl 'https://api.tracksuite.net/api/v2/trackings/create' \
  -H 'Authorization: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"data":[{"referId":"order-10002","rawTrackingNumber":"9400111899223857465678","metadata":{"carrierCode":"usps"}}]}'

请求成功表示批次已进入异步处理。每条跟踪的结果可通过查询接口或 Webhook 获取。

用例 2：查询状态与轨迹

创建跟踪后，可以通过 referId 或运单号查询。使用 referId 可以直接将查询结果映射回你系统中的订单。

以下示例查询刚才创建的 order-10001 跟踪：

curl 'https://api.tracksuite.net/api/v1/routers/detail?referId=order-10001' \
  -H 'Authorization: your_api_key'

如果使用方式 2，异步处理未完成时，查询会返回 message 为 Processing。可以稍后查询，或等待 Webhook 更新。

用例 3：接收跟踪更新

为了及时了解您的货件进度，你可以反复调用查询接口获取最新状态。如果您希望接收主动通知，并在追踪信息未更新时避免不必要的 API 调用，建议您使用 Webhook。借助 Tracksuite，您可以通过 Webhook 接收全部跟踪更新，或只接收选定的运单状态。

请登录 Tracksuite 管理门户，转到“设置”部分的“API 与 Webhook”，配置您的端点 URL 以接收通知。

出于安全考虑，请添加我们在同一页面提供的 Webhook 密钥以实现 SHA256 签名验证。

配置完成后，你的服务器会收到类似下面的推送：

[
  {
    "eventId": "8f2c1e6a-4b3d-4c91-9a10-2d7f6e5c8b11",
    "event": "router.delivered",
    "eventTime": "2026-07-10T12:05:00.000Z",
    "data": {
      "trackingNumber": "9400111899223857461234",
      "status": 1,
      "statusTrack": "delivered",
      "routerId": "550e8400-e29b-41d4-a716-446655440000",
      "summary": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "trackingNumber": "9400111899223857461234",
        "status": 1,
        "statusLabel": "DELIVERED",
        "latestEvent": "Delivered",
        "latestCheckpointTime": "2026-07-10T12:00:00.000Z",
        "transitTime": 5,
        "created": "2026-07-07T09:00:00.000Z",
        "updated": "2026-07-10T12:05:00.000Z"
      },
      "detail": {
        "trackingNumber": "9400111899223857461234",
        "statusSummary": "Delivered",
        "trackingEvents": [
          {
            "eventType": "Delivered",
            "eventCity": "LAS VEGAS",
            "eventState": "NV",
            "eventZIPCode": "89101",
            "eventTimestamp": "2026-07-10T05:00:00",
            "GMTTimestamp": "2026-07-10T12:00:00Z"
          },
          {
            "eventType": "Out for Delivery",
            "eventCity": "LAS VEGAS",
            "eventState": "NV",
            "eventZIPCode": "89101",
            "eventTimestamp": "2026-07-10T02:10:00",
            "GMTTimestamp": "2026-07-10T09:10:00Z"
          },
          {
            "eventType": "In Transit to Next Facility",
            "eventCity": "LAS VEGAS",
            "eventState": "NV",
            "eventZIPCode": "89101",
            "eventTimestamp": "2026-07-09T18:20:00",
            "GMTTimestamp": "2026-07-10T01:20:00Z"
          }
        ]
      },
      "error": null
    }
  }
]