> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 轮询跟踪更新

> 如何获取并使用标准化跟踪数据进行客户通知

<Note>
  此页面由英文翻译而成。[英文版](/introduction)为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。
</Note>

# 轮询跟踪更新

使用 `GET /tracking/{id}` 以统一格式获取实时发货跟踪数据。本指南涵盖轮询流程、如何解读跟踪状态，以及构建客户通知的模式。

## 获取跟踪数据

使用标签创建响应中的 `id`：

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479',
    { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }
  );
  const tracking = await response.json();
  console.log(tracking.tag); // High-level status: InTransit, Delivered, etc.
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
  )
  tracking = response.json()
  print(tracking['tag'])  # High-level status: InTransit, Delivered, etc.
  ```
</CodeGroup>

### 响应

```json 200 OK theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "trackingNumber": "YT2503010001CN",
  "tag": "InTransit",
  "subtag": "InTransit_001",
  "subtagMessage": "In transit",
  "slug": "yunexpress",
  "checkpoints": [
    {
      "checkpointTime": "2026-03-17T08:15:00Z",
      "city": "Los Angeles",
      "state": "CA",
      "countryRegion": "US",
      "location": "LAX Distribution Center",
      "message": "Arrived at destination country",
      "tag": "InTransit",
      "subtag": "InTransit_001",
      "subtagMessage": "In transit",
      "slug": "yunexpress"
    },
    {
      "checkpointTime": "2026-03-16T02:30:00Z",
      "city": "Shenzhen",
      "state": "Guangdong",
      "countryRegion": "CN",
      "location": null,
      "message": "Departed from sorting center",
      "tag": "InTransit",
      "subtag": "InTransit_001",
      "subtagMessage": "In transit",
      "slug": "yunexpress"
    },
    {
      "checkpointTime": "2026-03-15T10:30:00Z",
      "city": "Tokyo",
      "state": "Tokyo",
      "countryRegion": "JP",
      "location": null,
      "message": "Shipment information received",
      "tag": "InfoReceived",
      "subtag": "InfoReceived_001",
      "subtagMessage": "Shipment information received",
      "slug": "yunexpress"
    }
  ]
}
```

检查点按最新事件排在最前面。

## 了解跟踪状态

使用顶层的 `tag` 字段来实现高级别的状态逻辑：

| Tag            | 面向客户的含义     | 处理方式               |
| -------------- | ----------- | ------------------ |
| `Pending`      | 订单处理中       | 无需通知               |
| `InfoReceived` | 发货信息已向物流商登记 | 通知："您的订单已发货"       |
| `InTransit`    | 包裹运输中       | 通知："您的包裹正在运输中"     |
| `Delivered`    | 包裹已送达       | 通知："您的包裹已送达"       |
| `Exception`    | 配送发生问题      | 通知："您的配送发生问题"并进行调查 |
| `Cancelled`    | 发货已取消       | 内部处理               |
| `Unknown`      | 无法获取状态      | 无需通知 — 稍后重试        |

## 轮询模式

由于目前尚未提供 Webhook，请以合理的间隔轮询 `GET /tracking/{id}` 来检测状态变更。

### 推荐做法

```javascript theme={null}
async function pollTracking(labelId, token) {
  let lastTag = null;

  const interval = setInterval(async () => {
    const response = await fetch(
      `https://api.flexforward.com/tracking/${labelId}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    const tracking = await response.json();

    if (tracking.tag !== lastTag) {
      lastTag = tracking.tag;
      await notifyCustomer(tracking); // Your notification logic
    }

    // Stop polling when shipment reaches a terminal state
    if (['Delivered', 'Cancelled'].includes(tracking.tag)) {
      clearInterval(interval);
    }
  }, 30 * 60 * 1000); // Every 30 minutes
}
```

### 轮询指南

| 发货阶段                       | 建议间隔          |
| -------------------------- | ------------- |
| `Pending` / `InfoReceived` | 每 4-6 小时      |
| `InTransit`                | 每 30-60 分钟    |
| `Delivered` / `Cancelled`  | 停止轮询          |
| `Exception`                | 解决前每 15-30 分钟 |

<Note>
  跟踪数据从物流商近乎实时获取。以低于 15 分钟的间隔轮询不太可能获得新数据，且会计入建议的速率限制（每秒 10 个请求）。
</Note>

## 错误处理

| 状态码 | 含义      | 处理方式                     |
| --- | ------- | ------------------------ |
| 200 | 已获取跟踪数据 | 处理 `tag` 和 `checkpoints` |
| 403 | 访问被拒    | 该标签属于其他账户                |
| 404 | 找不到标签   | 请确认标签 ID 是否正确            |
| 502 | 上游服务错误  | 使用指数退避重试                 |

## 后续步骤

<CardGroup cols={2}>
  <Card title="核心概念" icon="book" href="/zh-Hans/core-concepts#追踪状态模型">
    跟踪状态标签和检查点结构的完整参考。
  </Card>

  <Card title="幂等性与重试" icon="rotate" href="/zh-Hans/idempotency-and-retries">
    处理瞬时故障的安全重试模式。
  </Card>
</CardGroup>