> ## 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-Hans/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-Hans/webhooks#label-result) — 跟踪号的送达来源。
* [错误代码](/zh-Hans/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
````