> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建配送标签

> 为指定的物流商和货件详情创建配送标签。支持幂等创建 — 使用相同 idempotencyKey 重发请求将以 HTTP 200 返回原始结果，而不创建重复标签。



## OpenAPI

````yaml /flex-forward-zh-Hans.yaml post /labels
openapi: 3.1.0
info:
  title: Flex Forward Shipping API
  description: >-
    > **翻译说明：** 此 API
    参考文档由英文翻译而成。[英文版](/api-reference/labels/create-label)为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。


    Flex Forward 提供统一的 API，用于创建配送标签、获取标签文件，以及追踪多个物流商的货件。
  version: 1.0.0
servers:
  - url: https://api.flexforwardship.com
    description: Production
  - url: https://api-staging.flexforwardship.com
    description: Staging
security: []
tags:
  - name: CreateLabels
    description: 创建配送标签。
  - name: Labels
    description: 获取配送标签与标签文件。
  - name: Tracking
    description: 追踪货件状态与检查点。
  - name: Products
    description: 列出可用的配送产品。
paths:
  /labels:
    post:
      tags:
        - CreateLabels
      summary: 创建配送标签
      description: >-
        为指定的物流商和货件详情创建配送标签。支持幂等创建 — 使用相同 idempotencyKey 重发请求将以 HTTP 200
        返回原始结果，而不创建重复标签。
      operationId: createLabel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              description: 创建配送标签的请求载荷。
              type: object
              required:
                - idempotencyKey
                - courier
                - service
                - shipment
              properties:
                idempotencyKey:
                  minLength: 1
                  maxLength: 100
                  description: 客户端生成的唯一密钥，用于确保幂等标签创建。使用相同密钥重发请求将返回原始结果。
                  type: string
                  example: unique-key-per-request
                courier:
                  minLength: 1
                  description: >-
                    要使用的物流商代码。调用 GET /couriers 以列出您账户可用的有效物流商代码，然后传入其中一个返回的 code
                    值。
                  type: string
                  example: yunexpress
                service:
                  additionalProperties: false
                  description: 物流商服务配置。
                  type: object
                  required:
                    - productCode
                  properties:
                    shipperAccountId:
                      minLength: 1
                      description: 配送账户标识符。
                      type: string
                      example: optional-shipper-account-id
                    serviceCode:
                      description: 服务等级代码。
                      type: string
                    productCode:
                      minLength: 1
                      description: 物流商产品代码。
                      type: string
                      example: HKMUZXR
                label:
                  additionalProperties: false
                  description: 标签输出偏好设置。
                  type: object
                  properties:
                    format:
                      description: 标签文件格式（pdf 或 png）。
                      type: string
                      example: PDF
                units:
                  additionalProperties: false
                  description: 重量与尺寸的计量单位。
                  type: object
                  properties:
                    weight:
                      description: 重量单位（默认为 kg）。
                      type: string
                      example: KG
                    dimension:
                      description: 尺寸单位（默认为 cm）。
                      type: string
                      example: CM
                order:
                  additionalProperties: false
                  description: 订单参考信息。
                  type: object
                  properties:
                    customerOrderNumber:
                      minLength: 1
                      description: 用于交叉比对的订单编号。
                      type: string
                      example: N-2026-05-27-TEST-03
                    orderNumbers:
                      additionalProperties: false
                      description: 额外的订单标识符。
                      type: object
                      properties:
                        platformOrderNumber:
                          description: 电商平台订单编号。
                          type: string
                        trackingNumber:
                          description: 预先指定的追踪编号。
                          type: string
                        referenceNumbers:
                          description: 额外的参考编号。
                          type: array
                          items:
                            type: string
                shipment:
                  additionalProperties: false
                  description: 包含发件地、目的地及包裹的货件详情。
                  type: object
                  required:
                    - shipTo
                    - parcels
                  properties:
                    shipTo:
                      $ref: '#/components/schemas/ShipEndpoint'
                    shipFrom:
                      $ref: '#/components/schemas/ShipEndpoint'
                    parcels:
                      minItems: 1
                      description: 要寄送的包裹。
                      type: array
                      items:
                        $ref: '#/components/schemas/Parcel'
                customs:
                  additionalProperties: false
                  description: 跨境货件的报关信息。
                  type: object
                  properties:
                    taxIds:
                      additionalProperties: false
                      description: 通关用的税务标识符。
                      type: object
                      properties:
                        taxNumber:
                          description: 税务识别号码。
                          type: string
                        ioss:
                          description: 欧盟进口一站式服务（IOSS）号码。
                          type: string
                        vat:
                          description: VAT 登记号码。
                          type: string
                        eori:
                          description: 经济运营者注册识别（EORI）号码。
                          type: string
                serviceOptions:
                  description: 以代码与值配对方式提供的额外服务选项。
                  type: array
                  items:
                    additionalProperties: false
                    type: object
                    required:
                      - code
                    properties:
                      code:
                        minLength: 1
                        description: 选项代码。
                        type: string
                        example: V1
                      value:
                        description: 选项值。
                        type: string
                dangerousGoods:
                  additionalProperties: false
                  description: 危险品申报。
                  type: object
                  properties:
                    code:
                      description: 危险品分类代码。
                      type: string
                pickup:
                  additionalProperties: false
                  description: 取件点配置。
                  type: object
                  properties:
                    pickupPointCode:
                      description: 取件点标识符。
                      type: string
                courierOptions:
                  additionalProperties: false
                  description: 物流商专属选项。
                  type: object
                  properties:
                    yunexpress:
                      additionalProperties: false
                      description: YunExpress 专属选项。
                      type: object
                      properties:
                        sourceCode:
                          description: YunExpress 的来源代码。
                          type: string
                        platformAccountCode:
                          description: 平台账户代码。
                          type: string
                        sensitiveType:
                          description: 敏感品类型分类。
                          type: string
                        signatureService:
                          description: 签名服务标志（Y/N）。
                          type: string
                        houseNumber:
                          description: 收件人门牌号。
                          type: string
                        packageCount:
                          minimum: 1
                          description: 订单中的包裹数量。
                          type: integer
                        senderUsci:
                          description: 寄件人统一社会信用代码。
                          type: string
                        platformName:
                          description: 销售平台名称。
                          type: string
                        platformState:
                          description: 销售平台州或省。
                          type: string
                        platformAddress:
                          description: 销售平台地址。
                          type: string
                        platformPostalCode:
                          description: 销售平台邮政编码。
                          type: string
                        platformPhone:
                          description: 销售平台电话。
                          type: string
                        platformEmail:
                          description: 销售平台电子邮件。
                          type: string
                        platformSalesUrl:
                          description: 销售平台商品 URL。
                          type: string
                        cargoType:
                          description: 货物类型代码（W/F/O，日本必填）。
                          type: string
                        paymentPlatform:
                          description: 支付平台。
                          type: string
                        paymentPlatformAccount:
                          description: 支付平台账户。
                          type: string
                        paymentTransactionNumber:
                          description: 支付交易编号。
                          type: string
                        labelUrl:
                          description: 预先生成的标签 URL。
                          type: string
            examples:
              createLabel:
                summary: YunExpress cross-border label
                value:
                  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: alex.smith@example.com
                      address:
                        streetLines:
                          - 18 Distribution Blvd
                        city: Edison
                        state: New jersey
                        postalCode: 8817
                        countryCode: US
                    shipFrom:
                      contact:
                        firstName: John
                        lastName: Doe
                        phone: 886900676877
                        email: john.doe@example.com
                      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
        description: 创建配送标签的请求载荷。
      responses:
        '200':
          description: 标签创建请求的结果。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelResponse'
        '201':
          description: 标签创建请求的结果。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelResponse'
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationErrorResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: 标签创建请求的结果。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelResponse'
      security:
        - bearerAuth: []
        - apiKey: []
          apiToken: []
components:
  schemas:
    ShipEndpoint:
      additionalProperties: false
      description: 包含联系信息与地址的货件关系方。
      type: object
      required:
        - contact
        - address
      properties:
        contact:
          $ref: '#/components/schemas/Contact'
        address:
          $ref: '#/components/schemas/Address'
    Parcel:
      additionalProperties: false
      description: 包含一个或多个品项的包裹。
      type: object
      required:
        - weight
        - items
      properties:
        parcelId:
          description: 可选的客户端自定义包裹标识符。
          type: string
        weight:
          minimum: 0
          description: 包裹重量，单位由 units.weight 指定（默认为 kg）。
          type: number
          example: 0.5
        dimension:
          additionalProperties: false
          description: 包裹尺寸。
          type: object
          required:
            - length
            - width
            - height
          properties:
            length:
              minimum: 0
              description: 长度。
              type: number
              example: 30
            width:
              minimum: 0
              description: 宽度。
              type: number
              example: 20
            height:
              minimum: 0
              description: 高度。
              type: number
              example: 10
        items:
          minItems: 1
          description: 此包裹中的品项。
          type: array
          items:
            $ref: '#/components/schemas/ParcelItem'
    LabelResponse:
      additionalProperties: false
      description: 标签创建请求的结果。
      type: object
      required:
        - id
        - status
        - courier
        - customerOrderNumber
        - courierOrderNumber
        - courierTrackingNumber
        - error
      properties:
        id:
          format: uuid
          description: 唯一标签标识符。
          type: string
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        status:
          description: 标签创建结果 — created 或 failed。
          anyOf:
            - type: string
              enum:
                - created
            - type: string
              enum:
                - failed
          example: created
        courier:
          description: 使用的物流商。
          type: string
          example: yunexpress
        customerOrderNumber:
          description: 与此标签关联的客户订单编号。
          type: string
          example: N-2026-05-27-TEST-03
        courierOrderNumber:
          description: 物流商分配的订单编号，失败时为 null。
          anyOf:
            - type: string
            - type: 'null'
          example: YT2503010001
        courierTrackingNumber:
          description: 物流商分配的追踪编号，尚未获取时为 null。
          anyOf:
            - type: string
            - type: 'null'
          example: YT2503010001CN
        error:
          description: 标签创建失败时的错误详情，否则为 null。
          anyOf:
            - additionalProperties: false
              type: object
              required:
                - code
                - message
              properties:
                code:
                  description: 机器可读的错误代码。
                  examples:
                    - COURIER_ERROR
                  type: string
                message:
                  description: 人类可读的错误描述。
                  examples:
                    - 'YunExpress API returned HTTP 400: Bad request'
                  type: string
            - type: 'null'
    ValidationErrorResponse:
      additionalProperties: false
      description: 当请求体未通过模式验证时返回。
      type: object
      required:
        - error
        - details
      properties:
        error:
          description: 错误摘要消息。
          type: string
          enum:
            - Validation failed
        details:
          description: 字段级验证错误列表。
          type: array
          items:
            additionalProperties: false
            type: object
            required:
              - field
              - message
            properties:
              field:
                description: 指向无效字段的点分隔路径。
                type: string
                example: service.productCode
              message:
                description: 人类可读的验证消息。
                type: string
                example: service.productCode is required
    ErrorResponse:
      additionalProperties: false
      type: object
      required:
        - error
      properties:
        error:
          description: 人类可读的错误消息。
          type: string
          example: Shipping account not found
        code:
          description: 机器可读的错误代码。
          type: string
          example: COURIER_ERROR
    Contact:
      additionalProperties: false
      description: 货件寄件方或收件方的联系信息。
      type: object
      required:
        - firstName
      properties:
        firstName:
          minLength: 1
          description: 名字。
          type: string
          example: John
        lastName:
          description: 姓氏。
          type: string
          example: Doe
        company:
          description: 公司或组织名称。
          type: string
        phone:
          description: 含国家代码的电话号码。
          type: string
          example: +1-908-555-1234
        email:
          format: email
          description: 电子邮件地址。
          type: string
          example: john@example.com
        identification:
          additionalProperties: false
          description: 政府签发的身份证明文件。
          type: object
          properties:
            type:
              description: 证件类型（例如 passport、national_id）。
              type: string
              example: passport
            number:
              description: 证件号码。
              type: string
              example: AB1234567
    Address:
      additionalProperties: false
      description: 货件端点的实体地址。
      type: object
      required:
        - countryCode
        - city
        - postalCode
        - streetLines
      properties:
        countryCode:
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2 国家代码。
          type: string
          example: US
        state:
          description: 州或省份。
          type: string
          example: NJ
        city:
          minLength: 1
          description: 城市名称。
          type: string
          example: EDISON
        postalCode:
          minLength: 1
          description: 邮政编码或 ZIP 码。
          type: string
          example: '08817'
        streetLines:
          minItems: 1
          description: 街道地址行。
          type: array
          items:
            minLength: 1
            type: string
          example:
            - 18 Distribution Blvd
        shortAddress:
          description: 用于标签打印的简短地址。
          type: string
    ParcelItem:
      additionalProperties: false
      description: 包裹内的单一品项。
      type: object
      required:
        - descriptionEn
        - quantity
        - unitPrice
        - unitWeight
      properties:
        sku:
          maxLength: 50
          description: 库存单位标识符。
          type: string
          example: SKU-001
        descriptionEn:
          minLength: 1
          description: 品项的英文描述（报关必填）。
          type: string
          example: Wireless earbuds
        descriptionLocal:
          description: 以目的地国家语言描述的品项说明。
          type: string
        quantity:
          minimum: 1
          description: 数量。
          type: integer
          example: 1
        unitPrice:
          additionalProperties: false
          description: 单位价格。
          type: object
          required:
            - amount
          properties:
            amount:
              minimum: 0
              description: 价格金额。
              type: number
              example: 29.99
            currency:
              minLength: 3
              maxLength: 3
              description: ISO 4217 货币代码。
              type: string
              example: USD
        unitWeight:
          minimum: 0
          description: 每单位重量，单位由 units.weight 指定（默认为 kg）。
          type: number
          example: 0.5
        hsCode:
          maxLength: 50
          description: 国际商品统一分类（HS）代码。
          type: string
          example: '851830'
        salesUrl:
          format: uri
          description: 商品销售页面的 URL。
          type: string
        attributes:
          $ref: '#/components/schemas/ParcelItemAttributes'
    ParcelItemAttributes:
      additionalProperties: false
      description: 报关与物流用的扩展品项属性。
      type: object
      properties:
        material:
          description: 材质组成。
          type: string
        purpose:
          description: 品项的预期用途。
          type: string
        brand:
          description: 品牌名称。
          type: string
        spec:
          description: 产品规格。
          type: string
        model:
          description: 型号或型名。
          type: string
        remark:
          description: 附加备注。
          type: string
        manufacturer:
          $ref: '#/components/schemas/ParcelItemManufacturer'
        fabricCreationMethod:
          description: 面料制造方式（例如：梭织、针织）。
          type: string
        sellingPrice:
          minimum: 0
          description: 零售销售价格。
          type: number
        originCountry:
          minLength: 2
          maxLength: 2
          description: 品项原产地的 ISO 3166-1 alpha-2 国家代码。
          type: string
          example: CN
    ParcelItemManufacturer:
      additionalProperties: false
      description: 报关用的制造商详细信息。
      type: object
      properties:
        manufacturerId:
          description: 制造商标识符。
          type: string
        manufacturerName:
          description: 制造商名称。
          type: string
          example: Acme Corp
        manufacturerAddress:
          description: 街道地址。
          type: string
        manufacturerCity:
          description: 城市。
          type: string
        manufacturerProvince:
          description: 省份或州。
          type: string
        manufacturerCountry:
          description: 国家名称或代码。
          type: string
        manufacturerPostalcode:
          description: 邮政编码。
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKey:
      type: apiKey
      in: header
      name: x-rr-apikey
    apiToken:
      type: apiKey
      in: header
      name: x-rr-apitoken

````