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

​
コアコンセプト

このページでは、Flex Forward APIの主要な概念を説明します。リソースの関係性、ラベルのライフサイクル、配送業者間で追跡データがどのように正規化されるかを理解できます。

​
リソース

APIは3つの関連リソースを管理しており、すべてラベルID（UUID）でリンクされています：
リソースエンドポイント説明
ラベルPOST /labels配送業者に送信された配送ラベルリクエスト
ラベル文書GET /labels/{id}ラベルの印刷可能なエアウェイビル（PDFまたはPNG）
追跡GET /tracking/{id}ラベルのリアルタイム配送追跡データ
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 の配列が含まれます。

​
ステータスタグ

タグ意味
Pendingラベルが作成されたが、まだ配送業者に受信されていない
InfoReceived配送業者が配送情報を受信した
InTransit荷物が輸送中
Delivered荷物が配達された
Exception輸送中に問題が発生した（例：配達失敗、税関保留）
Cancelled配送がキャンセルされた
Unknownステータスを判定できなかった
subtag フィールドはより詳細な粒度を提供します（例：InTransit_001、Exception_002）。高レベルのステータスロジックには tag を、詳細なステータス表示には subtag を使用してください。

​
チェックポイント

各チェックポイントは1つの追跡イベントを表します： 
{
  "checkpointTime": "2026-03-15T14:30:00Z",
  "city": "Tokyo",
  "state": "Tokyo",
  "countryRegion": "JP",
  "location": null,
  "message": "Departed from sorting facility",
  "tag": "InTransit",
  "subtag": "InTransit_001",
  "subtagMessage": "In transit",
  "slug": "yunexpress"
}
チェックポイントは最新のイベントが先頭に配置されます（時系列逆順）。最も古いイベントが配列の最後に表示されます。

​
配送業者の正規化

各配送業者には独自のAPIフォーマット、ステータスコード、エラー規約があります。Flex Forwardはこれらの違いを正規化します：
  • 統一リクエスト形式 — 配送業者に関係なく同じJSON構造を送信します。配送業者固有の詳細は内部で処理されます。
  • 統一レスポンス形式 — id、status、courierOrderNumber、courierTrackingNumber、および（失敗時は）error を含む一貫したラベルレスポンスを受信します。
  • 統一追跡 — 異なる配送業者の追跡イベントが同じステータスタグの分類体系とチェックポイント形式にマッピングされます。
これにより、インテグレーションコードで配送業者固有のロジックを扱う必要がありません。新しい配送業者が有効化されても、既存のインテグレーションは変更なしで機能します。

​
配送業者とプロダクトコード

各ラベルリクエストには courier スラッグと productCode が必要です。利用可能な配送業者とプロダクトコードはアカウントのオンボーディング時に設定されます。
配送業者スラッグプロダクトコード説明
YunExpressyunexpressYEXP01標準越境EC
serviceCode フィールドはオプションで、利用可能な場合に特定のサービスレベルを有効にします。お客様の配送ルートで利用可能なプロダクトコードとサービスオプションについては、Flex Forwardチームにお問い合わせください。

​
アドレス参照データ

アドレスフィールドには標準化されたコードが必要です：
  • countryCode — ISO 3166-1 alpha-2国コード（例：US、JP、CN、GB、DE）
  • state — 州または県コード。州レベルの住所が必要な国で必須（例：米国の CA、NY、TX）
サポートされている国コードと米国の州コードの完全なリファレンスは今後のリリースで予定されています。

​
インテグレーションフロー

一般的なインテグレーションの流れ： 
1. 認証           →  すべてのリクエストにBearerトークンを含める
2. ラベル作成     →  POST /labels  →  ラベルID + トラッキング番号を受信
3. 文書取得       →  GET /labels/{id}  →  PDF/PNGをダウンロード
4. 配送追跡       →  GET /tracking/{id}  →  ステータス更新をポーリング
3つのGET操作はすべて、最初の POST /labels 呼び出しから返される同じラベル id を使用します。文書と追跡に別々の識別子を管理する必要はありません。
追跡データは配送業者からリアルタイムで取得されます。まだ配送業者にスキャンされていない荷物の場合、追跡レスポンスはチェックポイントなしの Pending または InfoReceived ステータスを返す場合があります。