> ## 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.

# クイックスタート

> 数分で最初の配送ラベルを作成する

# クイックスタート

このガイドでは、最初の配送ラベルの作成、ラベル文書の取得、配送の追跡までを順を追って説明します。

## 前提条件

* APIトークン（取得方法は[認証](/ja/authentication)を参照）
* `curl` またはHTTPクライアント
* 開発環境のベースURL：`https://sandbox.flexforward.com`

<Note>
  テストには開発環境をご使用ください。配送業者のサンドボックスサービスに接続されており、実際の配送は作成されません。
</Note>

## ステップ1：認証

すべてのリクエストの `Authorization` ヘッダーにBearerトークンを含めてください：

```
Authorization: Bearer YOUR_API_TOKEN
```

トークンのベストプラクティスとエラーレスポンスについては[認証](/ja/authentication)ページをご覧ください。

## ステップ2：ラベルを作成

配送情報を含む `POST /labels` リクエストを送信します。`idempotencyKey` により、同じリクエストを再試行しても重複ラベルが作成されることはありません。

<Note>
  **最低限必要なフィールド:** `idempotencyKey`、`courier`、`service.productCode`、`shipment.shipTo`（`firstName` を含む contact と `countryCode`、`city`、`postalCode`、`streetLines` を含む address）、および `weight` と少なくとも1つの item（`descriptionEn`、`quantity`、`unitPrice`、`unitWeight`）を含む parcel が必要です。`shipment.shipFrom` フィールドは特定の配送業者や配送ルートで必要です — オンボーディング時にFlex Forwardチームに要件をご確認ください。
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://sandbox.flexforward.com/labels \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "idempotencyKey": "quickstart-test-001",
      "courier": "yunexpress",
      "service": {
        "productCode": "HKMUZXR"
      },
      "shipment": {
        "shipFrom": {
          "contact": {
            "firstName": "Test",
            "lastName": "Sender",
            "phone": "+81-90-1234-5678"
          },
          "address": {
            "countryCode": "JP",
            "city": "Tokyo",
            "postalCode": "100-0001",
            "streetLines": ["1-1 Marunouchi"]
          }
        },
        "shipTo": {
          "contact": {
            "firstName": "Test",
            "lastName": "Recipient",
            "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
              }
            ]
          }
        ]
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://sandbox.flexforward.com/labels', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      idempotencyKey: 'quickstart-test-001',
      courier: 'yunexpress',
      service: {
        productCode: 'HKMUZXR'
      },
      shipment: {
        shipFrom: {
          contact: { firstName: 'Test', lastName: 'Sender', phone: '+81-90-1234-5678' },
          address: { countryCode: 'JP', city: 'Tokyo', postalCode: '100-0001', streetLines: ['1-1 Marunouchi'] }
        },
        shipTo: {
          contact: { firstName: 'Test', lastName: 'Recipient', 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
          }]
        }]
      }
    })
  });
  const label = await response.json();
  console.log(label.id); // Use this ID for document retrieval and tracking
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://sandbox.flexforward.com/labels',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
      json={
          'idempotencyKey': 'quickstart-test-001',
          'courier': 'yunexpress',
          'service': {
              'productCode': 'HKMUZXR'
          },
          'shipment': {
              'shipFrom': {
                  'contact': {'firstName': 'Test', 'lastName': 'Sender', 'phone': '+81-90-1234-5678'},
                  'address': {'countryCode': 'JP', 'city': 'Tokyo', 'postalCode': '100-0001', 'streetLines': ['1-1 Marunouchi']}
              },
              'shipTo': {
                  'contact': {'firstName': 'Test', 'lastName': 'Recipient', '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
                  }]
              }]
          }
      }
  )
  label = response.json()
  print(label['id'])  # Use this ID for document retrieval and tracking
  ```
</CodeGroup>

リクエストが成功すると、HTTP 201でラベルの詳細が返されます：

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

レスポンスの主要フィールド：

| フィールド                   | 説明                                          |
| ----------------------- | ------------------------------------------- |
| `id`                    | ラベルのUUID。文書の取得と追跡に使用します。                    |
| `status`                | 成功時は `created`、配送業者がリクエストを拒否した場合は `failed`。 |
| `courierOrderNumber`    | 配送業者が割り当てた注文番号。                             |
| `courierTrackingNumber` | 配送業者が割り当てたトラッキング番号。                         |
| `error`                 | 成功時は `null`。失敗時は `code` と `message` を含みます。  |

<Warning>
  同じ `idempotencyKey` でリクエストを再試行すると、APIは重複ラベルを作成せず、HTTP 200で元の結果を返します。詳細は[冪等性とリトライ](/ja/idempotency-and-retries)をご覧ください。
</Warning>

## ステップ3：ラベル文書を取得

前のレスポンスのラベル `id` を使用してエアウェイビル文書を取得します：

```bash theme={null}
curl https://sandbox.flexforward.com/labels/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```json 200 OK theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "quickstart-test-001",
  "url": "https://label-documents.example.com/labels/a1b2c3d4.pdf",
  "labelFormat": "pdf"
}
```

返された `url` からPDFまたはPNGをダウンロードして配送ラベルを印刷してください。

## ステップ4：配送を追跡

同じラベル `id` を使用して追跡情報を取得します：

```bash theme={null}
curl https://sandbox.flexforward.com/tracking/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```json 200 OK theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "YT2503010001CN",
  "tag": "InfoReceived",
  "subtag": "InfoReceived_001",
  "subtagMessage": "Shipment information received",
  "slug": "yunexpress",
  "checkpoints": [
    {
      "checkpointTime": "2026-03-15T10:30:00Z",
      "city": "Tokyo",
      "state": "Tokyo",
      "countryRegion": "JP",
      "location": null,
      "message": "Shipment information received",
      "tag": "InfoReceived",
      "subtag": "InfoReceived_001",
      "subtagMessage": "Shipment information received",
      "slug": "yunexpress"
    }
  ]
}
```

`tag` フィールドは配送の概要ステータスを示します。追跡ステータスの完全な一覧は[コアコンセプト](/ja/core-concepts#追跡ステータスモデル)をご覧ください。

## 成功の確認

このクイックスタートを完了したら、以下を確認してください：

* [ ] Bearerトークンで正常に認証できる
* [ ] 開発環境でテストラベルを作成できる
* [ ] 印刷可能なラベル文書（PDFまたはPNG）を取得できる
* [ ] テストラベルの正規化された追跡更新を取得できる

## 次のステップ

<CardGroup cols={3}>
  <Card title="エラーハンドリング" icon="triangle-exclamation" href="/ja/error-handling">
    エラーレスポンスの理解と一般的な問題のトラブルシューティング。
  </Card>

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

  <Card title="コアコンセプト" icon="book" href="/ja/core-concepts">
    ラベルのライフサイクル、追跡モデル、配送業者の正規化について。
  </Card>
</CardGroup>