> ## 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](/ja/webhooks#label-result) で届きます——ラベル作成時に自社側で保存しておき、最新のステータスが必要になったタイミングで本エンドポイントを呼び出してください。
照会できる対象
トラッキングの対象は、[対応しているサービスタイプ](#supported-service-types)で作成された返品ラベルです。それ以外のサービスタイプの追跡番号や、本機能の提供開始前に作成されたラベルの追跡番号は、空の結果ではなく not found のエラーを返します。
対応しているサービスタイプ
* `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 → ラベル結果](/ja/webhooks#label-result) — 追跡番号が届く場所。
* [エラーコード](/ja/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
````