このページは英語から翻訳されています。英語版が正式な情報源です。翻訳内容に不一致がある場合は、英語版を参照してください。
コアコンセプト
このページでは、Flex Forward APIの主要な概念を説明します。リソースの関係性、ラベルのライフサイクル、配送業者間で追跡データがどのように正規化されるかを理解できます。リソース
APIは4つの関連リソースを管理しており、すべてラベルID（UUID）でリンクされています：POST /labels から返されるラベルIDが、すべての操作で使用される主キーです。GET /labels/{id} と GET /tracking/{id} はいずれも、パスパラメータとしてラベルのUUIDまたは customerOrderNumber のいずれかを受け付けます。別個のトラッキングIDはありません。GET /orders/{orderId} はラベルのUUIDのみを受け付けます。注文とラベルは同じ id を共有します。
配送業者側の識別子（
courierOrderNumber、courierTrackingNumber）は {id} として受け付けられません。配送業者の追跡番号を渡すと 404 Label not found が返ります。ラベルUUIDを保存するか、ご自身の customerOrderNumber を使用してください。顧客注文番号
order.customerOrderNumber はラベル作成時には任意です。指定する場合はアカウント内で一意で、ASCII英字（A–Z、a–z）、数字、-、_ のみを使用した1〜40文字とする必要があります。値は大文字と小文字を区別します。空白、カンマ、その他の文字は使用できません。
省略すると、APIが注文番号を生成します。返された customerOrderNumber またはラベル id を保存してください。生成された注文番号がラベルのUUIDと同一であるとは限りません。どちらも文書と追跡情報の取得に使用できます。
FlexForwardは、顧客参照として {clientCode}-{customerOrderNumber} を配送業者に送信します。対応している場合、配送業者はその参照をラベルに印字します。参照検索には、APIから返されるプレフィックスなしの customerOrderNumber を使用してください。
ラベルのライフサイクル
ラベルは以下の状態を経て進行します：1
作成済み
ラベルリクエストが配送業者に受け付けられました。レスポンスにはラベル
id と courierOrderNumber が含まれます。courierTrackingNumber はこの時点では通常 null で、ラストマイル配送業者が後から割り当てます。ラベル文書は取得可能です。2
文書が利用可能
GET /labels/{id} で文書をダウンロードできます。作成時の label.format は PDF または PNG を指定でき、省略時はPDFです。レスポンスの labelFormat は pdf または png になります。文書URLは短命なため、必要なときに再取得してください。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 フィールドはオプションで、利用可能な場合に特定のサービスレベルを有効にします。
カタログはグローバルです。コードが一覧に表示されていても、必ずしもお客様のアカウントがその配送業者やルートに対して有効化されていることを意味しません。お客様のアカウントに該当配送業者のシッピングアカウントが設定されていない場合、POST /labels は404（Shipping account not found）を返します。
アドレス参照データ
アドレスフィールドには標準化されたコードが必要です：countryCode— ISO 3166-1 alpha-2国コード（例：US、JP、CN、GB、DE）state— 州または県コード。州レベルの住所が必要な国で必須（例：米国のCA、NY、TX）
米国の州コードの完全なリストは、州コードリファレンスを参照してください。
インテグレーションフロー
一般的なインテグレーションの流れ：POST /labels 呼び出しから返される同じラベル id を使用します。文書、追跡、注文に別々の識別子を管理する必要はありません。
追跡データは配送業者からリアルタイムで取得されます。まだ配送業者にスキャンされていない荷物の場合、追跡レスポンスはチェックポイントなしの
Pending または InfoReceived ステータスを返す場合があります。