> ## 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-ja.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: EU Import One-Stop Shop（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: 1つ以上の品目を含む荷物。
      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: ID の種類（例：passport、national_id）。
              type: string
              example: passport
            number:
              description: ID 番号。
              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

````