此页面由英文翻译而成。英文版为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。

创建国际发货

本指南将引导您使用 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. 后续步骤

国际发货提示