> ## 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の使い方

# Flex Forward API

Flex Forwardは、配送ラベルの作成、エアウェイビル文書の取得、配送追跡を一つのAPIで提供します。統一されたリクエスト形式、正規化された追跡データ、冪等性を備えた一つのインテグレーションで複数の配送業者に対応します。

## 主なワークフロー

<CardGroup cols={3}>
  <Card title="ラベル作成" icon="tag" href="/ja/api-reference/labels/create-label">
    冪等性のあるリクエストで配送業者を通じて配送ラベルを作成します。
  </Card>

  <Card title="ラベル文書取得" icon="file-pdf" href="/ja/api-reference/labels/get-label">
    作成したラベルのエアウェイビルPDFまたはPNGを取得します。
  </Card>

  <Card title="配送追跡" icon="location-dot" href="/ja/api-reference/tracking/get-tracking">
    すべての配送業者で統一されたフォーマットでリアルタイムの追跡情報を取得します。
  </Card>
</CardGroup>

## 3ステップで始める

<Steps>
  <Step title="APIアクセスを取得">
    Flex Forwardチームに [flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com) でご連絡いただき、API認証情報をリクエストしてください。認証用のBearerトークンが発行されます。
  </Step>

  <Step title="最初のラベルを作成">
    配送情報を含む `POST /labels` リクエストを送信します。APIからラベルIDとトラッキング番号が返されます。
  </Step>

  <Step title="文書の取得と追跡">
    ラベルIDを使用してエアウェイビル文書（`GET /labels/{id}`）を取得し、配送状況を追跡（`GET /tracking/{id}`）します。
  </Step>
</Steps>

<Card title="クイックスタートガイドに従う" icon="rocket" href="/ja/quickstart">
  認証から最初のラベル作成までのステップバイステップのガイド。
</Card>

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

```mermaid theme={null}
graph LR
    A["認証<br/>(Bearerトークン)"] --> B["ラベル作成<br/>POST /labels"]
    B --> C["文書取得<br/>GET /labels/{id}"]
    B --> D["配送追跡<br/>GET /tracking/{id}"]
    D -->|"更新をポーリング"| D
```

## 最初のリクエスト例

```bash theme={null}
curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ord-20250301-abc123",
    "courier": "yunexpress",
    "service": {
      "productCode": "HKMUZXR"
    },
    "shipment": {
      "shipFrom": {
        "contact": { "firstName": "Sender", "lastName": "Name", "phone": "+81-90-1234-5678" },
        "address": { "countryCode": "JP", "city": "Tokyo", "postalCode": "100-0001", "streetLines": ["1-1 Marunouchi"] }
      },
      "shipTo": {
        "contact": { "firstName": "Recipient", "lastName": "Name", "phone": "+1-555-0100" },
        "address": { "countryCode": "US", "city": "Los Angeles", "state": "CA", "postalCode": "90001", "streetLines": ["123 Main St"] }
      },
      "parcels": [{
        "weight": 0.5,
        "items": [{
          "descriptionEn": "T-Shirt",
          "descriptionLocal": "Tシャツ",
          "quantity": 2,
          "unitPrice": { "amount": 25.00, "currency": "USD" },
          "unitWeight": 0.25
        }]
      }]
    }
  }'
```

```json 201 Created theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
```

## 本番環境の対応範囲

Flex Forwardは現在、YunExpressによる本番環境での配送をサポートしており、グローバルな越境EC配送に対応しています。

| 配送業者       | スラッグ         | 対応地域      |
| ---------- | ------------ | --------- |
| YunExpress | `yunexpress` | グローバル越境EC |

追加の配送業者は、配送ルートの要件とアカウントのオンボーディングに基づいて有効化されます。配送業者の利用可能状況については、Flex Forwardチームまでお問い合わせください。

## 環境

| 環境 | ベースURL                            |
| -- | --------------------------------- |
| 本番 | `https://api.flexforward.com`     |
| 開発 | `https://sandbox.flexforward.com` |

すべてのAPIリクエストはHTTPSで行う必要があります。開発環境は配送業者のサンドボックスサービスに接続されており、安全にテストを行えます。

<Card title="環境の詳細" icon="server" href="/ja/environments">
  認証情報の分離、環境の動作、運用上の注意事項。
</Card>

## プラットフォームの信頼性

<CardGroup cols={2}>
  <Card title="認証" icon="key" href="/ja/authentication">
    Bearerトークン認証と認証情報管理のベストプラクティス。
  </Card>

  <Card title="エラーハンドリング" icon="triangle-exclamation" href="/ja/error-handling">
    HTTPステータスコード、エラーレスポンス形式、トラブルシューティングガイド。
  </Card>

  <Card title="冪等性とリトライ" icon="rotate" href="/ja/idempotency-and-retries">
    重複ラベル作成を防止し、リクエストを安全にリトライする方法。
  </Card>

  <Card title="バージョニング" icon="code-branch" href="/ja/versioning">
    APIの変更と後方互換性の管理方法。
  </Card>
</CardGroup>

## OpenAPI 仕様

<Card title="OpenAPI仕様をダウンロード" icon="file-code" href="/flex-forward.yaml">
  コード生成、クライアントSDK、APIツーリング用のOpenAPI 3.1仕様をダウンロードできます。
</Card>

## サポート

オンボーディング、インテグレーションサポート、または配送業者の利用可能状況に関するお問い合わせは、Flex Forwardチームまでご連絡ください：[flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com)

<Card title="サポートとFAQ" icon="circle-question" href="/ja/support">
  テクニカルサポート、オンボーディングガイド、よくある質問。
</Card>