> ## 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-Hans/api-reference/returninventory/update-return-inventory-handling) 移回 `ohd`。
* 从 [取得所有 VAS](/zh-Hans/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-Hans/api-reference/vas/get-all-value-added-services) — 有效的 `vasCode` 值。
* [取得所有 VAS 状态](/zh-Hans/api-reference/vasstatus/get-all-vas-statuses) — VAS 生命周期的代码到标签映射。
* [更新退件库存处理](/zh-Hans/api-reference/returninventory/update-return-inventory-handling) — 若库存已离开 `ohd`，将其移回。
* [Webhooks](/zh-Hans/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

````