> ## 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-Hans/api-reference/servicetype/get-all-return-service-types)
   * [按始发国家与仓库取得服务类型](/zh-Hans/api-reference/servicetype/get-service-types-by-origin-country-and-warehouse)
2. **始发与目的地国家代码** — 透过 [取得所有始发国家](/zh-Hans/api-reference/country/get-all-from-countries-origin-countries) 与 [取得所有国家](/zh-Hans/api-reference/country/get-all-countries) 获取。代码使用 **ISO3**（`usa`、`gbr`、`chn`）。
3. **包裹尺寸与重量** — 必填且必须 `> 0`。可透过 [取得所有尺寸单位](/zh-Hans/api-reference/dimensionuom/get-all-dimension-units-of-measurement) 与 [取得所有重量单位](/zh-Hans/api-reference/weightuom/get-all-weight-units-of-measurement) 验证单位。
4. **幂等键** — 强烈建议。请在 `x-returnhelper-idempotency-key` 中传入新的 UUID，以避免重试时产生重复的运货单。详见 [幂等性章节](/zh-Hans/introduction#idempotency)。

## 重要字段

* **`totalValue` 与 `totalValueCurrency`** — `totalValue` 必须严格等于 `parcel.items[].value` 之和。币种使用 ISO 4217（例如 `USD`、`GBP`、`EUR`）；可透过 [取得所有交易类型](/zh-Hans/api-reference/transactiontype/get-all-transaction-types) 确认币种代码是否被支持。
* **`parcel.items`** — 是否支持多明细取决于您的账户配置。仅支持单明细的账户提交多明细时会返回验证软错误。如需调整配置，请联络客服。
* **尺寸** — `dimension1` 为最长边，`dimension2` 为次长，`dimension3` 为最短。
* **`sellerReferenceNumber`** — 您卖家自定义的标识符，可在三个互相独立的层级（顶层、`shipment`、以及 `parcel.items[]` 内每条 item）上传入。原样保存并在 Webhook 事件中回传，便于与您自己的订单系统对账。层级语义、省略时的回退行为，以及推荐的对账工作流见 [Seller Reference Number](/zh-Hans/reference/seller-reference-number)。

## 面单生成是异步的

即时回应中包含 `labelRequestStatusCode: queued`。最终面单 URL 与追踪号透过 `labelGenerated` webhook 事件推送（生成失败时则为 `labelFailed`）；仓库收件由 `markShipmentArrive` 事件通知，随后会有 `inventoryCreated` 事件。请订阅 [Webhooks](/zh-Hans/webhooks)——webhook 是运货单生命周期的真实数据源，并非轮询补救方案。

## 相关

* [按始发位置取得运送费用](/zh-Hans/api-reference/shipment/get-shipping-fees-from-origin-location) — 在提交前预览费用。
* [Webhooks](/zh-Hans/webhooks) — 订阅 `labelGenerated`、`labelFailed` 与 `markShipmentArrive`，以接收完整的运货单生命周期。
* [Seller Reference Number](/zh-Hans/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

````