> ## 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.

# 取得 退貨庫存 詳情

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

依 `returnInventoryId` 取得單筆退件庫存記錄的完整內容。常於收到 webhook（例如 `inventoryCreated`）後呼叫，以讀取目前狀態。

## 庫存圖片

回應中包含 `returnRequestLineItemImages[]` 陣列，列出附加到庫存對應 line item 上的圖片。**此端點回傳的是 S3 key，而非 URL** —— 要顯示或下載圖片，請以您所在環境的主機名稱與 key 串接出 URL。

### 條目結構

每筆紀錄提供同一張圖片的四種尺寸變體，方便您按 UI 用途選用：

| 欄位                  | 典型用途                 |
| ------------------- | -------------------- |
| `s3SmallFileKey`    | 列表視圖的縮圖              |
| `s3MediumFileKey`   | 詳細視圖的預覽              |
| `s3LargeFileKey`    | 全螢幕預覽                |
| `s3OriginalFileKey` | 原始上傳（最大；僅在需要未縮放圖時使用） |

### 構造 URL

依環境選擇主機名稱：

| 環境      | 圖片主機名稱                           |
| ------- | -------------------------------- |
| 沙箱（UAT） | `rr-dev-files.returnshelper.com` |
| 生產      | `file.returnhelpercentre.com`    |

公式：

```
URL = "https://" + <圖片主機名稱> + "/" + <key>
```

生產環境範例：

```
s3MediumFileKey = "img/returns/202606/27_1000040536_lmpiohbx.5n3_medium.jpg"
                  ↓ 串接
URL             = "https://file.returnhelpercentre.com/img/returns/202606/27_1000040536_lmpiohbx.5n3_medium.jpg"
```

key 已經包含完整的 S3 路徑。串接出來的 URL 可公開存取、不需要任何認證標頭、也不會過期；URL 與圖片內容均可在用戶端安全快取。

<Warning>
  **請將路徑視為不透明。** Return Helper 過去曾使用多種路徑前綴（例如 `img/returns/...` 與 `images/returns/...`）；只有**主機名稱**是穩定的。請勿解析、驗證或對路徑/檔名做任何模式比對。
</Warning>

無圖片時的空狀態：`returnRequestLineItemImages: []`。

<Note>
  此端點回傳的是查詢當下的狀態。如需在倉庫人員新增、替換或移除圖片時即時收到通知，請訂閱 [`changeLineItemImage`](/zh-Hant/webhooks#image-updated) webhook，而非反覆輪詢此端點。
</Note>

## 相關

* [依 Line Item Id 取得退貨庫存](/zh-Hant/api-reference/returninventory/get-return-inventory-by-line-item-id) —— 回應結構相同，但以 line item ID 查詢。
* [Image Updated webhook](/zh-Hant/webhooks#image-updated) —— 圖片變更的即時通知。
* [VAS Updated webhook](/zh-Hant/webhooks#vas-update) —— VAS 結果圖片的即時通知。


## OpenAPI

````yaml get /api/ReturnInventory/GetReturnInventory
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/ReturnInventory/GetReturnInventory:
    get:
      tags:
        - ReturnInventory
      summary: Get return inventory details
      operationId: ReturnUserApi_GetReturnInventory
      parameters:
        - name: returnInventoryId
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Return inventory identifier
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserReturnInventoryResponse'
        '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:
    UserReturnInventoryResponse:
      type: object
      properties:
        returnInventoryId:
          type: integer
          format: int64
          description: Return inventory identifier
    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'
    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

````