メインコンテンツへスキップ

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

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

​
追跡データを取得する

ラベル作成レスポンスのidを使用します： 
curl https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
レスポンス

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, 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 / InfoReceived4〜6時間ごと
InTransit30〜60分ごと
Delivered / Cancelledポーリングを停止
Exception解決するまで15〜30分ごと
追跡データは配送業者からほぼリアルタイムで取得されます。15分未満の間隔でポーリングしても新しいデータが得られる可能性は低く、推奨レートリミットである1秒あたり10リクエストに対してカウントされます。

​
エラーハンドリング

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

​
次のステップ

コアコンセプト

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

べき等性とリトライ

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