此頁面由英文翻譯而成。英文版為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。

建立國際出貨

本指南將引導您使用 YunExpress 建立一筆從日本到美國的跨境出貨。相同的流程適用於所有支援的物流業者和配送路線。

開始之前

您已在入門流程中取得 API 金鑰與 API 令牌（請參閱身份驗證）
您已知道物流業者的 slug 和產品代碼（請參閱物流業者與產品代碼）

1. 準備出貨資料

國際出貨需要以下資訊：

寄件地址 — 您的倉庫或物流中心
收件地址 — 客戶的配送地址
包裹詳細資訊 — 重量和品項層級的海關申報（英文描述、數量、單價、單位重量）

海關申報（descriptionEn、unitPrice、unitWeight）是跨境出貨的必填欄位。遺漏或不準確的海關資料可能導致清關延誤。

品項的 unitPrice.amount 值必須至少為 0.01。免費贈品、樣品與促銷贈品也必須以 0.01 或以上的名目價值申報，不可為 0。品項的 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 編碼 — 附上國際商品統一分類代碼（hsCode）可加速清關流程。請至您所在國家的海關機構網站查詢編碼。
當地語言描述 — descriptionLocal 欄位提供目的地國家語言的品項描述，有助於海關處理。
冪等性 — 請務必使用有意義的 idempotencyKey（例如：您的訂單 ID），以確保重試是安全的。請參閱冪等性與重試。

快速開始

指南

使用場景指南

平台

建立國際出貨

建立國際出貨

開始之前

1. 準備出貨資料

2. 建立標籤

3. 確認回應

4. 後續步驟

取得標籤文件

追蹤出貨

國際出貨提示

​建立國際出貨

​開始之前

​1. 準備出貨資料

​2. 建立標籤

​3. 確認回應

​4. 後續步驟

取得標籤文件

追蹤出貨

​國際出貨提示

建立國際出貨

開始之前

1. 準備出貨資料

2. 建立標籤

3. 確認回應

4. 後續步驟

國際出貨提示