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

# 建立 Return Shipment

<Warning>
  此頁面由 AI 自動翻譯。API 技術規格以英文呈現為標準。如有任何疑問，請參閱[英文版本](/api-reference/returnshipment/create-return-shipment)。
</Warning>

建立一份附帶面單請求的退件運貨單——幾乎是所有 Return Helper 整合的入口。運貨單將一個或多個包裹與其商品、聯絡資料、尺寸打包在一起。面單產生會非同步排程；即時回應中給出運貨單 ID 與 `labelRequestStatusCode`（通常為 `queued`），實際面單 URL 稍後透過 webhook 推送。

## 前置條件

呼叫前請備妥：

1. **`serviceTypeCode`** — 從下列任一端點取得可用的退件服務：
   * [取得所有退件服務類型](/zh-Hant/api-reference/servicetype/get-all-return-service-types)
   * [依始發國家與倉庫取得服務類型](/zh-Hant/api-reference/servicetype/get-service-types-by-origin-country-and-warehouse)
2. **始發與目的地國家代碼** — 透過 [取得所有始發國家](/zh-Hant/api-reference/country/get-all-from-countries-origin-countries) 與 [取得所有國家](/zh-Hant/api-reference/country/get-all-countries) 取得。代碼使用 **ISO3**（`usa`、`gbr`、`chn`）。
3. **包裹尺寸與重量** — 必填且必須 `> 0`。可透過 [取得所有尺寸單位](/zh-Hant/api-reference/dimensionuom/get-all-dimension-units-of-measurement) 與 [取得所有重量單位](/zh-Hant/api-reference/weightuom/get-all-weight-units-of-measurement) 驗證單位。
4. **等冪鍵** — 強烈建議。請在 `x-returnhelper-idempotency-key` 中傳入新的 UUID，以避免重試時產生重複的運貨單。詳見 [等冪性章節](/zh-Hant/introduction#idempotency)。

## 重要欄位

* **`totalValue` 與 `totalValueCurrency`** — `totalValue` 必須嚴格等於 `parcel.items[].value` 之和。幣別使用 ISO 4217（例如 `USD`、`GBP`、`EUR`）；可透過 [取得所有交易類型](/zh-Hant/api-reference/transactiontype/get-all-transaction-types) 確認幣別代碼是否支援。
* **`parcel.items`** — 是否支援多明細取決於您的帳戶設定。僅支援單明細的帳戶若提交多明細，會收到驗證軟錯誤。如需調整設定，請聯絡客服。
* **尺寸** — `dimension1` 為最長邊，`dimension2` 為次長，`dimension3` 為最短。
* **`sellerReferenceNumber`** — 您賣家自訂的識別碼，可在三個互相獨立的層級（頂層、`shipment`、以及 `parcel.items[]` 內每條 item）上傳入。原樣保存並在 Webhook 事件中回傳，便於與您自己的訂單系統對帳。層級語意、省略時的回退行為，以及建議的對帳工作流見 [Seller Reference Number](/zh-Hant/reference/seller-reference-number)。

## 面單產生為非同步

即時回應包含 `labelRequestStatusCode: queued`。最終面單 URL 與追蹤號透過 `labelGenerated` webhook 事件推送（產生失敗則為 `labelFailed`）；倉庫收件由 `markShipmentArrive` 事件通知，隨後會有 `inventoryCreated` 事件。請訂閱 [Webhooks](/zh-Hant/webhooks)——webhook 是運貨單生命週期的真實資料來源，並非輪詢的退路。

## 相關

* [依始發位置取得運送費用](/zh-Hant/api-reference/shipment/get-shipping-fees-from-origin-location) — 在提交前預覽費用。
* [Webhooks](/zh-Hant/webhooks) — 訂閱 `labelGenerated`、`labelFailed` 與 `markShipmentArrive`，以接收完整的運貨單生命週期。
* [Seller Reference Number](/zh-Hant/reference/seller-reference-number) — 如何設定 `sellerReferenceNumber` 並依據 Webhook 事件與您自己的訂單紀錄對帳。


## OpenAPI

````yaml post /api/ReturnShipment/createReturnShipment
openapi: 3.1.0
info:
  title: Return Helper API
  description: API documentation for Return Helper — covering User and Public endpoints.
  version: 1.0.0
servers:
  - url: https://api.returnshelper.com/uat/user
    description: Sandbox — User API
  - url: https://api.returnshelper.com/uat/public
    description: Sandbox — Public API
  - url: https://api.returnhelpercentre.com/v1/user
    description: Production — User API
  - url: https://api.returnhelpercentre.com/v1/public
    description: Production — Public API
  - url: https://api.returnhelperchina.com/user
    description: Production — User API (China)
security:
  - ApiKey: []
    ApiToken: []
paths:
  /api/ReturnShipment/createReturnShipment:
    post:
      tags:
        - ReturnShipment
      summary: Create return shipment
      operationId: ReturnUserApi_CreateReturnShipment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReturnShipmentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralCreateReturnShipmentReply'
        '401':
          description: >-
            Authentication failed. Returned when the `x-rr-apikey` or
            `x-rr-apitoken` header is missing or invalid. The body uses the
            standard `ApiResponse` envelope with `meta.error.message` describing
            the auth failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
      security:
        - ApiKey: []
          ApiToken: []
      servers:
        - url: https://api.returnshelper.com/uat/user
          description: Sandbox — User API
components:
  schemas:
    CreateReturnShipmentRequest:
      type: object
      properties:
        serviceTypeCode:
          type: string
          description: Return service type code
          default: fedex_ground
        orderTitle:
          type: string
          description: Order title / return title
          default: Return Label Title
        totalValue:
          type: number
          description: Total declared value of the return
          default: 100
        totalValueCurrency:
          type: string
          description: Currency code for totalValue (e.g. USD)
          default: usd
        sellerReferenceNumber:
          type: string
          description: Seller reference number
        remarks:
          type: string
          description: Additional remarks
        shipment:
          $ref: '#/components/schemas/CreateShipmentPayload'
          description: Shipment details including origin address and parcel info
      required:
        - serviceTypeCode
        - orderTitle
        - totalValue
        - totalValueCurrency
        - shipment
    GeneralCreateReturnShipmentReply:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CreateReturnShipmentReply'
          description: Created return shipment details
    ApiResponse:
      type: object
      description: >-
        Universal response envelope. Successful responses include the business
        payload as additional top-level fields alongside `correlationId` and
        `meta`. Failed responses (auth errors, validation errors) only populate
        `correlationId` and `meta`, with `meta.errorCode` and `meta.error`
        describing the failure.
      properties:
        correlationId:
          type:
            - string
            - 'null'
          description: >-
            Unique correlation ID for tracing the request through Return Helper
            systems.
        meta:
          $ref: '#/components/schemas/ApiResponseMeta'
    CreateShipmentPayload:
      type: object
      properties:
        shipToWarehouseId:
          type: integer
          description: Destination warehouse ID
          default: 2
        boxType:
          type: string
          description: Box type code
          default: cus
        sellerReferenceNumber:
          type: string
          description: Seller reference number for this shipment
        shipFrom:
          $ref: '#/components/schemas/ReturnShipmentShipFromPayload'
          description: Origin address
        parcel:
          $ref: '#/components/schemas/ReturnShipmentParcelPayload'
          description: Parcel dimensions, weight, and item list
        customFieldMap:
          type: object
          additionalProperties:
            type: string
          description: Custom key-value metadata
      required:
        - shipToWarehouseId
        - boxType
        - shipFrom
        - parcel
    CreateReturnShipmentReply:
      type: object
      properties:
        returnRequestId:
          type: integer
          format: int32
        returnRequestNumber:
          type:
            - string
            - 'null'
        shipmentId:
          type: integer
          format: int64
        referenceNumber:
          type:
            - string
            - 'null'
        labelId:
          type: integer
          format: int64
        labelRequestStatusCode:
          type:
            - string
            - 'null'
        cost:
          type: number
          format: decimal
        costCurrencyCode:
          type:
            - string
            - 'null'
    ApiResponseMeta:
      type: object
      description: >-
        Application-level metadata for every API response. Inspect `status` and
        `errorCode` to detect soft-error responses (validation failures arrive
        as HTTP 200 with `meta.status: 400`).
      properties:
        status:
          type: integer
          description: >-
            Application-level status code. For successful operations this
            mirrors the HTTP status (e.g. 200). For validation failures it
            reports the logical status (e.g. 400) even though the wire HTTP
            status is 200.
        data:
          type: object
          additionalProperties:
            type: string
          description: Reserved free-form metadata key/value pairs. Usually empty.
        errorCode:
          type:
            - string
            - 'null'
          description: >-
            Machine-readable error code (e.g. `VALIDATION_FAILED`). Non-null
            only when the operation failed.
        error:
          type: object
          additionalProperties: true
          description: >-
            Field-level or message-level error detail keyed by request property
            name. Empty object on success.
    ReturnShipmentShipFromPayload:
      type: object
      properties:
        country:
          type: string
          description: ISO3 origin country code
          default: usa
        contactName:
          type: string
          description: Sender contact name
          default: Your name
        phone:
          type: string
          description: Sender phone number
          default: '15622708183'
        email:
          type: string
          description: Sender email address
          default: user@example.com
        fax:
          type: string
          description: Sender fax number
        street1:
          type: string
          description: Address line 1
          default: Some address line 1
        street2:
          type: string
          description: Address line 2
          default: Some address line 2
        street3:
          type: string
          description: Address line 3
        state:
          type: string
          description: State / province
          default: tx
        city:
          type: string
          description: City
          default: Houston
        postalCode:
          type: string
          description: Postal code
          default: '77235'
      required:
        - country
        - contactName
        - street1
        - state
        - city
        - postalCode
    ReturnShipmentParcelPayload:
      type: object
      properties:
        weight:
          type: number
          description: Parcel weight
          default: 10.5
        weightUnit:
          type: string
          description: Weight unit (e.g. kg)
          default: g
        length:
          type: number
          description: Length (longest side)
          default: 10
        width:
          type: number
          description: Width (second longest side)
          default: 10
        height:
          type: number
          description: Height (shortest side)
          default: 10
        dimensionUnit:
          type: string
          description: Dimension unit (e.g. cm)
          default: cm
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReturnShipmentItemPayload'
          description: List of items in the parcel
          default:
            - description: Test item
              weight: 10.5
              value: 100
              weightUom: g
              valueCurrencyCode: usd
      required:
        - weight
        - weightUnit
        - length
        - width
        - height
        - dimensionUnit
        - items
    ReturnShipmentItemPayload:
      type: object
      properties:
        description:
          type: string
          description: Item description
          default: Test item
        weight:
          type: number
          description: Item weight
          default: 10.5
        weightUom:
          type: string
          description: Weight unit of measure (e.g. kg, g)
          default: g
        value:
          type: number
          description: Declared value of the item
          default: 100
        valueCurrencyCode:
          type: string
          description: Currency code for the declared value (e.g. USD)
          default: usd
        sellerReferenceNumber:
          type: string
          description: Seller reference number for the item
        customFieldMap:
          type: object
          additionalProperties:
            type: string
          description: Custom key-value metadata
          default:
            sku: '1234567890'
            hsCode: '1234567890'
            countryOfOrigin: usa
      required:
        - description
        - weight
        - weightUom
        - value
        - valueCurrencyCode
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-rr-apikey
      description: Your API key
    ApiToken:
      type: apiKey
      in: header
      name: x-rr-apitoken
      description: Your API token — keep this private

````