API docs 17TRACK

17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Go to dashboard
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
Parameter for…
Basic informati…

Carrier code

Country code

Tracking sta…

Tracking inf…


 
 
Get the API access key
Log in to the management console -> Settings ->Security-> Access Key, you can get the access key. If you need to
change the key, you can directly operate the "Change key". If you change the key, the new key will take effect within
5 minutes. Once the key takes effect, the old one will expire immediately.
API endpoint
API endpoint: https://api.17track.net/track/v1
Data request
All API interfaces use the http(s) POST method to submit requests. The request and response data are in UTF-8
encoded JSON format. All request base addresses start with http(s)://api.17track.net/track/v1/.
All requests need to be submitted with the key as the request header, with the header name 17token, as shown below
(registration number request):
curl -X POST
--header '17token:your secret key'
--header 'Content-Type:application/json'
--data '[{"number":"RR123456789CN"}]'
https://api.17track.net/track/v1/register
Data encapsulation
{
Tracking inf…
"code": 0,
"data": {
"accepted":[],
Event infor…
Important notes
API Reference(…

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack
Webhook

Develop Documentation
Package sta…


API
docs
Get API detailed description.
Setting
https://api.17track.net/en/doc
"rejected":[]
}
}
The response results are in a unified data encapsulation format, as shown below;
Name
Name
code
data
- accepted
- rejected
Description
Description
Error status code, 0 means no error, and for other errors refer to error status code
Data content of the response object encapsulation
For the normal processed part of the response in the request
For the abnormal processed part of the response in the request
Response status
HTTP status code
Name Description
200 The request is processed normally, and the returned data needs to be checked for the specific processing
result.
401 Request unauthorized, wrong key, access IP not in whitelist or account disabled.

404 The requested URL address is incorrect.
429 Access frequency exceeds limit.
1/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
Parameter for…
Basic informati…

Carrier code

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…

Important notes
 
API Reference(…
 

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack
Webhook

Setting
https://api.17track.net/en/doc
Name Description
Go to dashboard
500 Server Error.
503 Service temporarily unavailable.
Error status code
The error status code is a concrete representation of the data processing result based on the return of the http
status code.
Name
0
-18010001
-18010002
-18010003
-18010004
-18010005
-18010010
-18010011
-18010012
-18010013
-18010014
-18010015
-18010016
-18019901
-18019902
-18019903
-18019904
-18019905
-18019906
-18019907
-18019908
-18019909
-18019910
-18019801
-18019802
-18019803
-18019804
-18019805
-18019806
-18019807
Description
Success
IP address is not in whitelist.
Access token is invalid.
Internal service error, please retry later.
Account is disabled.
Unauthorized access.
The field of {0} is required.
The value of {0} is invalid.
The format of {0} is invalid.
Submitted data is invalid.
Request parameter number exceeds 40.
The value {0} of field {1} is invalid.
Only postal logictics can set up the last-mile shipping methods.
The tracking number {0} has been registered, don't need to repeat registration
The tracking number {0} does not register, please register first
Carrier cannot be detected.
Retrack is not allowed. You can only retrack stopped number.
Retrack is not allowed. You can only retrack each number once.
Stop tracking is not allowed. You can only stop numbers that are being tracked.
Exceeded daily request limit.
Quota is not enough for use.
No tracking information at this time.
The carrier is value {0} is not correct.
The registration information of multiple carriers with the same tracking number exists, please specify
the existing carrier parameters [carrier_old].
Submitted new carrier parameter [carrier_new] {0} may be incorrect.
The parameter of the carrier requesting for change cannot be the same.
New carrier parameter [carrier_new] or [final_carrier_new] requesting for change must be specified.
The tracking number {1} for the specified carrier {0} is not registered, or the existing carrier
parameter [carrier_old] is incorrect.
Change carrier for stopped tracking number is not allowed. Please activate it first before submitting a
change of carrier request.

Exceeded the maximum number of carrier revisions.
2/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
Parameter for…
Basic informati…

Carrier code

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…

Important notes
 
API Reference(…
 

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack
Webhook

Setting
https://api.17track.net/en/doc
Name
Description
Go to dashboard
-18019808 The tracking result has not been returned after the latest registration or modification.Please wait for
the tracking result to be returned before changing it.
-18019809 The registration information of the carrier with tracking number {0} already exists and cannot be
changed to a duplicate registration information.
-18019810 Data that meet the update condition are not unique.
-18019811 No valid data modification item.
Parameter format
Tracking number: The tracking number must be a continuous combination of 5 to 50 letters and numbers.
Carrier: The carrier code must be a valid shipping carrier's Key. For details, please refer to the carrier code.
Basic information
Carrier code
Visit https://res.17track.net/asset/carrier/info/carrier.all.json for all available carriers currently supported. As we keep
adding and supporting more and more carriers, please check and update it periodically. The relevant interfaces that
are using the carrier code must be submitted by using the code "Key" in our own defined carrier
information.Download carrier list.
Country code
Visit https://res.17track.net/asset/carrier/info/country.all.json to get the latest country code. After getting the tracking
information or receiving the push information, it is required to use the country codes of the origin and destination
countries listed to correspond to the actual countries of the parcel.
Package status
Name
Description
0
Not found
10
In transit
20
Expired
30
Pick up
35
Undelivered
40
Delivered
50
Alert
Tracking status
Name
Description
0
Unable To Track
1
Normal Tracking
2
Not Found
10
Web Error
11
Process Error
12
Service Error
20
Web Error [Cache]
21
Process Error [Cache]
22
Service Error [Cache]
Tracking information

Name Description
3/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
Parameter for…
Basic informati…

Carrier code

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…

Important notes
 
API Reference(…
 

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack
Webhook

Setting
https://api.17track.net/en/doc
Name
w1
w2
b
c
z0
z1
z2
z9
Description
Go to dashboard
First carrier code
Second carrier code
Country code of the origin country
Country code of the destination country
The latest event information (the latest one in the first and second carrier event sets)
First carrier event set, all stored in descending order.
Second carrir event set, all stored in descending order.
Cooperation e-commerce carrier event set, all stored in descending order. About cooperation e-commerce
carrier.
ygt1 The first carrier tracking consuming time, in milliseconds
ygt2 The second carrier tracking consuming time, in milliseconds
ygt9 The cooperation e-commerce carrier tracking consuming time, in milliseconds
ylt1 The last tracking time of the first carrier. Time 2079-01-01 signifies the time is invalid.
ylt2 The last tracking time of the second carrier. Time 2079-01-01 signifies the time is invalid.
ylt9 The last tracking time of cooperation e-commerce carrier. Time 2079-01-01 signifies the time is invalid.
is1 The first carrier's tracking status. It is valid when the first carrier's code (w1) is not 0; otherwise, it is
invalid.
is2 The second carrier's tracking status. It is valid when the second carrier's code (w2) is not 0; otherwise, it
is invalid.
ln1 Language of the event information used by the first carrier
ln2 Language of the event information used by the second carrier
ln9 Language of the event information used by the cooperation e-commerce carrier
hs The hash value of the latest event
e
Package status
f
Delivery time (Only for parcels with delivered results, -1 means the information is invalid)
yt Other prompt information
zex Tracking information extension
Tracking information extension
Name
Description
trC
Original shipping channel
trN
Original tracking number
dtS
First event time. Time unit: Unix timestamp, millisecond.
dtP
First delivery attempt time. Time unit: Unix timestamp, millisecond.
dtD
Delivery time. Time unit: Unix timestamp, millisecond.
dtL
Last event time. Time unit: Unix timestamp, millisecond.
dt
(Not enabled yet)
psex
(Not enabled yet)

Event information
Name Description
4/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
Parameter for…
Basic informati…

Carrier code

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…


 
 
Name
a
b
c
d
z
Important notes
The tracking number of all interface requests needs to be registered first through the register interface.
The interface frequency limit is 3req/s, which can be adjusted according to actual conditions.
Repetitive requests for the same number with same carrier only consume one tracking quota. When it gets expired or
being deleted and resubmitted, it will be recalculated.
The system will automatically stop the tracking of parcels whose events have not been updated for 30 consecutive
days or no event updates for 15 days after successful delivery;
The system will reserve the data of numbers that are stopped for tracking for 90 days, and physically delete the
corresponding data after the expiration dates.
For stopped tracking numbers, they can be activated and re-tracked only once.
API Reference(v1.0)
Register
40 tracking numbers are allowed to submit for registration per time for the interface.
POST /register
Request data example:
[
{
"number": "RR123456789CN",
"carrier": 3011,
"auto_detection":false,
"tag": "MyId"
Event infor…
},
{
"number": "1234"
Important notes
API Reference(…

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack
Description
Go to dashboard
Event time (Data may not be in valid time format, needs to be processed by string)
Mapping of the location (not used yet)
Event location
Event location extension (not used yet)
Event content description
}
]
Request data description:
Name
number
carrier
Required
Or Not Type Description
Yes
String Tracking number, conforming to the format requirements of a tracking
number.
No
Integer Carrier code. Currently our system can recognize most UPU tracking
numbers and the customized tracking numbers of our cooperative logistics
providers accurately. When you register these kinds of tracking numbers,
the carrier code is not required to be passed. It can be automatically
recognized when it is not passed. If the carrier code is passed wrong, we
would correct it and return the corrected carrier code. If the error code
-18019903 is returned while you register a tracking number, it means that
we cannot identify the carrier of the registered number accurately. Hoping
to avoid the identification error, please pass the correct carrier code to
register the tracking number again.

Webhook

Setting
https://api.17track.net/en/doc
5/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status



 
tag
No
{
"code": 0,
"data": {
"accepted": [
{
"origin": 1,
Error status …
"number": "RR123456789CN",
"carrier": 3011
Parameter for…
}
],
"rejected": [
Basic informati…

Carrier code

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…
Important notes
 
API Reference(…

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack
Go to dashboard
Description
Enable automatic carrier detection or not, which defaults to False. It will take
effect only when the carrier is not set, and the parameter is set to True.
When this parameter is in effect, the carrier detection algorithm will be
applied to recognize the first carrier; however, it is not guaranteed that the
carrier can be detected, or the accuracy of the carrier detection cannot be
guaranteed.
String Custom tracking number registration tag, Up to 100 characters.
Response data example:
HTTP status…

 
Required
Name
Or Not Type
auto_detection No
Bool
{
"number": "1234",
"error": {
"code": -18010012,
"message": "The format of '1234' is invalid."
}
}
]
}
}
Response result description:
Name
code
data
accepted
Description
Error status code, 0 means no error, and for other errors refer to error status code.
Corresponding response data to the request.
Tracking numbers that are accepted for registration normally with carrier code returned
correspondingly. If correction policy is executed, the returned carrier code might be different from the
passed one.
Tracking numbers that are accepted for registration normally.
-number
--carrier Carrier code that are accepted for registration normally.
--origin Carrier detection methods of registered tracking numbers:1. Accurate detection;2. Carrier passed by
the users;3. Automatic detection(not 100% correct).
-rejected Tracking number that are rejected for registration. For the specific rejected tracking numbers and
reasons, refer to the corresponding error code.
Change Carrier
sed to change the first carrier and the last-mile carrier. 40 tracking numbers are allowed to submit for change per
time for the interface.
POST /changecarrier
Request data example:

Webhook

Setting
https://api.17track.net/en/doc
6/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
[
"number": "RR123456789CN",
Develop Documen…



Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
Parameter for…
Basic informati…

Carrier code

Country code





Package sta…
"carrier_new": 3013,
"final_carrier_old": 0,
Request data description:
Required
Name
Or Not Type Description
number
Yes
String Tracking number, conforming to the format requirements of a tracking
number.
carrier_old
No
Integer Old carrier code, if not register multiple carriers with the same tracking
number, it can be skipped, no need to pass.
carrier_new
No
Integer New carrier code.
final_carrier_old No
Integer (Only available for postal logistics) Key of the old last-mile carrier. If the
registered tracking number is not repetitive, the settings can be left
empty.
final_carrier_new No
Integer (Only available for postal logistics) Key of the new last-mile carrier.
Response data example:
{
"code": 0,
"data": {
"accepted": [
{
"number": "RR123456789CN",
"carrier": 3013
}
Tracking inf…
Event infor…
 
API Reference(…

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…
],
"rejected": []
}
}
Response result description:
Name
code
data
accepted
-rejected
Setting
https://api.17track.net/en/doc
Description
Error status code, 0 means no error, and for other errors refer to error status code.
Corresponding response data to the request.
Tracking numbers that are accepted for request, and returned the latest carrier code.
Tracking number that are rejected for request. For the specific rejected tracking numbers and reasons,
refer to the corresponding error code.
ChangeInfo
Relevant additional information used to modify tracking.
POST /changeinfo
Request data example：
{
"number": "LW503511611CN",
"carrier":3011,
DeleteTrack
Webhook

]
Tracking inf…
Important notes

"final_carrier_new": 0
}
Tracking sta…

 
"carrier_old": 3011,
Get the API acc…
API endpoint
Go to dashboard
{
"items": {
"tag": "This is my order id."
}

}
7/19
17/01/2022, 12:26
Tracking API
 
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status



 
Required
Name Or Not
number Yes
carrier No
items Yes
--tag
No
"data": {
"accepted": [
{
"number": "LW503511611CN",
"carrier": 3011
}
],
Basic informati…

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…
Important notes
 
API Reference(…

Register

Change Car…
Description
Tracking number, conforming to the format requirements of a tracking number.
Carrier code.
Data item set that needs to be modified. Currently, only tag is supported to be
modified. Other items submitted will be ignored.
String Custom tracking number registration tag, Up to 100 characters.
"code": 0,
Parameter for…
Carrier code
Type
String
Integer
Dict
{
Error status …

Go to dashboard
Response data example：
HTTP status…

 
Request parameter description:
API docs | 17TRACK
"rejected": []
}
}
Response parameter description:
Name
code
data
accepted
-rejected
Description
Error status code, 0 means no error, and for other errors refer to error status code.
Corresponding response data to the request.
Tracking numbers that are accepted for request, and returned the latest carrier code.
Tracking number that are rejected for request. For the specific rejected tracking numbers and reasons,
refer to the corresponding error code.
StopTrack
40 tracking numbers are allowed to submit per time for the interface.
POST /stoptrack
Request data example:
[
{
"number": "RR123456789CN",
"carrier": "3011"

ChangeInfo

StopTrack
Request parameter description:

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…
Required
Name Or Not Type Description
number Yes
String Tracking number, conforming to the format requirements of a tracking number.
carrier No
Integer Carrier code. If it is not passed, and if there are multiple data for one same tracking
number (different carriers), they will all be processed.

DeleteTrack
}
]
Response data example:

Webhook

Setting
https://api.17track.net/en/doc
8/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
{
"data": {
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
Parameter for…
Basic informati…

Carrier code

Country code

Package sta…
"accepted": [
{
"number": "RR123456789CN",
"carrier": "3011"
}
]
}
}
Response parameter description:
Name
code
data
accepted
-rejected
Description
Error status code, 0 means no error, and for other errors refer to error status code.
Corresponding response data to the request.
Tracking numbers that are accepted for request.
Tracking number that are rejected for request. For the specific rejected tracking numbers and reasons,
refer to the corresponding error code.
Retrack
40 tracking numbers are allowed to submit per time for the interface.
POST /Retrack
Request data example:
[
{

Tracking sta…

Tracking inf…

Tracking inf…
Request parameter description:

Event infor…
Required
Name Or Not Type Description
number Yes
String Tracking number, conforming to the format requirements of a tracking number.
carrier No
Integer Carrier code. If it is not passed, and if there are multiple data for one same tracking
number (different carriers), they will all be processed.

Important notes
 
API Reference(…

Register

Change Car…

ChangeInfo



 
Go to dashboard
"code": 0,
"number": "RR123456789CN",
"carrier": "3011"
}
]
Response data example:
{
"code": 0,
"data": {
"accepted": [
StopTrack
{
"number": "RR123456789CN",
"carrier": "3011"
Retrack
GetTrackList
}
]
}
}

GetTrackInfo
Response result description:

CarrierIdent…

DeleteTrack
Name
code
data
Webhook

Setting
https://api.17track.net/en/doc
Description
Error status code, 0 means no error, and for other errors refer to error status code.
Corresponding response data to the request.

9/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status



 
{
"number": "RR123456789CN",
"carrier": 3011,
HTTP status…
"register_time_from": "2019-01-01 12:24:00",
"register_time_to": "2019-02-01",
Error status …
"tracking_time_from": "2019-01-01",
"tracking_time_to": "2019-12-01",
"push_time_from": "2019-01-01",
Parameter for…
"push_time_to": "2019-12-01",
"push_state": 0,
Basic informati…

Carrier code

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…

Important notes
 
API Reference(…
 
Name Description
Go to dashboard
Tracking numbers that are accepted for request.
accepted
-rejected Tracking number that are rejected for request. For the specific rejected tracking numbers and reasons,
refer to the corresponding error code.
GetTrackList
Get tracking number list
POST /gettracklist
Request data example:
"stop_time_from": "2019-01-01",
"stop_time_to": "2019-12-01",
"package_state": 10,
"tracking_state": 0,
"page_no": 1
}
Request parameter description:
Name
number
Required Or Not Type
No
String
carrier
register_time_from
register_time_to
tr
tracking_time_to
push_time_from
push_time_to
push_state No
No
No
No
cking_time_from
No
No
No
Integer
No
No
No
No
Integer
DateTime
DateTime
No
DateTime
DateTime
DateTime
Push result 0: Not pushed;
1: Success; 2: Failure.
DateTime
DateTime
Integer
Bool
No
Integer

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList
stop_time_from
stop_time_to
package_state
tracking_state

GetTrackInfo
page_no

CarrierIdent…
Response data example:

DeleteTrack
Description
Tracking number, conforming to the format
requirements of a tracking number.
Carrier code.
Register time from (UTC).
Register time to (UTC).
DateTime
Latest tracked time to (UTC).
Latest pushed time from (UTC).
Latest pushed time to (UTC).
Tracking Stopped time from (UTC).
Tracking Stopped time to (UTC).
Package status.
Tracking status：1: Automatic tracking; 0:
Tracking stopped.
Page number, defailt is 1.

Webhook

Setting
https://api.17track.net/en/doc
10/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
{
"data": {
Develop Documen…




 

 
"accepted": [
{
"number": "RV929123748CN",
Get the API acc…
"w1": 3011,
"b": 301,
API endpoint
"w2": 10011,
"c": 1001,
"e": 20,
Data request
"rt": "2019-08-26 09:48:16",
"tt": "2020-01-16 02:52:11",
Data encapsula…
"pt": "2019-11-08 06:16:25",
Response status
"st": "2020-02-28 02:36:59",

HTTP status…

Error status …
Parameter for…
Basic informati…

Carrier code

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…

Important notes
 
API Reference(…
 
Go to dashboard
"code": 0,

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack
Webhook

Setting
https://api.17track.net/en/doc
"ps": 200,
"sr": 1,
"ir": true,
"ts": false,
"mc": 0,
"tag": null
}
]
}
}
Response result description:
Name Description
code
Error status code, 0 means no error, and for other errors refer to error status code.
data
Corresponding response data to the request.
Accepted and processed normally with result set returned. If the returned set is empty, it means there
accepted is no data that meets the conditions.
-Tracking number.
number
--w1
First carrier code.
--w2
Second carrier code.
--b
Country code of the origin country.
--c
Country code of the destination country.
--e
Package status.
--rt
Register time.
--tt
Latest tracked time.
--pt
Latest pushed time.
--ps
Pushed http status code.
--st
Tracking Stopped time.
--sr
Tracking Stopped reason 1: Expiration rules; 2: API request; 3: Manual operation; 4: Invalid carrier.
--ir
Retrack enabled or not 1: Yes; 0：No.
--ts
Tracking status 1：Automatic tracking; 0：Tracking stopped.
--mc
Carrier modification times.
--tag
Custom tracking number registration tag.
-errors Tracking condition settings errors.
GetTrackInfo
40 tracking numbers are allowed to submit per time for the interface.

11/19
17/01/2022, 12:26
Tracking API
 
Develop Documen…

POST /gettrackinfo
Request data example:
API docs | 17TRACK
Go to dashboard
[
{
Get the API acc…
"number": "RR123456789CN",
"carrier": "3011"
}

API endpoint

Data request
Request parameter description:

Data encapsula…
 
Response status
Required
Name Or Not Type Description
number Yes
String Tracking number, conforming to the format requirements of a tracking number.
carrier No
Integer Carrier code. If it is not passed, and if there are multiple data for one same tracking
number (different carriers), then return all the data.

 

HTTP status…

Error status …
Response data example:
Parameter for…
Basic informati…

Carrier code

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…

Important notes
 
API Reference(…
 
]

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack

Webhook

Setting
https://api.17track.net/en/doc
12/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
{
"data": {
Develop Documen…




 

 
"number": "RM101474005CN",
"tag": "",
"track": {
"b": 301,
"c": 1803,
"e": 10,
Data request
"f": -1,
"w1": 3011,
Data encapsula…
"w2": 18031,
"z1": [
{
Response status

HTTP status…

Error status …
"a": "2015-05-13 14:47",
"b": null,
"c": "",
"d": "",
],
"z2": [
{
"a": "2015-05-31 00:00",
Basic informati…

Carrier code

Country code
"b": null,
"c": "",
"d": "",
"z": "Distribué ANDORRE LA VIEILLE (09)."
}
],
"z9": [],
Package sta…
"ygt1": 370,
"ygt2": 0,
"ygt9": 0,
Tracking sta…

Tracking inf…

Tracking inf…
"is1": 1,
"is2": 0,
"ln1": "zh-CHS",
"ln2": null,
"ln9": null,
"hs": 627236210,
"z0": {
Event infor…
"a": "2015-05-29 09:00",
"b": null,
"c": "BLAGOVESCH 1",
Important notes
"d": "",



"ylt9": "2079-01-01 00:00:00",
"yt": "",
"zex": {
"trN": "",
ChangeInfo
"trC": 0,
"psex": 0,
"dt": 1586726160000,
StopTrack

GetTrackList
"dtS": 1586726160000,
"dtP": 0,
"dtD": 0,
"dtL": 1588846740000
}
}
}
GetTrackInfo

CarrierIdent…

DeleteTrack
Webhook

"ylt2": "2079-01-01 00:00:00",
Change Car…
Retrack

},
"ylt1": "2015-06-01 20:44:52",
Register

Setting
https://api.17track.net/en/doc
移交海关"
"z": "
API Reference(…

电子信息已收到"
"z": "
}
Parameter for…

 
{
API endpoint

 
"accepted": [
Get the API acc…


Go to dashboard
"code": 0,
]
}
}
Response result description:
Name
code
Description
Error status code, 0 means no error, and for other errors refer to error status code.

13/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
Parameter for…
Basic informati…


 
Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…
Description
Go to dashboard
Corresponding response data to the request.
Sets that are accepted and processed normally with carrier code returned correspondingly.
Tracking number.
Custom tracking number registration tag.
Tracking information.
Tracking number that are rejected for getting tracking infomation. For the specific rejected tracking
numbers and reasons, refer to the corresponding error code.
CarrierIdentify
A maximu of 40 trakcing numbers can be sent to this API each time. Use this when you want to register some
numbers but don't know what carriers they belong to. Possible matches of carrier will be returned.
POST /carrierIdentify
Request data example:
[
{
Carrier code

"number": "RR123456789CN"
}
]
Request parameter description:
Required Or
Name Not
number Yes
{
"code": 0,
"data": {
"accepted": [
{
API Reference(…
Change Car…

ChangeInfo



GetTrackInfo
"hint": [
{
"may": "1151",
"score": 0.0
},
{
"may": "xxx",
"score": 0.0
},
...
]
},
{
"score": 1.0,
"number": "EL123456789CN",
"carrier": 3011
}
CarrierIdent…
DeleteTrack
Webhook

"carrier": 0,
Retrack
GetTrackList

"number": "LM0010039036",
StopTrack


"score": 0.0,
Register

Setting
https://api.17track.net/en/doc
Type Description
String Tracking number, conforming to the format requirements of a tracking
number.
Response data example:
Important notes

 
Name
data
accepted
-number
--tag
--track
-rejected
],
"rejected": []
}
}
Response result description:

14/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
Parameter for…
Basic informati…



Carrier code
[
Country code
Package sta…
{
"number": "RR123456789CN",
"carrier":3011
}
]

Tracking sta…
Request parameter description:

Tracking inf…

Tracking inf…

Event infor…
Required Or
Name Not
number Yes

Important notes
 
API Reference(…


carrier Yes
{
Register
"code":0,
Change Car…
{
"data":
"accepted":
[
ChangeInfo
{

StopTrack
}

"carrier":100271
],
"rejected":
GetTrackList
]
GetTrackInfo

CarrierIdent…

DeleteTrack
Webhook

"number":"621366941543",
Retrack

Setting
https://api.17track.net/en/doc
Type Description
String Tracking number, conforming to the format requirements of a tracking
number.
String Carrier code.
Response data example:


 
Name
Description
Go to dashboard
code
Error status code. 0 means no error. For other errors, please refer to the error status code.
data
Data content of the response object encapsulation.
-accepted For the successfully processed part of the response.
--number Tracking number.
--carrier Carrier code.
--score
Float. Matching accuracy where 1.0 means exact match.
--hint
Array. The possible matches for the carriers. At most 10 will be returned here.
----may Candidate carrier code.
----score Matching accuracy. Currently not available. Will always return 0.0.）
-rejected For the abnormal processed part of the response.
DeleteTrack
Delete the successfully registered tracking numbers.
POST /deleteTrack
Request data example:
[
}
}
Response result description:
Name
code
data
-accepted
Description
Error status code, 0 means no error, and for other errors refer to error status code.
Data content of the response object encapsulation.
For the normal processed part of the response in the request.

15/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Develop Documen…

Get the API acc…

API endpoint

Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
Parameter for…
Basic informati…

Carrier code

Country code


Tracking sta…

Tracking inf…

Tracking inf…

Event infor…
Important notes
 
API Reference(…

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack
Webhook

Setting
https://api.17track.net/en/doc
Description
Tracking number.
Carrier code.
For the abnormal processed part of the response in the request.
Tracking number.
Carrier code.
Go to dashboard
Webhook
Setting
Set the callback interface URL by logging into the management console -> Settings -> Webhook. If it is not set, no
notification will be sent.
Notification policy: If the Webhook URL of the notification call returns http status code 200, it means that the
notification call has been processed normally and will not retry, otherwise the notification call will be considered as a
failure. If the notification call fails, it will retry in the next 10, 30, and 60 minutes successively. If the notification call
still fails, the current change notification for the corresponding tracking number will be abandoned, while the
subsequent notifications will not be affected.
Data and Sign
When the tracking event is updated or the number is no longer tracked according to the policy, the system will
generate a POST request to be sent to the callback url you set on the Settings page. The push data format is
uniformly adopted in the following format:
{
"sign": "a829f039332706b9b888eba84b77bd01f425ed327d2c4a92b50bba5beb0a0260",
"event": "TRACKING_STOPPED",
Package sta…

 
Name
--number
--carrier
-rejected
--number
--carrier
"data": {
"number": "RM101474005CN",
"carrier":3011,
"tag":""
}
}
Data format
Name Description
sign Data sign
event Notification types supported currently: TRACKING_STOPPED：Stop tracking notification;
TRACKING_UPDATED：Tracking information update notification. When the tracking event is updated, the
notification of the latest tracking information will be pushed.
data Pushed data will vary depending on the event.
Sign verification
In order to ensure that the information source is pushed by 17TRACK, it is recommended to verify the sign of the
received data. During the verification, splice the value of type, value of data, and the API access key with the slash:
event/data/secretkey, and then calculate SHA256; if the calculated result is consistent with the sign, it means that the
information source is legal.
Sign example
The push data format is uniformly adopted in UTF-8 encoded JSON format. And parse the raw data (No formatting,
spaces, or line breaks, etc. are needed). For example, the received data is:
{"sign":"a829f039332706b9b888eba84b77bd01f425ed327d2c4a92b50bba5beb0a0260","event":"TRACKING_STOPPE
, then the parsed result would be: event:
TRACKING_STOPPED data: {"number":"RM101474005CN","carrier":3011,"tag":""} If the secret key is
6A8D7CFC3F7A41149E0A4EE8ABD0DD8A, then the data to be signed would be
TRACKING_STOPPED/{"number":"RM101474005CN","carrier":3011,"tag":""}/6A8D7CFC3F7A41149E0A4EE8ABD0DD
8A. Pass this data through SHA256 and use hexadecimal encoding. If the calculated result is consistent with sign,
means the data is valid.
Notification type

D","data":{"number":"RM101474005CN","carrier":3011}}
Tracking stopped
16/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
{
"event": "TRACKING_STOPPED",
Develop Documen…

API endpoint

Data request

Data encapsula…
 
Response status

 

HTTP status…

Error status …
"number": "RM101474005CN",
"carrier": 3011,
"tag":""
}
}
Name
sign
event
data
Description
Data sign.
TRACKING_STOPPED
Numbers that are stopped for tracking.
Tracking updated
Parameter for…
Basic informati…

Carrier code

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…

Important notes
 
API Reference(…
 
"data": {
Get the API acc…

Go to dashboard
"sign": "a829f039332706b9b888eba84b77bd01f425ed327d2c4a92b50bba5beb0a0260",

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack

Webhook

Setting
https://api.17track.net/en/doc
17/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
Develop Documen…




 
Get the API acc…
API endpoint
Data request
"tag": "",
"track": {
"b": 301,
"c": 2105,
"e": 10,
"f": -1,
"w1": 190316,
"w2": 0,
"is2": 0,
"ln1": "en",
"ln2": null,
HTTP status…
"ln9": "en",
Error status …
"ygt2": 0,
"ygt1": 366,
"ygt9": 423,
"ylt1": "2020-05-11 12:05:58",
Parameter for…
"ylt2": "2079-01-01 00:00:00",
Basic informati…
"yt": "",

Carrier code

Country code
Package sta…
Tracking sta…

Tracking inf…

Tracking inf…

Event infor…
"ylt9": "2020-05-11 12:05:58",
"z0": {
"a": "2020-05-07 10:19",
"b": null,
"c": "",
"d": "BLOOMINGTON, CA 92316",
"z": "Departed Shipping Partner Facility, USPS Awaiting Item -> Your item
departed a shipping partner facility at 10:19 am on May 7, 2020 in BLOOMINGTON, CA 92316. This
does not indicate receipt by the USPS or the actual mailing date."
},
"z1": [
{
"a": "2020-05-07 10:19",
"b": null,
"c": "",
"d": "BLOOMINGTON, CA 92316",
"z": "Departed Shipping Partner Facility, USPS Awaiting Item -> Your item
departed a shipping partner facility at 10:19 am on May 7, 2020 in BLOOMINGTON, CA 92316. This
does not indicate receipt by the USPS or the actual mailing date."
},
{
Important notes
"a": "2020-05-05 16:49",
"b": null,
API Reference(…









 
"number": "STOAA0000272952YQ",
Response status

 
"data": {
"hs": 730243286,


"event": "TRACKING_UPDATED",
"is1": 1,

 
Go to dashboard
"sign": "34f40c8fc37f9a7100c65215b0df85c58cc4880cf2e832fe91c86de1bc00b181",
Data encapsula…


{
"c": "",
"d": "BLOOMINGTON, CA 92316",
"z": "Arrived Shipping Partner Facility, USPS Awaiting Item"
Register
},
{
Change Car…
"a": "2020-04-12 21:16",
"b": null,
ChangeInfo
StopTrack
Retrack
GetTrackList
"c": "",
"d": "FREMONT, CA 94538",
"z": "Picked Up by Shipping Partner, USPS Awaiting Item"
}
],
"z2": [],
"z9": [
{
"a": "2020-04-13 17:07",
"b": null,
GetTrackInfo
CarrierIdent…
"c": "China, Shenzhen",
"d": "",
"z": "Item inbound in sorting center."
},
{
DeleteTrack
"a": "2020-04-13 17:02",
"b": null,
"c": "China, Shenzhen",
Webhook

Setting
https://api.17track.net/en/doc

"d": "",
"z": "Item accepted."
}
18/19
17/01/2022, 12:26
API docs | 17TRACK
Tracking API
 
],
"zex": {
"trN": "92612927005099010009150135",
"trC": 21051,
Develop Documen…



API endpoint
"dtD": 0,
Response status

HTTP status…

Error status …
"dtL": 1588846740000
}
}
}
}
Name
sign
event
data
Description
Data sign.
TRACKING_UPDATED
Detailed tracking information.
Parameter for…
Basic informati…

Carrier code

Country code

Package sta…

Tracking sta…

Tracking inf…

Tracking inf…

Event infor…

Important notes
 
API Reference(…
 
"dtP": 0,
Data request
 
 
"dt": 1586726160000,
"dtS": 1586726160000,
Data encapsula…

"psex": 0,
Get the API acc…

Go to dashboard

Register

Change Car…

ChangeInfo

StopTrack

Retrack

GetTrackList

GetTrackInfo

CarrierIdent…

DeleteTrack

Webhook

Setting
https://api.17track.net/en/doc
19/19