> ## 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 建立 VAS

> Create value-added service requests for one or more return inventories. Inventory must be set to On-hold handling before creating VAS. Split parcel VAS must be submitted separately from other VAS types.

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

為已收到的退件庫存請求一項或多項加值服務（VAS）——品質檢驗、重新包裝、拍照、拆分包裹等。倉庫執行 VAS 後，會透過後續 webhook 事件回報結果。

## 前置條件

* 目標庫存項已存在於您的帳戶。`returnInventoryId` 由 `newInventoryCreated` webhook 事件推送——請在自有端快取。
* 每筆目標庫存的 `handlingCode` 必須為 `ohd`（暫存）。VAS 僅在庫存為暫存時允許；若已進入其他處理路徑，請先透過 [更新退件庫存處理](/zh-Hant/api-reference/returninventory/update-return-inventory-handling) 移回 `ohd`。
* 從 [取得所有 VAS](/zh-Hant/api-reference/vas/get-all-value-added-services) 選擇有效的 `vasCode`。

## 必填欄位

* **`createVasList`** — 非空 payload 列表。每個 payload 對應一筆庫存與一項或多項 VAS 請求。

每個 payload 內：

* **`returnInventoryId`** — 字串，必須可解析為 long；必須存在且為暫存狀態。
* **`createVasDetailList`** — VAS 明細物件列表，每項含 `vasCode` 與該 VAS 專屬欄位。

整批請求中 `returnInventoryId` 必須唯一——同一呼叫中不可對同一庫存建立兩個 payload。

## 拆分包裹規則

若任一 payload 中的 VAS 使用 `vasCode: SPLIT_PARCEL`：

* 該 VAS 必須是該 payload `createVasDetailList` 中的**唯一**一項（不能與其他 VAS 同 payload 同庫存併用）。
* 僅 `SPLIT_PARCEL` 允許（且通常需要）檔案附件。其他 VAS 代碼不可附件。

之所以強制此規則，是因為拆分會改變物理庫存形態；與其他 VAS 同 payload 會造成處理順序不明。

## 副作用

* VAS 處理期間，庫存的處理保持在 `ohd`。
* 後續 webhook 事件會回報進度：`vasUpdated`，以及拆分包裹時的 `splitLineItem` 與 `newInventoryCreated`（針對拆分件）。
* 拆分包裹 VAS 完成時，可能產生額外的庫存紀錄（拆分後的物品）。

## 相關

* [取得所有 VAS](/zh-Hant/api-reference/vas/get-all-value-added-services) — 有效的 `vasCode` 值。
* [取得所有 VAS 狀態](/zh-Hant/api-reference/vasstatus/get-all-vas-statuses) — VAS 生命週期的代碼至標籤對映。
* [更新退件庫存處理](/zh-Hant/api-reference/returninventory/update-return-inventory-handling) — 若庫存已離開 `ohd`，將其移回。
* [Webhooks](/zh-Hant/webhooks) — `vasUpdated` 事件會將 VAS 生命週期推送至您的端點。


## OpenAPI

````yaml post /api/Vas/CreateByReturnInventoryId
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/Vas/CreateByReturnInventoryId:
    post:
      tags:
        - Vas
      summary: Create VAS by return inventory ID
      description: >-
        Create value-added service requests for one or more return inventories.
        Inventory must be set to On-hold handling before creating VAS. Split
        parcel VAS must be submitted separately from other VAS types.
      operationId: ReturnUserApi_CreateVasByReturnInventoryId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVasByReturnInventoryIdRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralList_CreateVasReply'
        '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:
    CreateVasByReturnInventoryIdRequest:
      type: object
      properties:
        createVasList:
          type: array
          items:
            $ref: '#/components/schemas/CreateVasByReturnInventoryIdPayload'
          description: List of VAS creation payloads grouped by return inventory ID
      required:
        - createVasList
    GeneralList_CreateVasReply:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CreateVasReply'
          description: List of created VAS
    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'
    CreateVasByReturnInventoryIdPayload:
      type: object
      properties:
        returnInventoryId:
          type: string
          description: Return inventory ID to create VAS for
        createVasDetailList:
          type: array
          items:
            $ref: '#/components/schemas/CreateVasDetail'
          description: List of VAS details to create
      required:
        - returnInventoryId
        - createVasDetailList
    CreateVasReply:
      type: object
      properties:
        returnRequestLineItemId:
          type: integer
          format: int64
        createVasDetailList:
          type: array
          items:
            type: object
            description: '(see source: CreateVasDetailReply)'
    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.
    CreateVasDetail:
      type: object
      properties:
        vasCode:
          type: string
          description: >-
            VAS code to create (e.g. use Get All VAS to retrieve available
            codes)
        notes:
          type:
            - string
            - 'null'
          description: Additional notes for the VAS request
        metaQuantity:
          type: integer
          format: int32
          description: Quantity for the VAS operation (applicable for split parcel)
        vasFileList:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CreateVasFilePayload'
          description: Files for the VAS request (applicable for split parcel only)
      required:
        - vasCode
    CreateVasFilePayload:
      type: object
      properties:
        filename:
          type: string
          description: Filename of the VAS file
        fileKey:
          type: string
          description: S3 file key of the uploaded file
      required:
        - filename
        - fileKey
  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

````