跳转到主要内容

​
创建国际发货

本指南将引导您使用 YunExpress 创建一笔从日本到美国的跨境发货。相同的流程适用于所有支持的物流商和配送路线。

​
开始之前

  • 您已在入门流程中获取 API 令牌和 shipperAccountId（请参阅认证）
  • 您已了解物流商的 slug 和产品代码（请参阅物流商与产品代码）

​
1. 准备发货数据

国际发货需要以下信息：
  • 发件地址 — 您的仓库或履约中心
  • 收件地址 — 客户的配送地址
  • 包裹详细信息 — 重量和商品级别的海关申报（英文描述、数量、单价、单位重量）
海关申报（descriptionEn、unitPrice、unitWeight）是跨境发货的必填字段。遗漏或不准确的海关数据可能导致清关延误。

​
2. 创建标签

curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "shipment-jp-us-001",
    "courier": "yunexpress",
    "service": {
      "shipperAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "productCode": "YEXP01"
    },
    "shipment": {
      "shipFrom": {
        "contact": {
          "firstName": "Warehouse",
          "lastName": "Staff",
          "phone": "+81-90-1234-5678"
        },
        "address": {
          "countryCode": "JP",
          "city": "Tokyo",
          "postalCode": "100-0001",
          "streetLines": ["1-1 Marunouchi"]
        }
      },
      "shipTo": {
        "contact": {
          "firstName": "Jane",
          "lastName": "Smith",
          "phone": "+1-555-0100",
          "email": "[email protected]"
        },
        "address": {
          "countryCode": "US",
          "city": "Los Angeles",
          "state": "CA",
          "postalCode": "90001",
          "streetLines": ["456 Oak Avenue", "Apt 12"]
        }
      },
      "parcels": [
        {
          "weight": 0.8,
          "items": [
            {
              "descriptionEn": "Cotton T-Shirt",
              "descriptionLocal": "コットンTシャツ",
              "quantity": 2,
              "unitPrice": { "amount": 29.99, "currency": "USD" },
              "unitWeight": 0.3,
              "hsCode": "6109.10"
            },
            {
              "descriptionEn": "Phone Case",
              "descriptionLocal": "スマホケース",
              "quantity": 1,
              "unitPrice": { "amount": 12.00, "currency": "USD" },
              "unitWeight": 0.2,
              "hsCode": "3926.90"
            }
          ]
        }
      ]
    }
  }'

​
3. 检查响应

201 Created
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
如果 status 为 created，表示标签已准备就绪。请保存 id，后续将用于获取标签文档和跟踪发货。 如果 status 为 failed，请检查 error 对象以了解物流商的拒绝原因。详情请参阅错误处理。

​
4. 后续步骤

获取标签文档

下载航空运单 PDF 以贴附于包裹上。

跟踪发货

使用标准化的跟踪数据监控发货进度。

​
国际发货提示

  • HS 编码 — 附上协调制度编码（hsCode）可加速清关流程。请在您所在国家的海关机构网站查询编码。
  • 本地语言描述 — descriptionLocal 字段提供目的国语言的商品描述，有助于海关处理。
  • 幂等性 — 请务必使用有意义的 idempotencyKey（例如：您的订单 ID），以确保重试是安全的。请参阅幂等性与重试。