> ## 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分未満の間隔でポーリングしても新しいデータが得られる可能性は低く、推奨レートリミットである1秒あたり10リクエストに対してカウントされます。
</Note>

## エラーハンドリング

| ステータス | 意味           | アクション                        |
| ----- | ------------ | ---------------------------- |
| 200   | 追跡データを取得しました | `tag`と`checkpoints`を処理してください |
| 403   | アクセス拒否       | ラベルが別のアカウントに属しています           |
| 404   | ラベルが見つかりません  | ラベルIDが正しいか確認してください           |
| 502   | 上流サービスエラー    | エクスポネンシャルバックオフでリトライしてください    |

## 次のステップ

<CardGroup cols={2}>
  <Card title="コアコンセプト" icon="book" href="/ja/core-concepts#追跡ステータスモデル">
    追跡ステータスタグとチェックポイントスキーマの完全なリファレンス。
  </Card>

  <Card title="べき等性とリトライ" icon="rotate" href="/ja/idempotency-and-retries">
    一時的な障害に対応する安全なリトライパターン。
  </Card>
</CardGroup>