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": [] }