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

クイックスタート

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

前提条件

APIキーとAPIトークン（取得方法は認証を参照）
curl またはHTTPクライアント
開発環境のベースURL：https://sandbox.flexforwardship.com

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

ステップ1：認証

すべてのリクエストに次の両方のヘッダーを含めてください：

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN

認証情報のベストプラクティスとエラーレスポンスについては認証ページをご覧ください。

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

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

実行ごとに idempotencyKey（unique-key-per-request）と order.customerOrderNumber（N-2026-05-27-TEST-03）を一意の値に置き換えてください。注文番号には1〜40文字のASCII英字、数字、-、_ を使用できます。サンプルをそのまま再送すると、最初の実行で保存された結果（HTTP 200）が返されます。同じキーのまま本文を変更すると 409 IDEMPOTENCY_CONFLICT が返ります。レガシー記録の例外については冪等性とリトライをご覧ください。

最低限必要なフィールド: 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チームに要件をご確認ください。

GET /couriers で返される courier コードを使用してください。以下の例では yunexpress を使用していますが、有効な値はアカウントで有効化されている配送業者によって異なります。

curl -X POST https://sandbox.flexforwardship.com/labels \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "idempotencyKey": "unique-key-per-request",
      "courier": "yunexpress",
      "service": {
        "productCode": "HKMUZXR"
      },
      "label": {
        "format": "PDF"
      },
      "units": {
        "weight": "KG",
        "dimension": "CM"
      },
      "order": {
        "customerOrderNumber": "N-2026-05-27-TEST-03",
        "orderNumbers": {
          "platformOrderNumber": "platform-order-number",
          "referenceNumbers": [
            "ref-number-1",
            "ref-number-2"
          ]
        }
      },
      "shipment": {
        "shipTo": {
          "contact": {
            "firstName": "Alex",
            "lastName": "Smith",
            "phone": "8554377467",
            "email": "[email protected]"
          },
          "address": {
            "streetLines": [
              "18 Distribution Blvd"
            ],
            "city": "Edison",
            "state": "NJ",
            "postalCode": "08817",
            "countryCode": "US"
          }
        },
        "shipFrom": {
          "contact": {
            "firstName": "John",
            "lastName": "Doe",
            "phone": "886900676877",
            "email": "[email protected]"
          },
          "address": {
            "streetLines": [
              "Habucho"
            ],
            "city": "Kishiwada-Shi",
            "state": "Osaka",
            "postalCode": "596-0825",
            "countryCode": "JP"
          }
        },
        "parcels": [
          {
            "weight": 0.5,
            "dimension": {
              "length": 30,
              "width": 20,
              "height": 10
            },
            "items": [
              {
                "descriptionEn": "Muji Ink pen",
                "descriptionLocal": "文具",
                "quantity": 1,
                "unitPrice": {
                  "amount": 29.99,
                  "currency": "USD"
                },
                "unitWeight": 0.5
              }
            ]
          }
        ]
      },
      "serviceOptions": [
        {
          "code": "V1",
          "value": "云途预缴"
        }
      ],
      "courierOptions": {
        "yunexpress": {
          "sourceCode": "YT",
          "sensitiveType": "D"
        }
      }
  }'

const response = await fetch('https://sandbox.flexforwardship.com/labels', {
  method: 'POST',
  headers: {
    'x-rr-apikey': 'YOUR_API_KEY',
    'x-rr-apitoken': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(
    {
      idempotencyKey: 'unique-key-per-request',
      courier: 'yunexpress',
      service: {
        productCode: 'HKMUZXR'
      },
      label: {
        format: 'PDF'
      },
      units: {
        weight: 'KG',
        dimension: 'CM'
      },
      order: {
        customerOrderNumber: 'N-2026-05-27-TEST-03',
        orderNumbers: {
          platformOrderNumber: 'platform-order-number',
          referenceNumbers: [
            'ref-number-1',
            'ref-number-2'
          ]
        }
      },
      shipment: {
        shipTo: {
          contact: {
            firstName: 'Alex',
            lastName: 'Smith',
            phone: '8554377467',
            email: '[email protected]'
          },
          address: {
            streetLines: [
              '18 Distribution Blvd'
            ],
            city: 'Edison',
            state: 'NJ',
            postalCode: '08817',
            countryCode: 'US'
          }
        },
        shipFrom: {
          contact: {
            firstName: 'John',
            lastName: 'Doe',
            phone: '886900676877',
            email: '[email protected]'
          },
          address: {
            streetLines: [
              'Habucho'
            ],
            city: 'Kishiwada-Shi',
            state: 'Osaka',
            postalCode: '596-0825',
            countryCode: 'JP'
          }
        },
        parcels: [
          {
            weight: 0.5,
            dimension: {
              length: 30,
              width: 20,
              height: 10
            },
            items: [
              {
                descriptionEn: 'Muji Ink pen',
                descriptionLocal: '文具',
                quantity: 1,
                unitPrice: {
                  amount: 29.99,
                  currency: 'USD'
                },
                unitWeight: 0.5
              }
            ]
          }
        ]
      },
      serviceOptions: [
        {
          code: 'V1',
          value: '云途预缴'
        }
      ],
      courierOptions: {
        yunexpress: {
          sourceCode: 'YT',
          sensitiveType: 'D'
        }
      }
    }
  )
});
const label = await response.json();
console.log(label.id); // Use this ID for document retrieval and tracking

import requests

response = requests.post(
    'https://sandbox.flexforwardship.com/labels',
    headers={
        'x-rr-apikey': 'YOUR_API_KEY',
        'x-rr-apitoken': 'YOUR_API_TOKEN',
    },
    json={
        'idempotencyKey': 'unique-key-per-request',
        'courier': 'yunexpress',
        'service': {
            'productCode': 'HKMUZXR'
        },
        'label': {
            'format': 'PDF'
        },
        'units': {
            'weight': 'KG',
            'dimension': 'CM'
        },
        'order': {
            'customerOrderNumber': 'N-2026-05-27-TEST-03',
            'orderNumbers': {
                'platformOrderNumber': 'platform-order-number',
                'referenceNumbers': [
                    'ref-number-1',
                    'ref-number-2'
                ]
            }
        },
        'shipment': {
            'shipTo': {
                'contact': {
                    'firstName': 'Alex',
                    'lastName': 'Smith',
                    'phone': '8554377467',
                    'email': '[email protected]'
                },
                'address': {
                    'streetLines': [
                        '18 Distribution Blvd'
                    ],
                    'city': 'Edison',
                    'state': 'NJ',
                    'postalCode': '08817',
                    'countryCode': 'US'
                }
            },
            'shipFrom': {
                'contact': {
                    'firstName': 'John',
                    'lastName': 'Doe',
                    'phone': '886900676877',
                    'email': '[email protected]'
                },
                'address': {
                    'streetLines': [
                        'Habucho'
                    ],
                    'city': 'Kishiwada-Shi',
                    'state': 'Osaka',
                    'postalCode': '596-0825',
                    'countryCode': 'JP'
                }
            },
            'parcels': [
                {
                    'weight': 0.5,
                    'dimension': {
                        'length': 30,
                        'width': 20,
                        'height': 10
                    },
                    'items': [
                        {
                            'descriptionEn': 'Muji Ink pen',
                            'descriptionLocal': '文具',
                            'quantity': 1,
                            'unitPrice': {
                                'amount': 29.99,
                                'currency': 'USD'
                            },
                            'unitWeight': 0.5
                        }
                    ]
                }
            ]
        },
        'serviceOptions': [
            {
                'code': 'V1',
                'value': '云途预缴'
            }
        ],
        'courierOptions': {
            'yunexpress': {
                'sourceCode': 'YT',
                'sensitiveType': 'D'
            }
        }
    }
)
label = response.json()
print(label['id'])  # Use this ID for document retrieval and tracking

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

201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": null,
  "error": null
}

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

フィールド	説明
`id`	ラベルのUUID。文書の取得と追跡に使用します。
`customerOrderNumber`	ご自身で指定した注文番号、または省略時はシステムが生成した値。この値を保存してください。文書の取得と追跡にも使用できます。顧客注文番号を参照してください。
`status`	成功時は `created`、配送業者がリクエストを拒否した場合は `failed`。
`courierOrderNumber`	配送業者が割り当てた注文番号。
`courierTrackingNumber`	ラストマイル配送業者の追跡番号。作成時は通常 `null` で、配送業者が番号を割り当てた時点で設定されます。追跡をポーリングして取得してください。
`error`	成功時は `null`。失敗時は `code` と `message` を含みます。

同じ idempotencyKey でリクエストを再試行すると、APIは重複ラベルを作成せず、HTTP 200で保存結果を返します。最初の試行が配送業者に拒否されていた場合、その保存結果は status: failed になることがあるため、HTTPステータスコードだけに頼らず必ず status フィールドを確認してください。本文を変えると 409 IDEMPOTENCY_CONFLICT が返ります。詳細は冪等性とリトライとエラーハンドリングをご覧ください。

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

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

curl https://sandbox.flexforwardship.com/labels/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "url": "https://label-documents.example.com/labels/a1b2c3d4.pdf",
  "labelFormat": "pdf"
}

返された url からPDFをダウンロードして配送ラベルを印刷してください。このサンプルでは label.format: "PDF" を指定しています。作成時に "PNG" を指定することもでき、その場合、文書のレスポンスは labelFormat: "png" を返します。

ステップ4：配送を追跡

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

curl https://sandbox.flexforwardship.com/tracking/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "YT2503010001TN",
  "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 フィールドは配送の概要ステータスを示します。追跡ステータスの完全な一覧はコアコンセプトをご覧ください。

成功の確認

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

APIキーとAPIトークンで正常に認証できる
開発環境でテストラベルを作成できる
印刷可能なラベル文書（PDF）を取得できる
テストラベルの正規化された追跡更新を取得できる
レスポンスを寛容に解析できる — 不明なフィールドやenum値を拒否せずに無視する（バージョニングを参照）

次のステップ

エラーハンドリング

エラーレスポンスの理解と一般的な問題のトラブルシューティング。

冪等性とリトライ

重複ラベルを作成せずにリクエストを安全にリトライする方法。

コアコンセプト

ラベルのライフサイクル、追跡モデル、配送業者の正規化について。

はじめに

ガイド

ユースケースガイド

プラットフォーム

クイックスタート

クイックスタート

前提条件

ステップ1：認証

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

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

ステップ4：配送を追跡

成功の確認

次のステップ

エラーハンドリング

冪等性とリトライ

コアコンセプト

​クイックスタート

​前提条件

​ステップ1：認証

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

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

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

​成功の確認

​次のステップ

エラーハンドリング

冪等性とリトライ

コアコンセプト

クイックスタート

前提条件

ステップ1：認証

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

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

ステップ4：配送を追跡

成功の確認

次のステップ