开发者 API

鉴权

在控制台创建 API Key，通过请求头传入。Key 只在创建时显示一次，请妥善保存；泄露后在控制台吊销即可，立即失效。

X-API-Key: xt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 或
Authorization: Bearer xt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

接口支持跨域调用（CORS），但请不要把 Key 写进面向公众的前端代码里——任何人都能从浏览器里把它取走。

限流与额度

两件事分开计：速率限制按「每个 Key 每分钟的请求数」，额度按「账号每个自然月（UTC）查过的不同单号数」。两者的上限都由套餐决定。

计额度的规则：同一个单号当月重复查询只计一次；格式非法、识别不出承运商、承运商未接入的单号不计；一批里只要会超出额度，整批拒绝、一个都不扣。

批量查询轨迹

一次查询多个单号（上限见套餐的「单次批量」）。carrier_code 可省略，省略时自动识别；数组元素也可以直接写成字符串。

{
  "trackings": [
    { "tracking_number": "00340434161094000019", "carrier_code": "dhl" },
    "1Z999AA10123456784"
  ]
}

{
  "request_id": "9f2c51d0a1b3e4f7",
  "trackings": [ /* 与请求顺序一致的轨迹对象，见下文 */ ],
  "quota": { "period": "month", "used": 128, "limit": 2000, "counted": 2 }
}

查询单个单号

返回 { tracking, quota }。carrier_code 可选。

识别承运商

只按单号格式给出候选承运商（按可信度排序），不查询轨迹、不计额度。live 表示该承运商已接入实时查询。

{ "tracking_number": "1Z999AA10123456784" }
→ { "tracking_number": "1Z999AA10123456784", "candidates": [{ "code": "ups", "name": "UPS", "live": false }] }

承运商目录

返回全部承运商的 code、名称、国家，以及是否已接入实时查询（live）。carrier_code 参数取值以这里为准。

套餐与用量

返回当前套餐的限额、订阅到期时间，以及本月已用与剩余额度。

MCP 接口：让 AI 助手直接查轨迹

除了 REST，我们还提供 MCP（Model Context Protocol）接口。把下面的地址加进 Claude、Cursor 这类支持 MCP 的客户端，就可以直接对它说「帮我查一下这几个单号到哪了」。

用的是同一把 API Key，限流与额度也和 REST 接口共用一份——MCP 只是另一种调用方式，不另外计费。

{
  "mcpServers": {
    "xtrack": {
      "type": "http",
      "url": "https://xtrack.mcwoms.com/mcp",
      "headers": { "Authorization": "Bearer xt_live_••••••••" }
    }
  }
}

claude mcp add --transport http xtrack https://xtrack.mcwoms.com/mcp \
  --header "Authorization: Bearer xt_live_••••••••"

提供的工具

实现细节：采用 Streamable HTTP 传输、无状态——每个请求自带 Key 独立处理，不建会话、不开 SSE 长连接（GET 会返回 405）。额度用完、承运商代码不对这类失败会放在工具结果的 isError 里返回，方便模型读到原因后自行调整。

轨迹对象

{
  "tracking_number": "00340434161094000019",
  "carrier": { "code": "dhl", "name": "DHL Paket", "name_zh": "DHL 德国包裹" },
  "status": "out_for_delivery",
  "stage": 3,                      // 0–4，画进度条用
  "status_description": "…",
  "latest_event": { "time": "2026-09-18T08:12:00", "description": "…", "location": "Braunschweig, DE", "code": "PO" },
  "events": [ /* 新 → 旧 */ ],
  "delivered_at": null,
  "updated_at": "2026-09-18T06:20:31.000Z",  // 我们取回这份数据的时间（UTC）
  "cached": true,
  "official_url": "https://www.dhl.de/…"
}

注意：events[].time 是承运商给出的当地时间，不带时区，请按原样展示，不要做时区换算。updated_at 才是带时区的 UTC 时间。

状态取值

错误码

失败时返回对应的 HTTP 状态码，响应体统一为：

{ "error": { "code": "QUOTA_EXCEEDED", "message": "…", "details": { "used": 100, "limit": 100 } }, "request_id": "…" }

注意：单个单号「没查到」不是错误——接口仍返回 200，由该单号的 status（not_found / unsupported / unavailable 等）表达。