> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# コアコンセプト

> Flex Forward APIの主要な概念とメンタルモデル

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

# コアコンセプト

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

## リソース

APIは3つの関連リソースを管理しており、すべて**ラベルID**（UUID）でリンクされています：

| リソース  | エンドポイント              | 説明                          |
| ----- | -------------------- | --------------------------- |
| ラベル   | `POST /labels`       | 配送業者に送信された配送ラベルリクエスト        |
| ラベル文書 | `GET /labels/{id}`   | ラベルの印刷可能なエアウェイビル（PDFまたはPNG） |
| 追跡    | `GET /tracking/{id}` | ラベルのリアルタイム配送追跡データ           |

`POST /labels` から返されるラベルIDが、すべての操作で使用される主キーです。別個のトラッキングIDはありません。追跡は常にラベルIDでアクセスします。

## ラベルのライフサイクル

ラベルは以下の状態を経て進行します：

```mermaid theme={null}
stateDiagram-v2
    [*] --> Created : Courier accepts
    [*] --> Failed : Courier rejects
    Created --> DocumentAvailable : Label document ready
    DocumentAvailable --> TrackingActive : Courier scans package
    TrackingActive --> Delivered : Shipment delivered
    TrackingActive --> Exception : Issue during transit
```

<Steps>
  <Step title="作成済み">
    ラベルリクエストが配送業者に受け付けられました。レスポンスには `courierOrderNumber`、`courierTrackingNumber`、およびラベル `id` が含まれます。ラベル文書は取得可能です。
  </Step>

  <Step title="文書が利用可能">
    `GET /labels/{id}` でエアウェイビルのPDFまたはPNGをダウンロードできます。印刷して荷物に添付してください。文書URLは永続的で有効期限はありません。対応フォーマットはPDFとPNGです。
  </Step>

  <Step title="追跡アクティブ">
    配送業者がパッケージをスキャンすると、`GET /tracking/{id}` で追跡データが利用可能になります。追跡データは配送業者からほぼリアルタイムで取得されます。追跡ステータスは `InfoReceived`、`InTransit`、`Delivered` などの段階を経て進行します。正規化されたステータスタグは、追加の配送業者データが利用可能になるにつれて進化する場合があります。
  </Step>
</Steps>

配送業者がリクエストを拒否した場合、ラベルは `status: failed` で保存され、配送業者のエラー詳細が含まれます。詳細は[エラーハンドリング](/ja/error-handling#配送業者の下流エラー502)をご覧ください。

## 追跡ステータスモデル

追跡データは業界標準に基づく統一されたステータスモデルを使用します。各追跡レスポンスにはトップレベルの `tag` と `subtag`、および個々の追跡イベントを表す `checkpoints` の配列が含まれます。

### ステータスタグ

| タグ             | 意味                         |
| -------------- | -------------------------- |
| `Pending`      | ラベルが作成されたが、まだ配送業者に受信されていない |
| `InfoReceived` | 配送業者が配送情報を受信した             |
| `InTransit`    | 荷物が輸送中                     |
| `Delivered`    | 荷物が配達された                   |
| `Exception`    | 輸送中に問題が発生した（例：配達失敗、税関保留）   |
| `Cancelled`    | 配送がキャンセルされた                |
| `Unknown`      | ステータスを判定できなかった             |

`subtag` フィールドはより詳細な粒度を提供します（例：`InTransit_001`、`Exception_002`）。高レベルのステータスロジックには `tag` を、詳細なステータス表示には `subtag` を使用してください。

### チェックポイント

各チェックポイントは1つの追跡イベントを表します：

```json theme={null}
{
  "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` が必要です。[`GET /couriers`](/ja/api-reference/couriers/list-couriers) を呼び出してアカウントで利用可能な有効な配送業者コードを一覧し、返された `code` 値のいずれかをラベル作成時の `courier` として指定してください。

| 配送業者       | スラッグ         | プロダクトコード  | 説明     |
| ---------- | ------------ | --------- | ------ |
| YunExpress | `yunexpress` | `HKMUZXR` | 標準越境EC |

配送業者を選択したら、その配送業者コードを指定して [`GET /products`](/ja/api-reference/products/list-products) を呼び出し、配送ルートで利用可能なプロダクトコードを一覧してください。`serviceCode` フィールドはオプションで、利用可能な場合に特定のサービスレベルを有効にします。

## アドレス参照データ

アドレスフィールドには標準化されたコードが必要です：

* **`countryCode`** — ISO 3166-1 alpha-2国コード（例：`US`、`JP`、`CN`、`GB`、`DE`）
* **`state`** — 州または県コード。州レベルの住所が必要な国で必須（例：米国の `CA`、`NY`、`TX`）

<Note>
  米国の州コードの完全なリストは、[州コードリファレンス](https://apidocs.returnhelper.com/reference/supported-states)を参照してください。
</Note>

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

一般的なインテグレーションの流れ：

```
1. 認証           →  すべてのリクエストにBearerトークンを含める
2. ラベル作成     →  POST /labels  →  ラベルID + トラッキング番号を受信
3. 文書取得       →  GET /labels/{id}  →  PDF/PNGをダウンロード
4. 配送追跡       →  GET /tracking/{id}  →  ステータス更新をポーリング
```

3つのGET操作はすべて、最初の `POST /labels` 呼び出しから返される同じラベル `id` を使用します。文書と追跡に別々の識別子を管理する必要はありません。

<Note>
  追跡データは配送業者からリアルタイムで取得されます。まだ配送業者にスキャンされていない荷物の場合、追跡レスポンスはチェックポイントなしの `Pending` または `InfoReceived` ステータスを返す場合があります。
</Note>