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

クイックスタート

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

前提条件

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

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

ステップ1：認証

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

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

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

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

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

最低限必要なフィールド: 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.flexforward.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": "New jersey",
            "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.flexforward.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: 'New jersey',
                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.flexforward.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': 'New jersey',
                    '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",
  "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 "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またはPNGをダウンロードして配送ラベルを印刷してください。

ステップ4：配送を追跡

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

curl https://sandbox.flexforward.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": "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 フィールドは配送の概要ステータスを示します。追跡ステータスの完全な一覧はコアコンセプトをご覧ください。

成功の確認

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

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

次のステップ

エラーハンドリング

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

冪等性とリトライ

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

コアコンセプト

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

はじめに

ガイド

ユースケースガイド

プラットフォーム

クイックスタート

クイックスタート

前提条件

ステップ1：認証

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

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

ステップ4：配送を追跡

成功の確認

次のステップ

エラーハンドリング

冪等性とリトライ

コアコンセプト

​クイックスタート

​前提条件

​ステップ1：認証

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

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

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

​成功の確認

​次のステップ

エラーハンドリング

冪等性とリトライ

コアコンセプト

クイックスタート

前提条件

ステップ1：認証

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

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

ステップ4：配送を追跡

成功の確認

次のステップ