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

国際出荷を作成する

このガイドでは、YunExpressを使用して日本からアメリカへの越境出荷を作成する手順を説明します。同じフローは、サポートされているすべての配送業者および配送ルートに適用できます。

始める前に

オンボーディングで取得したAPIキーとAPIトークンがあること（認証を参照）
配送業者のslugとプロダクトコードを把握していること（配送業者とプロダクトコードを参照）

1. 出荷データを準備する

国際出荷には以下が必要です：

発送元住所 — 倉庫またはフルフィルメントセンター
届け先住所 — お客様の配送先住所
荷物の詳細 — 重量およびアイテムレベルの税関申告（英語の説明、数量、単価、単位重量）

税関申告（descriptionEn、unitPrice、unitWeight）は越境出荷に必須です。税関データが不足していたり不正確な場合、通関手続きに遅延が生じる可能性があります。

アイテムの unitPrice.amount の値は少なくとも 0.01 である必要があります。無償のギフト、サンプル、販促用同梱物であっても、0 ではなく 0.01 以上の名目価格で申告する必要があります。アイテムの unitPrice.currency の値は USD である必要があります。任意の unitPrice.currency フィールドは USD のみを受け付け、省略した場合も USD を意味します。配送業者に独自の IOSS コードを提供する必要がある場合は、customs.taxIds.ioss に送信してください。API は、指定された空白でない値の前後の空白を除去したうえで使用します。この項目が省略されているか空欄で、仕向地が EU の課税国である場合は、FlexForward のデフォルト IOSS コードが自動的に適用されます。IOSS registrations に登録したコードは、リクエストで送信しない限り自動適用されません。FlexForward のデフォルトコードを適用する場合は、配送運賃とあわせて、仕向地 VAT を立て替えるための VAT 前払いとサービス料が計上されるため課金対象です。ここで独自のコードを指定した場合は課金されません。

2. ラベルを作成する

新しいラベルごとに一意の idempotencyKey を使用してください。この例ではプレースホルダー unique-key-per-request を使用し、order.customerOrderNumber には N-2026-05-27-TEST-03 を使用しています。実行ごとに両方をご自身の一意の値に置き換えてください。注文番号は1〜40文字のASCII英字、数字、-、_ のみ使用できます。詳細は顧客注文番号をご覧ください。リトライ時はキーと変更していない本文を再利用してください。同じキーで本文を変更すると 409 IDEMPOTENCY_CONFLICT が返ります。レガシー記録の例外については冪等性とリトライをご覧ください。

curl -X POST https://api.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://api.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();

import requests

response = requests.post(
    'https://api.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()

3. レスポンスを確認する

201 Created

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": null,
  "error": null
}

statusがcreatedであれば、ラベルの準備は完了です。idを保存してください。ラベルドキュメントの取得や出荷の追跡に使用します。 statusがfailedの場合は、errorオブジェクトで配送業者の却下理由を確認してください。詳しくはエラーハンドリングを参照してください。

4. 次のステップ

ラベルドキュメントを取得する

荷物に貼付するPDFまたはPNGのラベル文書をダウンロードします。

出荷を追跡する

正規化された追跡データで出荷状況を監視します。

国際出荷のヒント

HSコード — HSコード（hsCode）を含めることで、通関手続きが迅速になります。各国の税関当局のサイトでコードを検索できます。
現地語の説明 — descriptionLocalフィールドは、仕向国の言語でアイテムの説明を提供し、通関処理に役立ちます。
べき等性 — 常に意味のあるidempotencyKey（例：注文ID）を使用して、リトライを安全に行えるようにしてください。べき等性とリトライを参照してください。

はじめに

ガイド

ユースケースガイド

プラットフォーム

国際出荷を作成する

国際出荷を作成する

始める前に

1. 出荷データを準備する

2. ラベルを作成する

3. レスポンスを確認する

4. 次のステップ

ラベルドキュメントを取得する

出荷を追跡する

国際出荷のヒント

​国際出荷を作成する

​始める前に

​1. 出荷データを準備する

​2. ラベルを作成する

​3. レスポンスを確認する

​4. 次のステップ

ラベルドキュメントを取得する

出荷を追跡する

​国際出荷のヒント

国際出荷を作成する

始める前に

1. 出荷データを準備する

2. ラベルを作成する

3. レスポンスを確認する

4. 次のステップ

国際出荷のヒント