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

​
クイックスタート

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

​
前提条件

  • APIトークン（取得方法は認証を参照）
  • curl またはHTTPクライアント
  • 開発環境のベースURL：https://sandbox.flexforward.com
テストには開発環境をご使用ください。配送業者のサンドボックスサービスに接続されており、実際の配送は作成されません。

​
ステップ1：認証

すべてのリクエストの Authorization ヘッダーにBearerトークンを含めてください： 
Authorization: Bearer YOUR_API_TOKEN
トークンのベストプラクティスとエラーレスポンスについては認証ページをご覧ください。

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

配送情報を含む POST /labels リクエストを送信します。idempotencyKey により、同じリクエストを再試行しても重複ラベルが作成されることはありません。
最低限必要なフィールド: idempotencyKey、courier、service.shipperAccountId、service.productCode、shipment.shipTo（firstName を含む contact と countryCode、city、postalCode、streetLines を含む address）、および weight と少なくとも1つの item（descriptionEn、quantity、unitPrice、unitWeight）を含む parcel が必要です。shipment.shipFrom フィールドは特定の配送業者や配送ルートで必要です — オンボーディング時にFlex Forwardチームに要件をご確認ください。
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": {
      "shipperAccountId": "your-account-id",
      "productCode": "YEXP01"
    },
    "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
            }
          ]
        }
      ]
    }
  }'
リクエストが成功すると、HTTP 201でラベルの詳細が返されます：
201 Created
{
  "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 を含みます。
同じ idempotencyKey でリクエストを再試行すると、APIは重複ラベルを作成せず、HTTP 200で元の結果を返します。詳細は冪等性とリトライをご覧ください。

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

前のレスポンスのラベル id を使用してエアウェイビル文書を取得します： 
curl https://sandbox.flexforward.com/labels/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
200 OK
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://label-documents.example.com/labels/a1b2c3d4.pdf",
  "labelFormat": "pdf"
}
返された url からPDFまたはPNGをダウンロードして配送ラベルを印刷してください。

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

同じラベル id を使用して追跡情報を取得します： 
curl https://sandbox.flexforward.com/tracking/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
200 OK
{
  "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 フィールドは配送の概要ステータスを示します。追跡ステータスの完全な一覧はコアコンセプトをご覧ください。

​
成功の確認

このクイックスタートを完了したら、以下を確認してください：
  • Bearerトークンで正常に認証できる
  • 開発環境でテストラベルを作成できる
  • 印刷可能なラベル文書（PDFまたはPNG）を取得できる
  • テストラベルの正規化された追跡更新を取得できる

​
次のステップ

エラーハンドリング

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

冪等性とリトライ

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

コアコンセプト

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