> ## 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 詳情
此頁面由 AI 自動翻譯。API 技術規格以英文呈現為標準。如有任何疑問，請參閱[英文版本](/api-reference/returnshipment/get-return-request)。
透過 [建立 Return Shipment](/zh-Hant/api-reference/returnshipment/create-return-shipment) 回傳的 `returnRequestId`，取得單一**退件運貨單**的完整紀錄——包含運貨單、其明細、面單與任何自訂欄位。
退件運貨單代表**倉庫收件前**的包裹。一旦倉庫登錄該包裹，它便成為*退貨庫存*項目；自該階段起，請改用 [取得 退貨庫存 詳情](/zh-Hant/api-reference/returninventory/get-return-inventory-details)，其中帶有收件後的處理資料。
找回遺漏的面單
面單位於 `shipments[].label.labelUrl`。此端點的主要用途是**系統異常後的對帳**：若您的接收端遺漏了某次面單通知，可使用 `returnRequestId` 呼叫本端點，直接讀取目前的 `labelUrl` 與 `trackingNumber`。`labelUrl` 為空表示面單尚未產生完成（或已失敗）——請檢查 `shipments[].label.labelRequestStatusCode`。
這是備援途徑，並非主要途徑。面單以非同步方式產生，並透過 `labelGenerated` webhook 推送，那才是真實資料來源。請勿在正常運作下輪詢本端點來探知面單——請訂閱 [Webhooks](/zh-Hant/webhooks#label-result)，僅在通知遺漏或推送失敗後，才用本端點補資料。
## OpenAPI
````yaml get /api/ReturnRequest/getReturnRequest
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/ReturnRequest/getReturnRequest:
get:
tags:
- ReturnShipment
summary: Get return shipment details
operationId: ReturnUserApi_GetReturnRequest
parameters:
- name: returnRequestId
in: query
required: false
schema:
type: integer
format: int32
description: Return request identifier, as returned by Create return shipment.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UserReturnRequestResponse'
'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:
UserReturnRequestResponse:
type: object
description: >-
Full record of a return shipment. Successful responses also carry the
standard envelope fields (`correlationId`, `meta`) alongside the fields
below.
properties:
returnRequestId:
type: integer
format: int32
description: Return request identifier
returnRequestNumber:
type: string
description: Return request number
sellerReferenceNumber:
type: string
description: Your merchant-supplied reference, echoed back for reconciliation
returnStatusCode:
type: string
description: Current return status code
returnTitle:
type: string
description: Return title
totalValue:
type: number
description: Declared total value of the return
totalValueCurrency:
type: string
description: ISO 4217 currency code of totalValue (e.g. USD)
rma:
type: string
description: >-
Warehouse-assigned RMA reference (uppercased). Populated once the
warehouse processes the parcel.
remarks:
type: string
description: Free-text remarks
isArchived:
type: boolean
description: Whether the return request is archived
returnRequestFrom:
type: string
description: Origin/source of the return request
shipments:
type: array
description: Shipments belonging to this return request, each with its label.
items:
type: object
properties:
shipmentId:
type: integer
format: int64
description: Shipment identifier
returnRequestId:
type: integer
format: int32
description: Parent return request identifier
shipmentNumber:
type: string
description: Shipment number
shipmentStatusCode:
type: string
description: Shipment status code
shipmentServiceType:
type: string
description: Service type used for the shipment
label:
type: object
description: Label associated with the shipment.
properties:
labelId:
type: integer
format: int64
description: Label identifier
labelRequestStatusCode:
type: string
description: Label generation status (e.g. queued, generated, failed)
trackingNumber:
type: string
description: Carrier tracking number
labelUrl:
type: string
description: >-
URL of the generated shipping label. Empty until label
generation completes; normally delivered via the
labelGenerated webhook. Read this field to recover a label
that was missed in webhook delivery.
qrcodeUrl:
type: string
description: URL of the label QR code, when applicable
carrier:
type: string
description: Carrier name
returnRequestLineItems:
type: array
description: Line items included in the return request.
items:
type: object
returnInventoryList:
type: array
description: >-
Return inventory records derived from this request, populated once
the warehouse has received the parcel. Empty before receipt — use
Get return inventory details for full inventory data at that stage.
items:
type: object
returnShipmentCustomFieldList:
type: array
description: Custom fields attached to the return shipment.
items:
type: object
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
````