> ## 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-Hant.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

````