跳转到主要内容
POST
/
labels
创建配送标签
curl --request POST \
  --url https://api.flexforward.com/labels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ord-20250301-abc123",
  "courier": "yunexpress",
  "service": {
    "shipperAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productCode": "YEXP01"
  },
  "shipment": {
    "shipTo": {
      "contact": {
        "firstName": "John",
        "lastName": "Doe",
        "phone": "+1-908-555-1234"
      },
      "address": {
        "countryCode": "US",
        "city": "EDISON",
        "postalCode": "08817",
        "streetLines": [
          "18 Distribution Blvd"
        ]
      }
    },
    "parcels": [
      {
        "weight": 0.5,
        "items": [
          {
            "descriptionEn": "Wireless earbuds",
            "quantity": 1,
            "unitPrice": {
              "amount": 29.99,
              "currency": "USD"
            },
            "unitWeight": 0.5
          }
        ]
      }
    ]
  }
}
'
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": {
    "code": "COURIER_ERROR",
    "message": "YunExpress API returned HTTP 400: Bad request"
  }
}

授权

Authorization
string
header
必填

部署时由 Flex Forward 团队发放的 API 访问令牌。

请求体

application/json
idempotencyKey
string
必填

确保幂等标签创建的唯一密钥。使用相同密钥的重复请求将返回原始结果。

示例:

"ord-20250301-abc123"

courier
string
必填

物流商识别码。

示例:

"yunexpress"

service
object
必填
shipment
object
必填
label
object
units
object
order
object
customs
object
serviceOptions
object[]
dangerousGoods
object
pickup
object
courierOptions
object

响应

幂等重放 — 此 idempotencyKey 的标签已创建。

id
string<uuid>
必填

唯一标签标识符。

示例:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

status
string
必填

标签创建状态 — createdfailed

示例:

"created"

courier
string
必填

使用的物流商。

示例:

"yunexpress"

courierOrderNumber
string | null
必填

物流商分配的订单编号,失败时为 null

示例:

"YT2503010001"

courierTrackingNumber
string | null
必填

物流商分配的追踪编号,尚未获取时为 null

示例:

"YT2503010001CN"

error
object
必填

标签创建失败时的错误详情,否则为 null