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

快速入门

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

前提条件

API 密钥与 API 令牌（获取方式请参阅身份验证）
curl 或任何 HTTP 客户端
开发环境基础 URL：https://sandbox.flexforwardship.com

测试请使用开发环境。该环境连接至物流商的沙盒服务，不会创建实际的配送。

步骤 1：身份验证

在每个请求中同时包含以下两个头部：

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN

认证信息最佳实践与错误响应请参阅身份验证页面。

步骤 2：创建标签

发送包含配送信息的 POST /labels 请求。idempotencyKey 确保重试相同的请求不会创建重复标签。

每次执行前，请将 idempotencyKey（unique-key-per-request）与 order.customerOrderNumber（N-2026-05-27-TEST-03）替换为唯一的值。订单号可使用 1–40 个 ASCII 字母、数字、-、_。若原样重发示例，会返回第一次执行时保存的结果（HTTP 200）；在重复使用密钥的同时更改请求体，则会返回 409 IDEMPOTENCY_CONFLICT。旧记录的例外情况请参阅幂等性与重试。

最低限必填字段： 需要 idempotencyKey、courier、service.productCode、shipment.shipTo（包含 firstName 的 contact 以及包含 countryCode、city、postalCode、streetLines 的 address），以及包含 weight 和至少一个 item（descriptionEn、quantity、unitPrice、unitWeight）的 parcel。shipment.shipFrom 字段在特定物流商和配送路线中为必填 — 请在上线期间向 Flex Forward 团队确认您的需求。

请使用 GET /couriers 返回的 courier 代码。以下示例使用 yunexpress，但您的有效值取决于账户已启用的物流商。

curl -X POST https://sandbox.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://sandbox.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();
console.log(label.id); // Use this ID for document retrieval and tracking

import requests

response = requests.post(
    'https://sandbox.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()
print(label['id'])  # Use this ID for document retrieval and tracking

请求成功时，返回 HTTP 201 和标签详情：

201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": null,
  "error": null
}

响应中的主要字段：

字段	说明
`id`	标签的 UUID。用于获取文件和追踪。
`customerOrderNumber`	您提供的订单号，若省略则为系统生成的值。请保存此值；它也可用于获取文件和追踪。请参阅客户订单号。
`status`	成功时为 `created`，物流商拒绝请求时为 `failed`。
`courierOrderNumber`	物流商分配的订单号码。
`courierTrackingNumber`	末端配送商的追踪号码。创建时通常为 `null`，待配送商分配后才会填入。请轮询追踪以获取。
`error`	成功时为 `null`。失败时包含 `code` 和 `message`。

如果您使用相同的 idempotencyKey 重试相同的请求，API 会返回 HTTP 200 和原始结果，而不会创建重复标签。若第一次尝试被物流商拒绝，该保存结果可能为 status: failed，因此请务必检查 status 字段，而不要只依赖 HTTP 状态码。详情请参阅幂等性与重试与错误处理。

步骤 3：获取标签文件

使用前一个响应中的标签 id 来获取运单文件：

curl https://sandbox.flexforwardship.com/labels/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "url": "https://label-documents.example.com/labels/a1b2c3d4.pdf",
  "labelFormat": "pdf"
}

从返回的 url 下载 PDF 来打印配送标签。本示例请求的是 label.format: "PDF"。创建时您也可以请求 "PNG"；文件响应中会相应报告 labelFormat: "png"。

步骤 4：追踪货件

使用相同的标签 id 来获取追踪信息：

curl https://sandbox.flexforwardship.com/tracking/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "YT2503010001TN",
  "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 字段提供货件的概要状态。完整的追踪状态列表请参阅核心概念。

成功验证

完成此快速入门后，请验证您可以：

使用 API 密钥与 API 令牌成功验证身份
在开发环境创建测试标签
获取可打印的标签文件（PDF）
获取测试标签的规范化追踪更新
宽容地解析响应 — 忽略未知字段与枚举值，而非拒绝（详见版本管理）

下一步

错误处理

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

幂等性与重试

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

核心概念

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

快速开始

指南

使用场景指南

平台

快速入门

快速入门

前提条件

步骤 1：身份验证

步骤 2：创建标签

步骤 3：获取标签文件

步骤 4：追踪货件

成功验证

下一步

错误处理

幂等性与重试

核心概念

​快速入门

​前提条件

​步骤 1：身份验证

​步骤 2：创建标签

​步骤 3：获取标签文件

​步骤 4：追踪货件

​成功验证

​下一步

错误处理

幂等性与重试

核心概念

快速入门

前提条件

步骤 1：身份验证

步骤 2：创建标签

步骤 3：获取标签文件

步骤 4：追踪货件

成功验证

下一步