> ## 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.
# 取得 Tracking 資訊
此頁面由 AI 自動翻譯。API 技術規格以英文呈現為標準。如有任何疑問，請參閱[英文版本](/api-reference/tracking/get-tracking)。
此為 **Enterprise 專屬** 功能，僅對 Return Helper Enterprise 客戶開放。如需了解本服務的收費方式，請聯絡 [enterprise-solution@returnhelper.com](mailto:enterprise-solution@returnhelper.com)。
回傳 Return Helper 為您產生的退貨標籤的物流狀態與事件紀錄。請將該標籤的追蹤號碼作為 `reference` 傳入。
追蹤號碼會透過[標籤產生 webhook](/zh-Hant/webhooks#label-result) 送達——請在標籤建立時於您端保存該號碼，之後即可隨時呼叫本端點查詢最新狀態。
可查詢的範圍
追蹤功能涵蓋以[支援的服務類型](#supported-service-types)所建立的退貨標籤。若追蹤號碼來自其他服務類型，或來自本功能上線前建立的標籤，會回傳查無資料的錯誤，而非空的結果。
支援的服務類型
* `DHL_GERMANY`
* `RETURN_DHL_ECOMMERCE_DEU`
* `RETURN_DHL_ECOMMERCE_INTL_DEU`
* `ROYAL_MAIL`
* `RETURN_POSTMEN_RM_BIR`
* `RETURN_RM48_QRCODE_BIR_GBR`
* `FEDEX`
* `fedex_ground`
* `RETURN_FEDEX_GROUND_WA`
* `RETURN_FEDEX_GROUND_USCA`
* `RETURN_FEDEX_GROUND_TX`
* `UPS`
* `RETURN_UPS_SV_HKG`
解讀回應內容
| 欄位 | 說明 |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `statusSlug` | 貨件目前的狀態——請參閱[狀態值](#status-values)。`events` 中的每一筆都會帶有該時點所適用的狀態。 |
| `events` | 追蹤事件，每筆包含 `statusSlug`、`message`、`location` 與 `eventAt`。`message` 是承運商對該事件的原始描述文字。若承運商未提供地點，`location` 為 `null`。承運商尚未回報任何資訊時為空陣列。 |
| `lastEventAt` | 最近一次事件的時間；第一筆事件出現前為 `null`。 |
| `noFurtherUpdates` | 當本貨件預期不會再有後續事件時為 `true`。可據此停止輪詢。 |
| `courierName` | 承運商名稱（可閱讀的形式）。剛註冊的追蹤號碼可能為 `null`。 |
| `id` | 該追蹤紀錄的識別碼。 |
所有時間戳記皆為 UTC 的 ISO 8601 格式。
狀態值
| `statusSlug` | 意義 |
| ------------ | ------------------------------------------------------------------------------------------------ |
| `PENDING` | 追蹤號碼已註冊，承運商尚未回報任何資訊。 |
| `IN_TRANSIT` | 承運商正在運送包裹。 |
| `DELIVERED` | 承運商已回報包裹送達。 |
| `EXCEPTION` | 此追蹤號碼無法註冊追蹤，不會有任何事件送達。若您需要追查該貨件，請聯絡 [support@returnhelper.com](mailto:support@returnhelper.com)。 |
`message` 是承運商提供的自由文字——可顯示或記錄，但請勿解析，也不要據此做分支判斷。請改以 `statusSlug` 分支，並讓無法識別的值走預設分支，而非直接失敗。
錯誤
未提供或為空的 `reference` 會驗證失敗：HTTP `200`，`meta.status` 為 `400`，`meta.errorCode` 為 `VALIDATION_FAILED`，訊息位於 `meta.error.reference`。
其餘所有失敗都會回傳 HTTP `200`，`meta.status` 為 `404`，`meta.errorCode` 為 `null`，並在 `meta.error.message` 中提供可閱讀的訊息：
* 追蹤號碼不存在，或物流追蹤服務無法接受該值——訊息會說明屬於哪一種情況。
* `Tracking service is temporarily unavailable.` —— 無法連線至物流追蹤服務。此時 `reference` 仍可能有效，請稍後重試。
```json theme={null}
{
"correlationId": "0HNCJ2K1P9RQ4:00000003",
"meta": {
"status": 404,
"data": {},
"errorCode": null,
"error": {
"message": "Tracking service is temporarily unavailable."
}
}
}
```
* [Webhooks → 標籤結果](/zh-Hant/webhooks#label-result) — 追蹤號碼的送達來源。
* [錯誤代碼](/zh-Hant/reference/error-codes) — 完整的回應信封與錯誤約定。
## OpenAPI
````yaml get /api/Tracking/GetTracking
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/Tracking/GetTracking:
get:
tags:
- Tracking
summary: Get tracking
operationId: ReturnUserApi_GetTracking
parameters:
- name: reference
in: query
required: true
description: Tracking number of a return label generated by Return Helper.
schema:
type: string
example: TRACK123456789
responses:
'200':
description: >-
Success — `data` carries the tracking detail. `events` is an empty
list when the carrier has not reported anything yet.
content:
application/json:
schema:
$ref: '#/components/schemas/General_UserGetTrackingReply'
'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:
General_UserGetTrackingReply:
type: object
properties:
data:
$ref: '#/components/schemas/UserGetTrackingReply'
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'
UserGetTrackingReply:
type: object
properties:
id:
type:
- string
- 'null'
description: Identifier of the tracking record.
examples:
- b6e4a8b0-6f2e-4b7a-9c3d-8a1e2f3c4d5e
courierName:
type:
- string
- 'null'
description: >-
Human-readable carrier name. May be null for a newly registered
tracking number.
examples:
- USPS
trackingNumber:
type:
- string
- 'null'
description: Carrier tracking number.
examples:
- TRACK123456789
statusSlug:
type:
- string
- 'null'
description: >-
Current status of the shipment: PENDING, IN_TRANSIT, DELIVERED or
EXCEPTION.
examples:
- IN_TRANSIT
lastEventAt:
type:
- string
- 'null'
description: >-
ISO 8601 UTC timestamp of the most recent event. Null before the
first event arrives.
examples:
- '2026-07-29T08:00:00.000Z'
noFurtherUpdates:
type: boolean
description: True once no further tracking events are expected for this shipment.
events:
type: array
items:
$ref: '#/components/schemas/TrackingEventReply'
description: >-
Tracking events. Empty list when the carrier has not reported
anything yet.
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.
TrackingEventReply:
type: object
properties:
statusSlug:
type:
- string
- 'null'
description: >-
Status that applied at this event: PENDING, IN_TRANSIT, DELIVERED or
EXCEPTION.
examples:
- IN_TRANSIT
message:
type:
- string
- 'null'
description: >-
What happened, in the carrier's own wording. Free text — display or
log it, do not parse it.
examples:
- Arrived at facility
location:
type:
- string
- 'null'
description: >-
Where the event happened. Null when the carrier does not attach a
place to it.
examples:
- Los Angeles, CA 90001, US
eventAt:
type:
- string
- 'null'
description: ISO 8601 UTC timestamp of the event.
examples:
- '2026-07-29T08:00:00.000Z'
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
````