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

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

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

追跡データを取得する

ラベル作成レスポンスのidを使用します。{id} にはラベルUUIDまたはご自身の customerOrderNumber を指定できます。配送業者の追跡番号（courierTrackingNumber）は受け付けられず、404 が返ります：

curl https://api.flexforwardship.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.flexforwardship.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.flexforwardship.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": "YT2503010001TN",
  "tag": "InTransit",
  "subtag": "InTransit_001",
  "subtagMessage": "In transit",
  "slug": "yunexpress",
  "checkpoints": [
    {
      "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"
    },
    {
      "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-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"
    }
  ]
}

チェックポイントは時系列順（最も古いイベントが先頭）に並びます。最後の要素が最新のイベントです。

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

トップレベルの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.flexforwardship.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	アカウントアクセス拒否	お客様のアカウントはAPIの呼び出しを許可されていません（例：ブロックされたアカウント）
404	ラベルが見つかりません	そのUUIDまたは`customerOrderNumber`を持つラベルはお客様のアカウントに存在しません。他のアカウントが所有するラベルも404として報告されます。
502	上流サービスエラー	エクスポネンシャルバックオフでリトライしてください

次のステップ

コアコンセプト

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

べき等性とリトライ

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

はじめに

ガイド

ユースケースガイド

プラットフォーム

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

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

追跡データを取得する

レスポンス

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

ポーリングパターン

推奨アプローチ

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

エラーハンドリング

次のステップ

コアコンセプト

べき等性とリトライ

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

​追跡データを取得する

​レスポンス

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

​ポーリングパターン

​推奨アプローチ

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

​エラーハンドリング

​次のステップ

コアコンセプト

べき等性とリトライ

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

追跡データを取得する

レスポンス

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

ポーリングパターン

推奨アプローチ

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

エラーハンドリング

次のステップ