01 · OVERVIEW

概览与开通

通过开放 API 批量注册物流单号，系统自动持续跟踪，你可以随时轮询查询最新轨迹，或让平台在轨迹变化时主动推送到你的服务器。

两种接入模式

模式	需要做什么	适合场景
轮询模式	只需 API Key。注册单号后定时调用查询接口获取最新轨迹，不需要写任何验签代码。	快速接入、低频查询、不方便对外暴露回调地址
Webhook 推送	在凭证上配置 `webhook_url`，实现签名校验与幂等处理。轨迹变化时平台实时 POST 到你的服务器。	大批量单号、对时效敏感、不想自己维护轮询任务

两种模式可以同时使用：配置了 webhook_url 后，查询接口依然可用。刚开始接入建议先跑通轮询模式（见下一章「快速开始」），再按需升级到 Webhook。

如何开通 API 权限

账号累计充值达到 500,000 积分后，联系客服开通。开通后在控制台「API & Webhook」页面创建凭证即可获得 API Key。开通前也可以先阅读本文档评估接入方案。

Base URL

https://frogtracking.com/api

鉴权

所有接口使用 Bearer Token 鉴权。创建凭证时会一次性展示完整的 API Key（格式 ak_<key_id>.<secret>），请妥善保存——服务端不保留明文，丢失只能重置。

Authorization: Bearer ak_xxxx.yyyyyyyyyyyy

以下任一情况会返回 401 Unauthorized：Key 格式错误或不存在；凭证被禁用或删除；账号的 API 权限被关闭。

02 · QUICKSTART

快速开始

最小可用路径只有三步，全程不需要写验签代码。

第 1 步：创建凭证

进入控制台「API & Webhook」页面，点击「创建凭证」。轮询模式下 webhook_url 留空即可。创建成功后弹窗会展示完整 API Key，仅此一次，请立即保存。

第 2 步：注册单号

curl -X POST "https://frogtracking.com/api/openapi/v1/trackings/register" \
  -H "Authorization: Bearer ak_xxxx.yyyyyyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"tracking_number": "9300110990413251585279"}]}'

第 3 步：查询轨迹

curl "https://frogtracking.com/api/openapi/v1/trackings/9300110990413251585279" \
  -H "Authorization: Bearer ak_xxxx.yyyyyyyyyyyy"

首次抓取通常几秒到几分钟内完成。响应里 task_status 变为 completed 后，status 和 events 就是最新轨迹。之后系统会自动按固定节奏持续重查（见「重试与自动跟踪」章节），你只需按自己的业务频率轮询查询接口。

需要实时推送？

在凭证上配置 webhook_url 后，轨迹变化会实时 POST 到你的服务器。详见「Webhook 推送」与「验签示例」两章。

03 · REGISTER

注册物流单号

批量提交单号进入自动跟踪，单次最多 100 条。

POST https://frogtracking.com/api/openapi/v1/trackings/register
Headers:
  Authorization: Bearer ak_xxxx.yyyyyyyyyyyy
  Content-Type: application/json

Body:
{
  "items": [
    {"tracking_number": "9300110990413251585279"},
    {"tracking_number": "UUS123ABC456DEF78", "carrier": "uniuni"}
  ]
}

规则

单号会自动去除首尾空格并转为大写。
carrier 可选，不传自动识别。传入时单号必须符合该承运商的格式（取值见「承运商列表」），否则该条失败；不传且单号同时命中多家承运商时该条返回 carrier_ambiguous，请从 candidates 里选一家带 carrier 重新注册。
同一凭证重复注册同一单号是幂等的：不会重复扣积分，已停止的订阅会自动恢复跟踪。

成功响应

HTTP/1.1 200 OK

{
  "successes": [
    {"tracking_number": "9300110990413251585279", "carrier": "usps"},
    {"tracking_number": "UUS123ABC456DEF78", "carrier": "uniuni"}
  ],
  "failures": []
}

未传 carrier 的单号，successes[].carrier 返回系统识别出的承运商。

失败响应

部分单号校验失败

HTTP/1.1 200 OK

{
  "successes": [
    {"tracking_number": "9300110990413251585279", "carrier": "usps"}
  ],
  "failures": [
    {"tracking_number": "UUS123ABC456DEF78", "carrier": "uniuni", "message": "carrier_mismatch", "candidates": []},
    {"tracking_number": "ABC123", "carrier": null, "message": "unsupported_carrier", "candidates": []},
    {"tracking_number": "EXAMPLE000000000001", "carrier": null, "message": "carrier_ambiguous", "candidates": ["usps", "fedex"]}
  ]
}

failures[].candidates 只在 carrier_ambiguous 时非空，按识别优先级排列、第一个是系统默认候选；其余失败为空数组。

积分余额不足（本批全部失败，不扣分）

HTTP/1.1 200 OK

{
  "successes": [],
  "failures": [
    {"tracking_number": "9300110990413251585279", "carrier": "usps", "message": "billing_failed:USER_WALLET_BALANCE_INSUFFICIENT", "candidates": []}
  ]
}

部分失败时 HTTP 状态码仍是 200

单条校验失败与计费失败都不会让整个请求报错，请务必检查响应里的 failures 数组。

鉴权失败

HTTP/1.1 401 Unauthorized

{
  "detail": "Unauthorized"
}

参数校验失败（整个请求不处理）

HTTP/1.1 422 Unprocessable Entity

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "items", 0, "carrier"],
      "msg": "Value error, unknown or disabled carrier: dhl",
      "input": "dhl",
      "ctx": {"error": {}}
    }
  ]
}

触发条件	detail[].type	detail[].loc
items 为空	`too_short`	`["body", "items"]`
items 超过 100 条	`too_long`	`["body", "items"]`
缺少 tracking_number	`missing`	`["body", "items", 0, "tracking_number"]`
tracking_number 超过 64 个字符	`string_too_long`	`["body", "items", 0, "tracking_number"]`
carrier 不存在或已停用	`value_error`	`["body", "items", 0, "carrier"]`

`failures[].message` 含义

message	含义
`invalid_format`	单号为空，或传入了 carrier 但单号无法识别为任何支持的承运商格式
`unsupported_carrier`	未传 carrier，且单号无法识别为任何支持的承运商格式
`carrier_mismatch`	传入的 carrier 与单号格式不符（单号不符合该承运商的任何识别规则）
`carrier_ambiguous`	未传 carrier，且单号同时符合多家承运商的格式；candidates 列出候选 code，请带 carrier 重新注册
`billing_failed:*`	计费失败（最常见原因是积分余额不足）。此时本批所有单号都会失败，且不会扣分

04 · QUERY

查询单号状态

查询当前凭证下已注册单号的最新状态与完整轨迹。

GET https://frogtracking.com/api/openapi/v1/trackings/{tracking_number}
Headers:
  Authorization: Bearer ak_xxxx.yyyyyyyyyyyy

成功响应

HTTP/1.1 200 OK

{
  "carrier": "usps",
  "tracking_number": "9300110990413251585279",
  "task_status": "completed",
  "status": "in_transit",
  "status_description": "Your item departed our USPS facility in DALLAS TX.",
  "events": [
    {"message": "Departed USPS Regional Facility", "location": "DALLAS TX DISTRIBUTION CENTER", "timestamp": "2026-05-20T02:11:00Z"},
    {"message": "Shipping Label Created", "location": "PLANO, TX 75074", "timestamp": null}
  ],
  "sync_at": "2026-05-20T06:00:12Z",
  "sync_count": 3,
  "created_at": "2026-05-18T05:05:29Z",
  "subscription_status": "active",
  "stop_reason": null
}

task_status 和 status 是两个不同维度

task_status 表示抓取任务的执行状态（是否已从承运商拿到数据）；status 表示包裹本身的物流状态。刚注册的单号 task_status 为 pending、status 为 null，等任务完成后 status 才有值。

字段说明

字段	说明
`carrier`	承运商 code，见「承运商列表」
`tracking_number`	单号（已规范化为大写）
`task_status`	抓取任务状态：`pending` 待抓取 / `processing` 抓取中 / `completed` 已完成 / `failed` 抓取失败（系统会自动重试）
`status`	物流主状态，任务完成前为 null，枚举值见「枚举参考」
`status_description`	承运商返回的最新状态描述原文
`events`	完整轨迹事件列表，按时间倒序（最新在前）；timestamp 可能为 null
`sync_at`	最近一次成功抓取的时间
`sync_count`	累计抓取次数
`created_at`	单号在本凭证下的创建时间
`subscription_status`	订阅状态：`active` 跟踪中 / `stopped` 已停止
`stop_reason`	停止原因，仅 stopped 时有值，见「重试与自动跟踪」

失败响应

单号未在当前凭证下注册，或已取消订阅

HTTP/1.1 400 Bad Request

{
  "code": "WEBHOOK_SUBSCRIPTION_NOT_FOUND",
  "message": "subscription_not_found"
}

鉴权失败

HTTP/1.1 401 Unauthorized

{
  "detail": "Unauthorized"
}

05 · CANCEL

取消订阅

停止某个单号的自动跟踪与推送。

DELETE https://frogtracking.com/api/openapi/v1/trackings/{tracking_number}
Headers:
  Authorization: Bearer ak_xxxx.yyyyyyyyyyyy

取消后该单号不再自动重查、不再产生 Webhook 推送（订阅变为 stopped，stop_reason=manual），之后查询该单号返回 subscription_not_found。
重新调用注册接口即可恢复跟踪；计费窗口内恢复不会重复扣分。

成功响应

HTTP/1.1 204 No Content

失败响应

单号未在当前凭证下注册，或已取消订阅

HTTP/1.1 400 Bad Request

{
  "code": "WEBHOOK_SUBSCRIPTION_NOT_FOUND",
  "message": "subscription_not_found"
}

鉴权失败

HTTP/1.1 401 Unauthorized

{
  "detail": "Unauthorized"
}

06 · CARRIERS

承运商列表

返回当前启用的承运商，code 即注册接口 items[].carrier 的取值。

GET https://frogtracking.com/api/openapi/v1/carriers

无需鉴权。响应带 Cache-Control: public, max-age=300。

成功响应

HTTP/1.1 200 OK

[
  {"code": "usps", "name": "USPS", "website_url": "https://www.usps.com"},
  {"code": "uniuni", "name": "UniUni", "website_url": "https://uniuni.com"},
  {"code": "swiftx", "name": "SwiftX", "website_url": null}
]

字段说明

字段	说明
`code`	承运商代码，小写
`name`	承运商名称
`website_url`	官网地址，可为 null

说明

承运商由平台维护并会增减，请缓存本接口结果并定期刷新，勿硬编码。
carrier 参数不区分大小写；传入不存在或已停用的 code，整个注册请求返回 422。
承运商停用后，历史单号仍保留原 code，查询与 Webhook 可能返回不在本列表中的值。

当前支持的承运商

承运商列表加载中...

08 · WEBHOOK

Webhook 推送

在凭证上配置 webhook_url 后，单号轨迹发生变化时平台会实时 POST 到你的服务器。

触发时机

注册成功后：若该单号已有现成轨迹，会立刻推送一条作为首推；新单号则在首次抓取完成后推送。
之后每次自动重查发现轨迹变化（状态、状态描述或事件列表任一变化）都会推送一条；无变化不推送。
每次推送的 data.events 都是该单号的全量轨迹（完整事件列表，非增量），接收端直接用最新一条推送整体覆盖本地数据即可。

推送格式

POST <your webhook_url>
Content-Type: application/json
User-Agent: FrogTracking-Webhook/1.0
X-Webhook-Id: 8f5e3b2c-...              ← 投递唯一 ID (重试同一事件共用同 ID)
X-Webhook-Timestamp: 1716100000         ← unix 秒
X-Webhook-Event: tracking.updated
X-Webhook-Signature: t=1716100000, v1=<hex sha256>[, v1=<hex sha256>]

{
  "id": "8f5e3b2c-...",
  "event": "tracking.updated",
  "occurred_at": "2026-05-18T05:05:30.0Z",
  "data": {
    "carrier": "usps",
    "tracking_number": "9300110990413251585279",
    "status": "info_received",
    "status_description": "...",
    "events": [
      {"message": "Shipping Label Created", "location": "PLANO, TX 75074", "timestamp": null}
    ],
    "sync_at": "2026-05-18T05:05:29.994831Z",
    "subscription_id": "uuid"
  }
}

接收端必须做的 3 件事：

校验时间戳：|now - X-Webhook-Timestamp| > 300s 则拒绝（防重放）
校验签名：用 webhook_secret 计算 HMAC-SHA256("<timestamp>.<raw_body>")，hex 后与 X-Webhook-Signature 里任一 v1= 值匹配（代码见「验签示例」）
幂等处理：X-Webhook-Id 持久化 7 天，重复收到直接返回 200 但跳过业务（at-least-once 投递）

密钥轮换期间会同时签发两个 v1= 值（新+旧），任意匹配即视为有效。

尽快返回 2xx

收到推送后建议先落库、返回 200，再异步处理业务。响应超过 10 秒会被判为投递失败并进入重试（见「重试与自动跟踪」）。

09 · VERIFY

验签示例

三种语言的完整验签实现，可直接复制使用。

import hashlib
import hmac
import time


def verify_webhook(
    secret: str,
    timestamp: str | int,
    raw_body: bytes,
    signature_header: str,
    tolerance_seconds: int = 300,
) -> bool:
    """
    校验 FrogTracking webhook 签名。

    Args:
        secret: 你的 webhook_secret（轮换期内也可传 webhook_secret_prev 二次校验）。
        timestamp: X-Webhook-Timestamp 头的值。
        raw_body: 请求体的**原始字节**——不要 JSON 再序列化。
        signature_header: X-Webhook-Signature 头的值。
        tolerance_seconds: 时间戳容差，默认 300s。

    Returns:
        True 表示签名与时间戳均有效。
    """
    # 1) 时间戳容差（防重放）
    try:
        ts_int = int(timestamp)
    except (TypeError, ValueError):
        return False
    if abs(int(time.time()) - ts_int) > tolerance_seconds:
        return False

    # 2) 提取 v1= 签名（轮换期可能有多个）
    if not signature_header:
        return False
    sigs: list[str] = [
        part.split("=", 1)[1].strip()
        for part in signature_header.split(",")
        if part.strip().startswith("v1=")
    ]
    if not sigs:
        return False

    # 3) 常数时间比对
    expected: str = hmac.new(
        secret.encode("utf-8"),
        f"{ts_int}.".encode("utf-8") + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return any(hmac.compare_digest(expected, sig) for sig in sigs)

10 · LIFECYCLE

重试与自动跟踪

单号注册后的自动重查节奏、订阅停止规则，以及 Webhook 投递失败后的重试策略。

自动重查节奏

注册成功后几秒内尝试首次抓取（可能因网络/承运商延迟 5+ 分钟）
非终态（运输中、派送中等）：按承运商设定的区间重查，通常数小时到一天一次（区间内随机抖动，避免集中）
终态（已签收 / 邮资未付 / 投递失败 / 异常 / 退回 / 过期）：按承运商设定的固定间隔重查，通常约一天一次
连续一段时间没有新的轨迹事件时，重查间隔会逐步拉长

订阅自动停止（`stop_reason`）

stop_reason	触发条件
`no_events`	长时间没有产生新的轨迹事件
`delivered`	已签收，一段时间后自动停止
`postage_unpaid`	邮资未付，一段时间后自动停止
`manual`	通过取消订阅接口主动停止

停止后不再重查、不再推送；重新调用注册接口即可恢复跟踪。

Webhook 投递重试

你的服务器返回 2xx 即视为投递成功；非 2xx 响应、连接失败或超时（默认 10 秒）视为失败。
失败后按指数退避自动重试：30s → 60s → 2m → 5m → 15m → 1h → 3h → 6h → 12h → 24h（每次 ±20% 抖动），默认最多重试 10 次。
重试同一事件时 X-Webhook-Id 保持不变，接收端按此做幂等。
超过重试上限后该条事件被永久放弃，但不影响订阅本身——之后的新事件仍会正常推送。

接收端故障期间会不会丢事件？

单条事件最长会在约 2 天内持续重试（退避序列累计），期间恢复服务即可收到。若故障超过重试窗口，被放弃的事件不会补发，恢复后建议用查询接口对账一次。

推送失败如何排查

在控制台「API & Webhook」凭证详情页：「推送记录」Tab 可按状态与单号筛选查看该凭证下每条事件的推送日志（HTTP 响应码、失败原因、重试次数与下次重试时间），事件 ID 可复制后与接收端日志里的 X-Webhook-Id 对账；「物流轨迹」Tab 可核对系统实际抓取到的轨迹数据。

11 · ERRORS

错误码参考

接口可能返回的 HTTP 状态码与错误响应格式。

HTTP 状态码

状态码	含义
`200`	请求成功。注意注册接口部分单号失败时也返回 200，需检查 `failures`
`204`	取消订阅成功，无响应体
`400`	业务错误，响应体见下方格式
`401`	鉴权失败：Key 格式错误或不存在 / 凭证被禁用或删除 / 账号 API 权限被关闭
`422`	参数校验失败（如 items 为空或超过 100 条、字段类型错误），响应体为 `{"detail": [...]}`

400 业务错误格式

{
  "code": "WEBHOOK_SUBSCRIPTION_NOT_FOUND",
  "message": "subscription_not_found"
}

code	触发场景
`WEBHOOK_SUBSCRIPTION_NOT_FOUND`	查询或取消的单号未在当前凭证下注册过，或已被删除

注册接口的单条失败（invalid_format / unsupported_carrier / carrier_mismatch / carrier_ambiguous / billing_failed）不走 400，而是出现在 200 响应的 failures 数组里，见「注册物流单号」章节。

12 · ENUMS

枚举参考

接口出入参用到的固定枚举值。

承运商 carrier 由平台在后台维护、会随时增减，不属于固定枚举，取值见「承运商列表」。

物流主状态 status（查询接口 / Webhook `data.status`）

枚举值	含义
not_found	未找到
info_received	已下单
in_transit	运输中
picked_up	已揽收
out_for_delivery	派送中
available_for_pickup	到达待取
undelivered	投递失败
delivered	已签收
alert	异常
return	退回
postage_unpaid	邮资未付
expired	已过期
unknown	未知

抓取任务状态 task_status（查询接口 `task_status`）

枚举值	含义
pending	待处理
processing	处理中
completed	已完成
failed	失败

新增的状态会逐步上线，建议接收端对未识别值容错处理（透传保存或归类为 unknown）。

概览与开通

两种接入模式

Base URL

鉴权

快速开始

第 1 步：创建凭证

第 2 步：注册单号

第 3 步：查询轨迹

注册物流单号

规则

成功响应

失败响应

failures[].message 含义

查询单号状态

成功响应

字段说明

失败响应

取消订阅

成功响应

失败响应

承运商列表

成功响应

字段说明

说明

当前支持的承运商

计费规则

什么时候不扣分

结果复用

Webhook 推送

触发时机

推送格式

验签示例

重试与自动跟踪

自动重查节奏

订阅自动停止（stop_reason）

Webhook 投递重试

错误码参考

HTTP 状态码

400 业务错误格式

枚举参考

物流主状态 status（查询接口 / Webhook data.status）

抓取任务状态 task_status（查询接口 task_status）

`failures[].message` 含义

订阅自动停止（`stop_reason`）

物流主状态 status（查询接口 / Webhook `data.status`）

抓取任务状态 task_status（查询接口 `task_status`）