Track Detail Query (Single Number) API Official External Documentation
Basic Information
Name: Track Detail Query (Single Number)
Method: POST
Route: /client/trackinfo
Content-Type: application/json
Authentication:
- Request header X-Api-Key is required, or pass apiKey in the request body (choose one of the two)

Function Description
Use the assigned apiKey to query the tracking details of a single logistics number
Deduct points according to the number of accepted entries in the result, and record a usage log
Request Parameters
apiKey (string) Required (or via request header X-Api-Key): API credential
number (string) Required: logistics tracking number, only a single one is supported
Response Parameters
Success: { code:int, data:{ accepted:array, rejected:array? }, usage:{ deducted:int, remaining:int } }
Error: { code:int, msg:string }
Business Rules
Tracking number support: only a single number is supported, arrays are not supported
Daily limit: if the apiKey has daily_limit ≥ 0 configured, exceeding the limit returns 429
Account quota: if the user’s remaining quota is not enough to cover the current deduction, returns 402
Usage log: each successful deduction is recorded in the usage log (including client_userid, masked key, tracking number, IP, deducted points)
Package creation: when the tracking number in accepted does not exist in the package table, insert a minimal record automatically (tracking_number, register_time, created_at, updated_at, data_origin='Api', param_type='json')
Request Examples
Using request header to pass the key (recommended)
curl -X POST 'https://your-domain.com/client/trackinfo' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: sk_live_xxx' \
-d '{
"timestamp": 1739300000,
"number": "RR123456789CN",
}'
Passing the key in the request body (without header)
curl -X POST 'https://your-domain.com/client/trackinfo' \
-H 'Content-Type: application/json' \
-d '{
"timestamp": 1739300000,
"apiKey": "sk_live_xxx",
"number": "RR123456789CN"
}'
Successful Response Example
{
"code": 0,
"data": {
"accepted": [
{
"number": "RR123456789CN",
"carrier": 3011,
"package_status": "InTransit",
"latest_event_time": "2026-02-10 12:34:56",
"latest_event_info": "{\"status\":\"Arrived at sorting center\"}"
}
],
"rejected": []
},
"usage": {
"deducted": 1,
"remaining": 998
}
}
Logistics Tracking Result Field Description
Field Structure Overview
accepted
Type: Array Description: Collection of results that have been successfully processed. If there is no data that meets the conditions, this array is empty.

Contains the following fields:

Field Type Description
------ ------ -------------
number String Tracking number
carrier Number Carrier code
param String Additional tracking parameters; this field exists for backward compatibility and can be ignored
origin_country String Origin country, passed via the /register API
ship_date String Shipping date in YYYY/MM/DD format
destination_postal_code String Destination postal code
destination_country String Destination country
destination_city String Destination city
shipper String Shipper
consignee String Consignee
phone_number_last_4 String Last 4 digits of phone number
phone_number String Phone number
cpf_or_cnpj String Personal or company tax ID
special_tracking_info Object Special tracking information. This field is an object where each item contains two parts: number_type and parameter
tag String Custom tag, up to 100 characters; e.g. association ID, grouping remarks, etc.
lang String Specified language for logistics events, i.e. translation language code
track_info Object Main structure node for tracking information
---

track_info Detailed Structure
shipping_info
Type: Object Description: Region-related information node

Contains the following fields:

Field Type Description
------ ------ -------------
shipper_address Object Shipper address node
recipient_address Object Recipient address node
shipper_address
Field Type Description
------ ------ -------------
country String Country or region (uppercase)
state String State / Province
postal_code String Postal code
city String City
street String Street
coordinates Object Location coordinates (e.g. longitude and latitude)
coordinates
Field Type Description
------ ------ -------------
longitude String Longitude
latitude String Latitude
recipient_address
(Same structure as shipper_address)

---

latest_status
Type: Object Description: Latest status node

Contains the following fields:

Field Type Description
------ ------ -------------
status String Main logistics status
sub_status String Sub-status of the package
sub_status_descr String Status description
---

latest_event
Type: Object Description: Latest event. The structure and description are consistent with the items in the events array.

---

time_metrics
Type: Object Description: Time-related metrics node. estimated_delivery_date is a time range.

Contains the following fields:

Field Type Description
------ ------ -------------
days_after_order Number Days since order (shipment transit days)
days_after_last_update Number Days since last update
days_of_transit Number Transit days
days_of_transit_done Number Completed transit days (after delivery)
estimated_delivery_date Object Expected delivery time range node
days_after_order Calculation Rules
When status is Delivered, days = delivery time − time of the first event
When status is not Delivered and there is tracking result, days = current time − time of the first event
When there is no tracking result, days = --
days_after_last_update Calculation Rules
When status is Delivered, Returned & Delivered, or No Result, days = 0
In other cases, days = current time − time of the last event
days_of_transit Calculation Rules
When status is Delivered: 1. If there is InTransit_PickedUp, days = delivery time − pickup time 2. If there is no InTransit_PickedUp but there is InfoReceived, days = delivery time − time of the first event after InfoReceived 3. If neither InTransit_PickedUp nor InfoReceived exists, days = delivery time − time of the first event

When status is not Delivered but there is tracking result: 1. If there is InTransit_PickedUp, days = current time − pickup time 2. If there is no InTransit_PickedUp but there is InfoReceived, days = current time − time of the first event after InfoReceived 3. If there is no InTransit_PickedUp, there is InfoReceived, but only 1 tracking event, days = 0 4. If neither InTransit_PickedUp nor InfoReceived exists, days = current time − time of the first event

When there is no tracking result: days = 0

days_of_transit_done Calculation Rules
When status is Delivered: 1. If there is InTransit_PickedUp, days = delivery time − pickup time 2. If there is no InTransit_PickedUp but there is InfoReceived, days = delivery time − time of the first event after InfoReceived 3. If neither InTransit_PickedUp nor InfoReceived exists, days = delivery time − time of the first event

When status is not Delivered: days = 0

estimated_delivery_date
Field Type Description
------ ------ -------------
source String Indicates the provider of from and to. 17TRACK means provided by 17TRACK, Official means provided by carrier, null means no provider
from String Earliest estimated delivery time (ISO format), e.g. 2021-09-01T08:00:54-05:00
to String Latest estimated delivery time (ISO format), e.g. 2021-09-01T08:00:54-05:00
---

milestone
Type: Array Description: Milestones

Purpose: Display the major steps during transportation and their order and time.

Usage: Iterate over milestone items. Recommended order: InfoReceived >> PickedUp >> Departure >> Arrival >> OutForDelivery >> Delivered. (AvailableForPickup, Returned, Returning should be used as appropriate.)

Note: If time_iso or time_utc is null, it means the carrier did not provide time information. You can use milestone[].key_stage to look up more detailed event information in tracking.providers[].events[].stage.

Meaning of milestone.key_stage:

key_stage Meaning
----------- ---------
InfoReceived Information received – carrier has received shipment order information from the merchant and is waiting for pickup
PickedUp Picked up – carrier has collected the parcel from the merchant
Departure Departure – departed from the origin country’s port (theoretically after customs clearance)
Arrival Arrival – arrived at the destination country’s port (customs clearance is not guaranteed)
AvailableForPickup Available for pickup – parcel has arrived at the destination pickup point and needs to be collected by recipient
OutForDelivery Out for delivery – parcel is being delivered
Delivered Delivered successfully – parcel has been delivered
Returned Returned – parcel has been returned
Returning Returning – parcel is in return process, but not guaranteed to end in “Returned” status
Contains the following fields:

Field Type Description
------ ------ -------------
key_stage String Milestone, corresponding to tracking.providers[].provider[].events[].stage
time_iso String Time when the status occurred (ISO format)
time_utc String Time when the status occurred (UTC format)
time_raw Object Raw time information provided by the carrier
time_iso Description
1. Time when the status occurred (ISO format). Converted from the carrier’s local time with time zone; if time format is invalid, the raw time is returned. 2. If the upstream carrier provides time zone information, it is used first; otherwise, the time zone of the carrier’s head office is used. 3. Example: 2022-03-02T20:43:24-06:00 means UTC−06:00. 4. Removing the time zone part (-06:00) gives the carrier’s local time. 5. This corresponds to time_iso in the events collection, i.e. tracking.providers[].provider[].events[].time_iso.

time_utc Description
1. Time when the status occurred (UTC format), converted from time_iso. If time_iso is invalid, this is null. 2. Example: 2022-03-03T02:43:24Z. 3. This corresponds to time_utc in the events collection, i.e. tracking.providers[].provider[].events[].time_utc.

time_raw
Field Type Description
------ ------ -------------
date String Date information (year-month-day)
time String Time information (hour-minute-second)
timezone String Time zone information. If timezone is null but time_iso is valid, it means the time zone was filled by 17TRACK.
---

misc_info
Type: Object Description: Additional package information node

Contains the following fields:

Field Type Description
------ ------ -------------
risk_factor Number Package risk factor
service_type String Service type
weight_raw String Original weight information; unit depends on the carrier (grams, kilograms, pounds, etc.)
weight_kg String Converted weight in kilograms based on weight_raw
pieces String Number of pieces
dimensions String Original dimension info (L×W×H). Units may differ by carrier; most use centimeters.
customer_number String Customer number of the receiver
reference_number String Reference number
local_number String Last-mile tracking number
local_provider String Last-mile carrier
local_key Number Last-mile carrier code
---

tracking
Type: Object Description: Tracking information node

Contains the following fields:

Field Type Description
------ ------ -------------
providers_hash Number Hash value calculated based on event contents, used to determine whether there are changes
providers Array Carrier collection node
Special Notes
When the package is handled by a postal carrier, providers[0] represents the destination carrier information, and providers[1] represents the origin carrier information. It is possible that events in providers[0] and providers[1] have duplicated descriptions and timestamps.

Structure of providers Array
Field Type Description
------ ------ -------------
provider Object Carrier information node
service_type String Service type
latest_sync_status String Latest synchronization status
latest_sync_time String Latest synchronization time
events_hash Number Event hash value
provider_tips String Query tips
provider_lang String Current language of the carrier; null if unknown
events Array Event collection node
provider
Field Type Description
------ ------ -------------
key Number Carrier code
name String Carrier name
alias String Carrier alias
tel String Carrier phone
homepage String Carrier official website
country String Country where the carrier is located
Values of latest_sync_status
Failure: Synchronization failed
Success: Synchronization succeeded
events
Description: Each item is a logistics event object. The array is sorted in reverse chronological order: more recent events come first.

Field Type Description
------ ------ -------------
time_iso String Time when the event occurred (ISO format)
time_utc String Time when the event occurred (UTC time)
time_raw Object Raw time information provided by the carrier
description String Event description, including location, in-transit actions, and key status notes
description_translation Object Translation node for the description
location String Location
stage String Milestone status; may be missing depending on the carrier’s data
sub_status String Sub-status of the package
address Object Address information node
time_iso Description
1. Time when the event occurred (ISO format). Converted from the carrier’s local time with time zone; if format is invalid, the raw time is shown. 2. If the upstream carrier provides time zone information, it is used first; otherwise, the time zone of the carrier’s head office is used. 3. Example: 2022-03-02T20:43:24-06:00, which represents UTC−06:00. 4. Removing the time zone (-06:00) yields the carrier’s local time.

time_utc Description
1. Time when the event occurred (UTC), converted from time_iso. If time_iso is invalid, this is null. 2. Example: 2022-03-03T02:43:24Z.

time_raw
Field Type Description
------ ------ -------------
date String Date (year-month-day)
time String Time (hour-minute-second)
timezone String Time zone. If timezone is null and time_iso is valid, it means the time zone information was filled by 17TRACK.
description_translation
Field Type Description
------ ------ -------------
description String Translated event description
lang String Translation language code
address
Field Type Description
------ ------ -------------
country String Country / Region
state String State / Province
city String City
street String Street
postal_code String Postal code
coordinates Object Location coordinates node
coordinates
Field Type Description
------ ------ -------------
longitude String Longitude
latitude String Latitude
---

Error Response Examples
apiKey invalid / disabled
{ "code": 401, "msg": "apiKey invalid / disabled", "data": [] }
Insufficient remaining quota
{ "code": 402, "msg": "Insufficient remaining quota", "data": [] }
Daily limit exceeded
{ "code": 429, "msg": "Daily call limit reached", "data": [] }
Missing parameter
{ "code": 400, "msg": "number is required", "data": [] }