このページは英語から翻訳されています。英語版が正式な情報源です。翻訳内容に不一致がある場合は、英語版を参照してください。

追跡情報をポーリングする

GET /tracking/{id}を使用して、統一フォーマットのリアルタイム出荷追跡データを取得します。このガイドでは、ポーリングフロー、追跡ステータスの解釈方法、および顧客通知を構築するためのパターンについて説明します。

追跡データを取得する

ラベル作成レスポンスのidを使用します：

curl https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

const response = await fetch(
  'https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479',
  { headers: { 'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN' } }
);
const tracking = await response.json();
console.log(tracking.tag); // High-level status: InTransit, Delivered, etc.

import requests

response = requests.get(
    'https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479',
    headers={'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN'}
)
tracking = response.json()
print(tracking['tag'])  # High-level status: InTransit, Delivered, etc.

レスポンス

200 OK

{
  "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}を適切な間隔でポーリングしてステータスの変更を検出します。

推奨アプローチ

async function pollTracking(labelId, apiKey, apiToken) {
  let lastTag = null;

  const interval = setInterval(async () => {
    const response = await fetch(
      `https://api.flexforward.com/tracking/${labelId}`,
      { headers: { 'x-rr-apikey': apiKey, 'x-rr-apitoken': apiToken } }
    );
    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分ごと

追跡データは配送業者からほぼリアルタイムで取得されます。15分未満の間隔でポーリングしても新しいデータが得られる可能性は低く、推奨レートリミットである1秒あたり10リクエストに対してカウントされます。

エラーハンドリング

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

次のステップ

コアコンセプト

追跡ステータスタグとチェックポイントスキーマの完全なリファレンス。

べき等性とリトライ

一時的な障害に対応する安全なリトライパターン。

はじめに

ガイド

ユースケースガイド

プラットフォーム

追跡情報をポーリングする

追跡情報をポーリングする

追跡データを取得する

レスポンス

追跡ステータスを理解する

ポーリングパターン

推奨アプローチ

ポーリングのガイドライン

エラーハンドリング

次のステップ

コアコンセプト

べき等性とリトライ

​追跡情報をポーリングする

​追跡データを取得する

​レスポンス

​追跡ステータスを理解する

​ポーリングパターン

​推奨アプローチ

​ポーリングのガイドライン

​エラーハンドリング

​次のステップ

コアコンセプト

べき等性とリトライ

追跡情報をポーリングする

追跡データを取得する

レスポンス

追跡ステータスを理解する

ポーリングパターン

推奨アプローチ

ポーリングのガイドライン

エラーハンドリング

次のステップ