跳转到主要内容

​
快速入门

本指南将引导您完成创建第一个配送标签、获取标签文件以及追踪货件的流程。

​
前提条件

  • API 令牌（获取方式请参阅身份验证）
  • curl 或任何 HTTP 客户端
  • 开发环境基础 URL：https://sandbox.flexforward.com
测试请使用开发环境。该环境连接至物流商的沙盒服务，不会创建实际的配送。

​
步骤 1：身份验证

在每个请求的 Authorization 头部中包含您的 Bearer 令牌： 
Authorization: Bearer YOUR_API_TOKEN
令牌最佳实践与错误响应请参阅身份验证页面。

​
步骤 2：创建标签

发送包含配送信息的 POST /labels 请求。idempotencyKey 确保重试相同的请求不会创建重复标签。
最低限必填字段： 需要 idempotencyKey、courier、service.shipperAccountId、service.productCode、shipment.shipTo（包含 firstName 的 contact 以及包含 countryCode、city、postalCode、streetLines 的 address），以及包含 weight 和至少一个 item（descriptionEn、quantity、unitPrice、unitWeight）的 parcel。shipment.shipFrom 字段在特定物流商和配送路线中为必填 — 请在上线期间向 Flex Forward 团队确认您的需求。
curl -X POST https://sandbox.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "quickstart-test-001",
    "courier": "yunexpress",
    "service": {
      "shipperAccountId": "your-account-id",
      "productCode": "YEXP01"
    },
    "shipment": {
      "shipFrom": {
        "contact": {
          "firstName": "Test",
          "lastName": "Sender",
          "phone": "+81-90-1234-5678"
        },
        "address": {
          "countryCode": "JP",
          "city": "Tokyo",
          "postalCode": "100-0001",
          "streetLines": ["1-1 Marunouchi"]
        }
      },
      "shipTo": {
        "contact": {
          "firstName": "Test",
          "lastName": "Recipient",
          "phone": "+1-555-0100"
        },
        "address": {
          "countryCode": "US",
          "city": "Los Angeles",
          "state": "CA",
          "postalCode": "90001",
          "streetLines": ["123 Main St"]
        }
      },
      "parcels": [
        {
          "weight": 0.5,
          "items": [
            {
              "descriptionEn": "T-Shirt",
              "descriptionLocal": "T恤",
              "quantity": 2,
              "unitPrice": { "amount": 25.00, "currency": "USD" },
              "unitWeight": 0.25
            }
          ]
        }
      ]
    }
  }'
请求成功时，返回 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 "Authorization: Bearer YOUR_API_TOKEN"
200 OK
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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 "Authorization: Bearer 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 字段提供货件的概要状态。完整的追踪状态列表请参阅核心概念。

​
成功验证

完成此快速入门后，请验证您可以：
  • 使用 Bearer 令牌成功验证身份
  • 在开发环境创建测试标签
  • 获取可打印的标签文件（PDF 或 PNG）
  • 获取测试标签的规范化追踪更新

​
下一步

错误处理

了解错误响应及如何排查常见问题。

幂等性与重试

学习如何安全地重试请求而不创建重复标签。

核心概念

了解标签生命周期、追踪模型与物流商规范化。