このページは英語から翻訳されています。英語版が正式な情報源です。翻訳内容に不一致がある場合は、英語版を参照してください。
コアコンセプト
このページでは、Flex Forward APIの主要な概念を説明します。リソースの関係性、ラベルのライフサイクル、配送業者間で追跡データがどのように正規化されるかを理解できます。リソース
APIは3つの関連リソースを管理しており、すべてラベルID（UUID）でリンクされています：POST /labels から返されるラベルIDが、すべての操作で使用される主キーです。別個のトラッキングIDはありません。追跡は常にラベルIDでアクセスします。
ラベルのライフサイクル
ラベルは以下の状態を経て進行します：1
作成済み
ラベルリクエストが配送業者に受け付けられました。レスポンスには
courierOrderNumber、courierTrackingNumber、およびラベル id が含まれます。ラベル文書は取得可能です。2
文書が利用可能
GET /labels/{id} でエアウェイビルのPDFまたはPNGをダウンロードできます。印刷して荷物に添付してください。文書URLは永続的で有効期限はありません。対応フォーマットはPDFとPNGです。3
追跡アクティブ
配送業者がパッケージをスキャンすると、
GET /tracking/{id} で追跡データが利用可能になります。追跡データは配送業者からほぼリアルタイムで取得されます。追跡ステータスは InfoReceived、InTransit、Delivered などの段階を経て進行します。正規化されたステータスタグは、追加の配送業者データが利用可能になるにつれて進化する場合があります。status: failed で保存され、配送業者のエラー詳細が含まれます。詳細はエラーハンドリングをご覧ください。
追跡ステータスモデル
追跡データは業界標準に基づく統一されたステータスモデルを使用します。各追跡レスポンスにはトップレベルのtag と subtag、および個々の追跡イベントを表す checkpoints の配列が含まれます。
ステータスタグ
subtag フィールドはより詳細な粒度を提供します（例：InTransit_001、Exception_002）。高レベルのステータスロジックには tag を、詳細なステータス表示には subtag を使用してください。
チェックポイント
各チェックポイントは1つの追跡イベントを表します：配送業者の正規化
各配送業者には独自のAPIフォーマット、ステータスコード、エラー規約があります。Flex Forwardはこれらの違いを正規化します：- 統一リクエスト形式 — 配送業者に関係なく同じJSON構造を送信します。配送業者固有の詳細は内部で処理されます。
- 統一レスポンス形式 —
id、status、courierOrderNumber、courierTrackingNumber、および（失敗時は）errorを含む一貫したラベルレスポンスを受信します。 - 統一追跡 — 異なる配送業者の追跡イベントが同じステータスタグの分類体系とチェックポイント形式にマッピングされます。
配送業者とプロダクトコード
各ラベルリクエストにはcourier コードと productCode が必要です。GET /couriers を呼び出してアカウントで利用可能な有効な配送業者コードを一覧し、返された code 値のいずれかをラベル作成時の courier として指定してください。
配送業者を選択したら、その配送業者コードを指定して
GET /products を呼び出し、配送ルートで利用可能なプロダクトコードを一覧してください。serviceCode フィールドはオプションで、利用可能な場合に特定のサービスレベルを有効にします。
アドレス参照データ
アドレスフィールドには標準化されたコードが必要です：countryCode— ISO 3166-1 alpha-2国コード（例：US、JP、CN、GB、DE）state— 州または県コード。州レベルの住所が必要な国で必須（例：米国のCA、NY、TX）
米国の州コードの完全なリストは、州コードリファレンスを参照してください。
インテグレーションフロー
一般的なインテグレーションの流れ：POST /labels 呼び出しから返される同じラベル id を使用します。文書と追跡に別々の識別子を管理する必要はありません。
追跡データは配送業者からリアルタイムで取得されます。まだ配送業者にスキャンされていない荷物の場合、追跡レスポンスはチェックポイントなしの
Pending または InfoReceived ステータスを返す場合があります。