> ## 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 Inventory ID 建立 Recall

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

為已抵達倉庫的一個或多個退件庫存項建立召回請求。召回會將物品從倉庫再次寄出，目的地為我們的香港倉庫。

## 前置條件

* 目標庫存項必須已存在於您的帳戶。`returnInventoryId` 由 `newInventoryCreated` webhook 事件推送——整合應在自有端快取。
* 每筆庫存目前的 `handlingStatusCode` 必須可依處理狀態機推進至召回（`Handling.rtn`）——通常 `pending` 或 `ohd` 狀態可用。
* 任何一項都不可處於已啟用（未取消）的召回中。
* 任何項所屬行項目都不可存在待處理的 VAS——請先處理。

## 必填欄位

* **`returnInventoryIdList`** — 非空 `List<long>`。

## 副作用

* 每筆庫存的 `handlingCode` 會被設為 `rtn`。
* 每筆庫存的 RMA 對映會被鎖定，禁止交換。
* 召回履行為非同步；狀態更新透過 webhook 推送（`recallShipmentDispatched`、`recallDelivered` 等）。

## 相關

* [建立召回訂單](/zh-Hant/api-reference/recall/create-recall-order) — 直接接受召回 payload 的舊版非批次端點。新整合請優先使用本批次端點。
* [依退件庫存 ID 取消召回](/zh-Hant/api-reference/recall/cancel-recall-by-return-inventory-id) — 在倉庫履行前撤銷召回。
* [取得所有召回庫存狀態](/zh-Hant/api-reference/recallstatus/get-all-recall-inventory-statuses) — 代碼至標籤對映。
* [Webhooks](/zh-Hant/webhooks) — `recallUpdateStatus` 與召回生命週期事件會將進度推送至您的端點。


## OpenAPI

````yaml post /api/Recall/createRecallByReturnInventoryId
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/Recall/createRecallByReturnInventoryId:
    post:
      tags:
        - Recall
      summary: Create recall by return inventory IDs
      operationId: ReturnUserApi_CreateRecallByReturnInventoryId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecallByReturnInventoryIdListRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CreateRecallByReturnInventoryIdListResponse
        '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:
    CreateRecallByReturnInventoryIdListRequest:
      type: object
      properties:
        returnInventoryIdList:
          type: array
          items:
            type: integer
            format: int64
          description: List of return inventory IDs
      required:
        - returnInventoryIdList
    CreateRecallByReturnInventoryIdListResponse:
      type: object
      properties:
        recallList:
          type: array
          items:
            $ref: '#/components/schemas/CreateRecallPayload'
          description: List of created recalls
    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'
    CreateRecallPayload:
      type: object
      properties:
        apiId:
          type: integer
          format: int32
        recallId:
          type: integer
          format: int64
        warehouseId:
          type: integer
          format: int32
        recallNumber:
          type:
            - string
            - 'null'
        recallStatusCode:
          type: string
          description: Recall status code
        warehouseRemarks:
          type:
            - string
            - 'null'
        recallInventoryList:
          type: array
          items:
            type: object
            description: '(see source: RecallInventoryPayload)'
    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.
  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

````