Tracking API
The V2.4 API is not backward compatible. We will keep the V1, V2.0, V2.1 and V2.2 API online.
When the v1 API is to be decommissioned in the future, we will notify you in advance by service chat group, email, and SMS. A live chat service specialist is also available (at the bottom right of the page) if you need any help.
Differences Between V2.4 and V2.2:
Optimization Items |
V2.2 |
V2.4 |
Relevant interfaces |
---|---|---|---|
Additional Fields | Always use the "param" parameter for tracking numbers and ensure carrier query requirements are pre-integrated. | When registering a tracking number, include all necessary tracking details, such as postal code or shipping date. 17TRACK will automatically use the required information according to each carrier’s needs. | /register /changeinfo /gettracklist /gettrackinfo /getRealTimeTrackInfo Webhook-UPDATE |
Support carrier official translation languages | Use "lang" to set the translation language; translations are only supported through 17TRACK’s partner services. | Set the translation language with "lang". If supported, the carrier's official description will be returned; if not, you'll get either the carrier's default language or a 17TRACK partner translation. See supported languages here |
/register /changeinfo /gettrackinfo Webhook-UPDATE |
Add "provider_tips" | Not supported. | The "provider_tips" field in webhooks or detail queries returns official carrier notifications, including explanations for tracking issues. | /gettrackinfo /getRealTimeTrackInfo Webhook-UPDATE |
Add "sync_status" | Not supported. | Through "/gettracklist" requests and responses, sync_status indicates whether tracking information was successfully synchronized from the carrier. | /gettracklist |
About
17TRACK API is a standard logistics query interface. Through the API, you can query the logistics information of 2,100 carriers supported by 17TRACK. The API is based on HTTP protocol and is compatible with various development languages. Through the Webhook mechanism, the API realizes data transfer (register and push) and automatically tracks the logistics information for the entire shipping process. For supported carriers, please see https://www.17track.net/zh-cn/carriers.
Quick Guide
- Please make sure you have registered an API account here: https://api.17track.net.
- There will be 100 free tracking quota each month.
Step 1. Create a Webhook
- Create your own webhook endpoint or get one from webhook.site for you to test on.
- Save the webhook URL in the API dashboard settings page.
- For details about creating a webhook, settings and test, see the webhook section.
Step 2. Register a Tracking Number
- Get yourself a tracking number.
- Write a script to call the API and register the number, or use test tools like postman、apifox、apipost.
- All endpoints only accept requests with a single unique API Key.
- Take bash for example, set the key as the value of 17token inside of the request header,and pass the tracking number via number parameter (A maximum of 40 tracking numbers can be passed at a single time).
curl -X POST \ --header '17token:YourKey' \ --header 'Content-Type:application/json' \ --data '[ { "number": "RR123456789CN" }, { "number: "21213123123230" } ]' \ https://api.17track.net/track/v2.4/register
- If you receive a message like below, with code being 0, and some data in the accepted field, then the registration is successful.
{ "code": 0, "data": { "accepted": [ { "origin": 1, "number": "RR123456789CN", "carrier": 3011 } ], "rejected": [ { "number": "21213123123230", "error": { "code": -18019903, "message": "Carrier cannot be detected." } } ] } }
Step 3. Listen to Your Webhook for Tracking Updates
- The tracking results will be returned within seconds after the tracking number is registered (sometime it may go over 5 minutes due to internat or carrier issue).
- If you receive something like the below, it means the push process is all green.
{ "event": "TRACKING_UPDATED", "data": { "accepted": [ { "number": "RR123456789CN", "carrier": 3011, ... ... }, ... ... // Refer to the <TRACKING_UPDATED> for full details. ] } }
Get Security Key
Log in to the dashboard and go to Settings to get a key.
Change Security Key
Click on the "Change Key" button on Settings. The new key will take effect within 5 minutes. The old one will expire once the new key takes effect.
Notes
Important Things to Know
- It is not recommended to use JavaScript on webend for data security reasons.
- The interface frequency limit is 3req/s, a 429 error code will be returned when exceeding the limit.
- All time in the response messages is in UTC format.
- All endpoints are compatible with new features in the future.
- All response data will show "Null" when there is no valid information.
- To ensure the security of data transmission, please upgrade all services involving data transfer to TLSv1.2 or higher. If you continue to use insecure protocols such as HTTP, TLSv1.0, or TLSv1.1 for access, connections will not be established.
- How Automatical tracking works:
- The tracking results will be returned within seconds after the tracking number is registered (sometime it may go over 5 minutes due to internat or carrier issue).
- Subsequent trackings will be made every 6~12 hours based on the shipping status checked last time. For delivered and exception packages, the tracking will be made every 24 hours.
- Starting from the Tracking Time, the system will stop the tracking if there is no event update from the carrier for 30 consecutive days since then.
- The system will stop the tracking if the package is delivered and stays that way for 15 consecutive days.
- The stopped tracking can be re-activate for 1 time.
- The stopped tracking will remain in your account for 90 days before it gets deleted by the system.
Tracking Quota
- The quota is only calculated when a tracking number is registered successfully.
- Each quota is associated with one tracking number. It will not be calculated if you track the same number for multiple times.
- The identity of each tracking number is determined by the tracking number itself and the carrier code it assigned with.
- In some cases, the tracking numbers were once deleted by you or by the system due to the expiration rule. If you want to re-register them to keep tracking again, the quota will be deducted.
Basic Concept and Definition
Carrier Code
You can find the code of each carrier under the "key" field in the data listed below. Use it as the value of the carrier parameter to specify a carrier.
- The carrier code list in JSON See here.
- The carrier code list in CSV See here.
- We keep adding new carriers to our support. Please visit these data regularly to stay up-to-date.
Additional parameters for tracking
Additional fields are required to track the shipments of some carriers, please refer to the following:
- The additional fields list in JSON See here;
- The additional fields list in CSV See here;
- 17TRACK will continue to update the above information based on newly added carriers and carrier inquiry requirements.
Country and Region Code
- The country and region code is in ISO 3166-1 format.
Main Status of the Shipping Process
- There are 9 main satatus, each representing a unique logistics process the package is in. The status are a enum set.
- Milestones have the same meaning as main/sub status. However, it may not always show depending on the carrier's data.
- In the v2.2 API, a status is given as a string under the lastest_status.status property. While in the v1 API, it is given as a number code under the e property.
Main Status |
Description |
---|---|
NotFound | The inquiry is made successfully but nothing can be found for this tracking number. See sub-statues for more details. |
InfoReceived | The carrier has received the order info and is about to pick up the package from the sender. |
InTransit | The package is in transit. See sub-status for more details |
Expired | The package has been in transit for a long time and not yet delivered. |
AvailableForPickup | The package has arrived at the pick up point of the destination. |
OutForDelivery | The package is out for delivery |
DeliveryFailure | The package was attempted to be delivered but not successfully failed. Please refer to the sub-status for the reason. The reasons may be: the recipient is not at home at the time of delivery, the delivery is delayed and is now rescheduled for another attempt, the recipient requests to postpone the delivery, the address is unknown and cannot be delivered, no delivery service is available due to remote areas, etc. |
Delivered | The package is delivered and signed by the recipient. |
Exception | The package may be returned, please refer to the sub-status for the reason. Reasons may be: recipient's address is wrong or unknown, recipient refuses to accept, parcel is unclaimed beyond the retention period, etc. The package may be detained by customs, common reasons for detention are: containing sensitive prohibited, restricted import and export items, unpaid taxes, etc. Parcels may suffer damage, loss, delayed delivery and other special circumstances in transit. |
Sub-status of the Shipping Status
- There are 30 sub status, each representing a specific cause or explanation to the main status. The status are a enum set.
- They are the subdivision of the main status and gives more details about what process the package is in.
- A sub status is given as a string under the latest_status.sub_status property.
Main Status | Sub-Status | Description |
---|---|---|
NotFound | NotFound_Other | The carrier didn't return any message. |
NotFound_InvalidCode | The tracking number is invalid. | |
InfoReceived | InfoReceived | No specific breakdown of meaning, same with the main status. |
InTransit | InTransit_PickedUp | The carrier has collected the package from the sender. |
InTransit_Other | Other circumstances beyond the currently known sub-statuses. | |
InTransit_Departure | Package has left the originating country/region's port. | |
InTransit_Arrival | Package has arrived at the destination country/region's port. | |
InTransit_CustomsProcessing | Your shipment is under the customs clearance process. | |
InTransit_CustomsReleased | Import/Export customs clearance is completed. | |
InTransit_CustomsRequiringInformation | Related information is required for clearance. | |
Expired | Expired_Other | No specific breakdown of meaning, same with the main status. |
AvailableForPickup | AvailableForPickup_Other | No specific breakdown of meaning, same with the main status. |
OutForDelivery | OutForDelivery_Other | No specific breakdown of meaning, same with the main status. |
DeliveryFailure | DeliveryFailure_Other | Other circumstances beyond the currently known sub-statuses. |
DeliveryFailure_NoBody | Unable to contact the recipient temporarily during the delivery process, resulting in delivery failure. | |
DeliveryFailure_Security | Package encountered security, customs clearance, or fee issues during delivery, resulting in delivery failure. | |
DeliveryFailure_Rejected | Recipient refused to accept the package for certain reasons, resulting in delivery failure. | |
DeliveryFailure_InvalidAddress | Delivery failure due to an incorrect recipient address. | |
Delivered | Delivered_Other | No specific breakdown of meaning, same with the main status. |
Exception | Exception_Other | Other circumstances beyond the currently known sub-statuses. |
Exception_Returning | Package is being returned to the sender. | |
Exception_Returned | Sender has successfully received the returned package. | |
Exception_NoBody | Cannot find the receipient due to the abnormal recipient information discovered before delivery | |
Exception_Security | Abnormalities found before delivery, including security, customs clearance, or fee issues. | |
Exception_Damage | The pacakge was found damaged during the transportation process. | |
Exception_Rejected | Recipient refused to accept the package before delivery. | |
Exception_Delayed | Possible delay beyond the original scheduled transit time due to various circumstances. | |
Exception_Lost | Package lost due to various circumstances. | |
Exception_Destroyed | Package unable to be delivered for various reasons and subsequently destroyed. | |
Exception_Cancel | Shipment order was cancelled due to various circumstances. |
Translating Language Codes
The code used to translate logistic events, please refer to the Register tracking number and Change Registration Info interface descriptions.
1.The logistics event descriptions of the following carriers are officially supported in multiple languages:
- "Official Multilingual Support List for Carriers"
- 17TRACK will continue to update the above information based on the addition of new carriers and the support for carrier languages.
2.If the carrier’s official language isn’t available, you can use 17TRACK’s third-party translation. Supported languages:
Language |
Code |
---|---|
English | en |
Japanese | ja |
French | fr |
Danish | da |
Thai | th |
German | de |
Spanish | es |
Simplified Chinese | zh-hans |
Traditional Chinese | zh-hant |
Arabic | ar |
Bulgarian | bg |
Czech | cs |
Greek | el |
Estonian | et |
Finnish | fi |
Hebrew | he |
Hungarian | hu |
Italian | it |
Korean | ko |
Latvian | lv |
Dutch | nl |
Norwegian | no |
Polish | pl |
Portuguese | pt |
Romanian | ro |
Russian | ru |
Slovak | sk |
Slovenian | sl |
Swedish | sv |
Turkish | tr |
Ukrainian | uk |
Vietnamese | vi |
How to get the pickup time
- The pickup time is available in the "pickup_time" field of the /gettracklist API. If this field is empty, it means that the carrier's event description is incomplete and the information is unavailable.
How to get delivery time
- Iterate through tracking.providers[].events[]. If sub_status == "Delivered_Other", then the content of time_raw represents the delivery time.
API Usage
About General Request
- Use http POST method to submit requests for all endpoints.
- All requests and responses are in UTF-8 encoded JSON format.
- Frequently used parameters:
- Tracking Number (number): must be a combination of 5 to 50 consecutive letters, numbers and/or hyphen.
- Carrier Code (carrier): must be on the List of Carrier Code.
- For other parameters, please see the description of for endpoint.
- Request URL:https://api.17track.net/track/v2.4
- Request Head(Required)
- 17token: Security Key.
- Content-Type: application/json.
- Request Body(Required)
- Serialized JSON content. For Google Apps Script, use payload as the request body.
Example Request
curl -X POST \
--header '17token:SecurityKey' \
--header 'Content-Type:application/json' \
--data '[{"number":"RR123456789CN", "carrier":3011}]' \
https://api.17track.net/track/v2.4/interfaceName
Response
Example Response 1. This syntax will show when illegal parameters are passed in.
{
"code": 0,
"data": {
"errors": [
{
"code": -18010013,
"message": "Submitted data is invalid."
}
]
}
}
The response results are in a uniform data encapsulation format, as described below:
Property | Description |
---|---|
code | The HTTP Status code and error code. |
data | The response data. |
-errors | |
--code | The HTTP Status code and error code. |
--message | Error description. |
Example Response 2
{
"code": 0,
"data": {
"accepted": [],
"rejected": []
}
}
The response results are in a uniform data encapsulation format, as described below:
Property | Description |
---|---|
code | The HTTP Status code and error code. |
data | The response data. |
- accepted | The response of the successfully processed part of the request. |
- rejected | The response of the unsuccessfully processed part of the request. |
List of HTTP Status Code
Code | Description |
---|---|
200 | The request is processed successfully. You can see the result in the returned data. |
401 | Unauthorized request, incorrect security key, IP not in the whitelist, or account disabled. |
404 | Incorrect request URL. |
429 | Request frequency exceeds governing threshold. |
500 | Server error. |
503 | Service temporarily suspended. |
List of Error Codes
An error code is a more specific status based on the response status code:
Code | Description |
---|---|
0 | Success |
-18010001 | Your IP is not in the whitelist. You can set it in the dashboard. |
-18010002 | Invalid security key. |
-18010003 | Internal service error. Please try again later. |
-18010004 | The account is disabled. |
-18010005 | Unauthorized access. |
-18010010 | Please provide the data {0}. |
-18010011 | The value of data {0} is invalid. |
-18010012 | The format of the data {0} is invalid. |
-18010013 | Invalid submitted data. |
-18010014 | Tracking numbers exceed limit. |
-18010015 | The value {0} of the field {1} is invalid. |
-18010016 | Last-mile carrier can only be set for postal services. |
-18010018 | The '{1}' field is required for this tracking. Please provide Alpha-2 country code and postal code. Example: '{0}'. |
-18010019 | The '{1}' field is required for this tracking. Please provide postal code. Example: '{0}'. |
-18010020 | The '{1}' field is required for this tracking. Please provide phone number. Example: '{0}'. |
-18010022 | Additional information is needed to continue tracking your package. Example: '2024-01-01'. |
-18010201 | Webhook URL is required. |
-18010202 | Incorrect URL format of 'Webhook'. |
-18010203 | WebHook test failed, Http status code: {0}. |
-18010204 | Webhook URL not set, can't push data. |
-18010205 | Incorrect IP format. |
-18010206 | Push failed. |
-18019901 | Tracking number {0} is already registered. |
-18019902 | Tracking number {0} is not registered yet. Please register first. |
-18019903 | The carrier can not be detected, please visit https://res.17track.net/asset/carrier/info/apicarrier.all.json for the carrier code and send in as the parameter. |
-18019904 | Only stopped numbers can be re-tracked. |
-18019905 | Each tracking number can only be re-tracked once. |
-18019906 | Only numbers being tracked can be stopped. |
-18019907 | Tracking amount exceeds your daily limit. |
-18019908 | Your quotas have ran out. |
-18019909 | No tracking info at the moment. |
-18019910 | Carrier Code {0} is incorrect. |
-18019911 | The tracking number of this carrier can not be registered at the moment. |
-18019801 | The tracking number is registered with multiple carriers. Please specify which tracking number you want to change the carrier code for by specifying the carrier_old parameter. |
-18019802 | The parameter carrier_new {0} is incorrect. |
-18019803 | The Carrier Code to be changed can not be the same of the current one. |
-18019804 | The Carrier Code to be changed must be specified to carrier_new or final_carrier_new. |
-18019805 | The tracking number {1} for the specified carrier {0} is not registered, or the existing carrier parameter carrier_old is incorrect. |
-18019806 | Carrier can not be changed for stopped numbers. Please retrack the number before changing the carrier. |
-18019807 | The times for changing carrier exceed limit. |
-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 | The data need to be changed is not valid. |
-18019818 | The carrier is not supported in the real-time tracking interface. |
-18019817 | System error; the charge for this request was not processed. |
-18019816 | The carrier interface encountered an error, and no tracking results were retrieved. |
-18019815 | The carrier interface response timed out. |
-18019912 | Unauthorized account access to the real-time tracking interface. |
Register tracking number - POST https://api.17track.net/track/v2.4/register
- The endpoint receives 40 numbers at most at a single time.
- The tracking results will be returned within seconds after the tracking number is registered (sometime it may go over 5 minutes due to internat or carrier issue).
- About 400,000 tracking numbers can be registered in an hour.
- Pass in the translation language code to be translated after the logistics event has changed and is not empty.
Example Request
curl -X POST \
--header '17token:your secret key' \
--header 'Content-Type:application/json' \
--data '[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "1234"
}
]' \
https://api.17track.net/track/v2.4/register
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.17track.net/track/v2.4/register",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS =>"[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "1234"
}
]",
CURLOPT_HTTPHEADER => [
"17token: your secret key",
"content-type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.17track.net/track/v2.4/register"),
Headers =
{
{ "17token", "your secret key" },
},
Content = new StringContent("[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "1234"
}
]")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
String value = "[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "1234"
}
]";
RequestBody body = RequestBody.create(mediaType, value);
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/register")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("17token", "your secret key")
.build();
Response response = client.newCall(request).execute();
response.body();
const axios = require("axios");
const options = {
method: 'POST',
url: 'https://api.17track.net/track/v2.4/register',
headers: {
'content-type': 'application/json',
'17token': 'your secret key',
},
data: '[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "1234"
}
]'
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
import requests
url = "https://api.17track.net/track/v2.4/register"
payload = [
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "1234"
}
]
headers = {
"content-type": "application/json",
"17token": "your secret key"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Request Parameter:
Parameter | Required |
Type |
Description |
---|---|---|---|
number | Yes | String | The tracking number you want to register. It must conform to the tracking number format. |
lang | No | String | Used to translate logistics events, specify the translation language code. |
translation_mode | No | Enum. | 1.This parameter is not effective when the carrier officially supports the specified language (lang). 2. When the specified language (lang) is not officially supported by the carrier, the translation_mode provided by the user will be applied: -"Denied":Response failed. -"UseDefaultLang":Use carrier default language. Response successful.[Default] -"UseThirdPartyServices":Use a third-party translation service; if the third-party service is not supported, use the carrier's default language. Response successful. Note: When the "UseThirdPartyServices" option is selected and description_translation has a value, each tracking number for each language (lang) will consume one quota upon the first successful translation. |
No | String | User email, no more than 250 characters. After the email notifications feature is activated, we'll notify users via this email when package status changes. | |
order_no | No | String | Must be a combination of 5 to 50 characters including letters, numbers, or dashes. |
order_time | No | DateTime | order placed time, use it to calculate the Scanned performance, e.g: 2023/1/1. |
carrier | No | Int. | 1. Pass in the Carrier Code if you want to specify a carrier for the tracking number. 2. The tracking numbers of most UPU and commercial carriers can be auto-identified by our system. If you do not pass in or pass in the wrong carrier code, the system will match the most possible carrier and return its Carrier Code. 3. If you receive a -18019903 error when you do not pass in a code, it means the system can not find a matched carrier at all. You will need to register the number again with a Carrier Code. |
final_carrier | No | Int. | Carrier Code of the last-mile carrier. (Only for UPU numbers) |
auto_detection | No | Boolean | Turn on and off the carrier auto detection, true by default. This does not always guarantee an accurate result if at all. The parameter will be ignored if a carrier parameter is passed in. |
origin_country | No | String | Origin country. Use the two-letter country code in ISO 3166-1 format. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
ship_date | No | DateTime | Shipping date in YYYY/MM/DD format. The Additional Field required by some carriers to retrieve the tracking info. |
destination_postal_code | No | String | The postal of the destination address. The Additional Field required by some carriers to retrieve the tracking info. |
destination_country | No | String | Destination country. The Additional Field required by some carriers to retrieve the tracking info. |
destination_city | No | String | Destination city. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
shipper | No | String | Shipper name. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
consignee | No | String | Consignee name. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
phone_number_last_4 | No | String | The last digits of the shipper's or recipient's phone number. The Additional Field required by some carriers to retrieve the tracking info. |
phone_number | No | String | The shipper's or recipient's phone number.The Additional Field required by some carriers to retrieve the tracking info. |
cpf_or_cnpj | No | String | Individual Taxpayer Registry(CPF)/National Registry of Legal Entities(CNPJ). The Additional Field required by some carriers to retrieve the tracking info. |
special_tracking_info | No | Object | This parameter format is an object, each consisting of "number_type" and "parameter". "number_type" represents different query channels provided by the carrier, and "parameter" is the corresponding value for that query channel. |
-number_type | No | String | Available channels for checking logistics information provided by carriers. The Additional Field required by some carriers to retrieve the tracking info. |
-parameter | No | String | The value of the query channel. The Additional Field required by some carriers to retrieve the tracking info. |
tag | No | String | A tag you can note anything down with no more than 100 characters. You can use it to add additional info, categorize your numbers, etc. |
remark | No | String | No more than 1,000 characters, you can use it to describe the current package status. |
Example Response
{
"code": 0,
"data": {
"accepted": [
{
"origin": 1,
"number": "RR123456789CN",
"carrier": 3011,
"email": null,
"lang": null
}
],
"rejected": [
{
"number": "1234",
"carrier":0,
"error": {
"code": -18010012,
"message": "The format of '1234' is invalid."
}
}
]
}
}
Response Explanation:
Property | Type |
Description |
---|---|---|
code | Int. | The HTTP Status code and error code. |
data | Object | The response data. |
-accepted | Array | Tracking number registered and its carrier code will be returned. If the carrier code sent in was invalid or belongs to another carrier, the system will correct it and returned the right one. |
--number | String | The tracking number registered. |
--tag | String | Custom tag. See tracking number registration for more info. |
--carrier | Int. | Carrier Code. |
String | ||
--lang | String | Translating Language Code |
--origin | Int. | This shows a number code representing how the carrier code is provided: If it shows 1: A confidant result given by the system including auto-detection or the correction by the system based on the code passed in. If it shows 2. The carrier code is passed in which is also found correct by the system. If it shows 3. The carrier code is not passed in, and a guess was provided by the system, may not always be correct. |
-rejected | Array | This shows the tracking numbers failed to be registered, with an error code and a message explaning the cause. |
--number | String | The tracking number must conform to the tracking number format. |
--carrier | Int. | Carrier Code. |
--error | Object | |
---code | Int. | Error code. |
---message | String | Error description. |
Change Carrier - POST https://api.17track.net/track/v2.4/changecarrier
- The endpoint receives a maximum of 40 tracking numbers at a single time.
- You can reassign a carrier for a tracking number by passing in the new carrier code and the old carrier code that needs to be replaced.
- You can change the carrier ofr a tracking for 5 times at most.
Example Request
curl -X POST \
--header '17token:your secret key' \
--header 'Content-Type:application/json' \
--data '[
{
"number": "RR123456789CN",
"carrier_old": 3013,
"carrier_new": 3011
},
{
"number": "21213123123230",
"carrier_old": 3011,
"carrier_new": 21051,
}
]' \
https://api.17track.net/track/v2.4/changecarrier
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.17track.net/track/v2.4/changecarrier",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "[
{
"number": "RR123456789CN",
"carrier_old": 3013,
"carrier_new": 3011
},
{
"number": "21213123123230",
"carrier_old": 3011,
"carrier_new": 21051,
}
]",
CURLOPT_HTTPHEADER => [
"17token: your secret key",
"content-type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.17track.net/track/v2.4/changecarrier"),
Headers =
{
{ "17token", "your secret key" },
},
Content = new StringContent("[
{
"number": "RR123456789CN",
"carrier_old": 3013,
"carrier_new": 3011
},
{
"number": "21213123123230",
"carrier_old": 3011,
"carrier_new": 21051,
}
]")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
String value = "[
{
"number": "RR123456789CN",
"carrier_old": 3013,
"carrier_new": 3011
},
{
"number": "21213123123230",
"carrier_old": 3011,
"carrier_new": 21051,
}
]";
RequestBody body = RequestBody.create(mediaType, value);
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/changecarrier")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("17token", "your secret key")
.build();
Response response = client.newCall(request).execute();
response.body();
const axios = require("axios");
const options = {
method: 'POST',
url: 'https://api.17track.net/track/v2.4/changecarrier',
headers: {
'content-type': 'application/json',
'17token': 'your secret key'
},
data: '[
{
"number": "RR123456789CN",
"carrier_old": 3013,
"carrier_new": 3011
},
{
"number": "21213123123230",
"carrier_old": 3011,
"carrier_new": 21051,
}
]'
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
import requests
url = "https://api.17track.net/track/v2.4/changecarrier"
payload = [
{
"number": "RR123456789CN",
"carrier_old": 3013,
"carrier_new": 3011
},
{
"number": "21213123123230",
"carrier_old": 3011,
"carrier_new": 21051,
}
]
headers = {
"content-type": "application/json",
"17token": "your secret key"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Parameter Explanation:
Parameter | Required |
Type |
Description |
---|---|---|---|
number | Yes | String | The tracking number you want to change the carrier for. It must conform to the Tracking Number Format. |
carrier_old | No | Int. | The old Carrier Code that needs to be replaced. If you have assigned multiple carriers to a single tracking number, it helps specify which one of them you want to change. You can ignore this parameter if only one carrier is assiged to the tracking number. |
carrier_new | Yes | Int. | The new Carrier Code that needs to be changed into. |
final_carrier_old | No | Int. | The old last-mile Carrier Code that needs to be replaced. Only available for UPU carriers. |
final_carrier_new | Yes | Int. | The new last-mile Carrier Code that needs to be changed into. Only available for UPU carriers. |
Example Response
{
"code": 0,
"data": {
"accepted": [
{
"number": "RR123456789CN",
"carrier": 3011,
"final_carrier": 0
}
],
"rejected": [
{
"carrier": 0,
"number": "21213123123230",
"error": {
"code": -18019809,
"message": "The registration information of the carrier with tracking number 'Usa' already exists and cannot be changed to a duplicate registration information."
}
}
]
}
}
Response Explanation:
Item | Description |
---|---|
code | The HTTP Status code and error code. |
data | The response data. |
-accepted | This shows the tracking number whose carrier has been changed successfully. The new carrier code will be returned as well. |
-rejected | This shows the tracking numbers failed to be processed. An error code will be returned. |
--number | Tracking number. |
--carrier | Carrier Code. |
--error | Error message collection |
---code | Error code. |
---message | Error description. |
Change Registration Info - POST https://api.17track.net/track/v2.4/changeinfo
- The endpoint receives a maximum of 40 tracking numbers at a single time.
- Use this endpoint to change the attached info of a tracking number.
Example Request
curl -X POST \
--header '17token:your secret key' \
--header 'Content-Type:application/json' \
--data '[
{
"number": "RR123456789CN",
"carrier": 3011,
"items": {
"lang": "en",
"tag": "This is my order id."
}
},
{
"number": "21213123123230",
"carrier": 11031,
"items": {
"tag":"This is my order id."
}
}
]' \
https://api.17track.net/track/v2.4/changeinfo
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.17track.net/track/v2.4/changeinfo",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "[
{
"number": "RR123456789CN",
"carrier": 3011,
"items": {
"lang": "en",
"tag": "This is my order id."
}
},
{
"number": "21213123123230",
"carrier": 11031,
"items": {
"tag":"This is my order id."
}
}
]",
CURLOPT_HTTPHEADER => [
"17token: your secret key",
"content-type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.17track.net/track/v2.4/changeinfo"),
Headers =
{
{ "17token", "your secret key" },
},
Content = new StringContent("[
{
"number": "RR123456789CN",
"carrier": 3011,
"items": {
"lang": "en",
"tag": "This is my order id."
}
},
{
"number": "21213123123230",
"carrier": 11031,
"items": {
"tag":"This is my order id."
}
}
]")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
String value = "[
{
"number": "RR123456789CN",
"carrier": 3011,
"items": {
"lang": "en",
"tag": "This is my order id."
}
},
{
"number": "21213123123230",
"carrier": 11031,
"items": {
"tag":"This is my order id."
}
}
]";
RequestBody body = RequestBody.create(mediaType, value);
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/changeinfo")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("17token", "your secret key")
.build();
Response response = client.newCall(request).execute();
response.body();
const axios = require("axios");
const options = {
method: 'POST',
url: 'https://api.17track.net/track/v2.4/changeinfo',
headers: {
'content-type': 'application/json',
'17token': 'your secret key'
},
data: '[
{
"number": "RR123456789CN",
"carrier": 3011,
"items": {
"lang": "en",
"tag": "This is my order id."
}
},
{
"number": "21213123123230",
"carrier": 11031,
"items": {
"tag":"This is my order id."
}
}
]'
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
import requests
url = "https://api.17track.net/track/v2.4/changeinfo"
payload = [
{
"number": "RR123456789CN",
"carrier": 3011,
"items": {
"lang": "en",
"tag": "This is my order id."
}
},
{
"number": "21213123123230",
"carrier": 11031,
"items": {
"tag":"This is my order id."
}
}
]
headers = {
"content-type": "application/json",
"17token": "your secret key"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Parameter Explanation:
Parameter | Required |
Type |
Description |
---|---|---|---|
number | Yes | String | The tracking number must conform to the tracking number format. |
carrier | No | Int. | The Carrier Code of the tracking number. |
items | Yes | Object | The set of data that needs to be changed, only "tag" can be changed for now, other parameter will be ignored. |
--tag | No | String | Custom tag. See tracking number registration for more info. |
--origin_country | No | String | Origin country. Use the two-letter country code in ISO 3166-1 format. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
--ship_date | No | DateTime | Shipping date in YYYY/MM/DD format. The Additional Field required by some carriers to retrieve the tracking info. |
--destination_postal_code | No | String | The postal of the destination address. The Additional Field required by some carriers to retrieve the tracking info. |
--destination_country | No | String | Destination country. The Additional Field required by some carriers to retrieve the tracking info. |
--destination_city | No | String | Destination city. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
--shipper | No | String | Shipper name. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
--consignee | No | String | Consignee name. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
--phone_number_last_4 | No | String | The last digits of the shipper's or recipient's phone number. The Additional Field required by some carriers to retrieve the tracking info. |
--phone_number | No | String | The shipper's or recipient's phone number.The Additional Field required by some carriers to retrieve the tracking info. |
--cpf_or_cnpj | No | String | Individual Taxpayer Registry(CPF)/National Registry of Legal Entities(CNPJ). The Additional Field required by some carriers to retrieve the tracking info. |
--special_tracking_info | No | Object | This parameter format is an object, each consisting of "number_type" and "parameter". "number_type" represents different query channels provided by the carrier, and "parameter" is the corresponding value for that query channel. |
---number_type | No | String | Available channels for checking logistics information provided by carriers. The Additional Field required by some carriers to retrieve the tracking info. |
---parameter | No | String | The value of the query channel. The Additional Field required by some carriers to retrieve the tracking info. |
--lang | No | String | Used to translate logistics events, specify the translation language code. |
--translation_mode | No | Enum. | 1.This parameter is not effective when the carrier officially supports the specified language (lang). 2. When the specified language (lang) is not officially supported by the carrier, the translation_mode provided by the user will be applied: -"Denied":Response failed. -"UseDefaultLang":Use carrier default language. Response successful.[Default] -"UseThirdPartyServices":Use a third-party translation service; if the third-party service is not supported, use the carrier's default language. Response successful. Note: When the "UseThirdPartyServices" option is selected and description_translation has a value, each tracking number for each language (lang) will consume one quota upon the first successful translation. |
Example Response
{
"code": 0,
"data": {
"accepted": [
{
"number": "RR123456789CN",
"carrier": 3011
}
],
"rejected": [
{
"carrier": 3011,
"number": "21213123123230",
"error": {
"code": -18019902,
"message": "The tracking number '21213123123230' does not register, please register first."
}
}
]
}
}
Response Explanation:
Item | Description |
---|---|
code | The HTTP Status code and error code. |
data | The response data. |
-accepted | The data that has been received and processed successfully. The latest Carrier Code will be returned. |
-rejected | The data failed to be processed. An error code will be returned. |
--number | Tracking number. |
--carrier | Carrier Code. |
--error | Error message collection |
---code | Error code. |
---message | Error description. |
Stop Tracking - POST https://api.17track.net/track/v2.4/stoptrack
- The endpoint receives a maximum of 40 tracking numbers at a single time.
- Use this to stop the tracking of a tracking number.
- This operation is the opposite of retrack.
Example Request
curl -X POST \
--header '17token:your secret key' \
--header 'Content-Type:application/json' \
--data '[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]' \
https://api.17track.net/track/v2.4/stoptrack
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.17track.net/track/v2.4/stoptrack",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]",
CURLOPT_HTTPHEADER => [
"17token: your secret key",
"content-type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.17track.net/track/v2.4/stoptrack"),
Headers =
{
{ "17token", "your secret key" },
},
Content = new StringContent("[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
String value = "[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]";
RequestBody body = RequestBody.create(mediaType, value);
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/stoptrack")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("17token", "your secret key")
.build();
Response response = client.newCall(request).execute();
response.body();
const axios = require("axios");
const options = {
method: 'POST',
url: 'https://api.17track.net/track/v2.4/stoptrack',
headers: {
'content-type': 'application/json',
'17token': 'your secret key'
},
data: '[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]'
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
import requests
url = "https://api.17track.net/track/v2.4/stoptrack"
payload = [
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]
headers = {
"content-type": "application/json",
"17token": "your secret key"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Parameter Explanation:
Parameter | Required |
Type |
Description |
---|---|---|---|
number | Yes | String | The tracking number must conform to the tracking number format. |
carrier | No | Int. | Carrier Code. If not passed in and if the tracking number can be matched to multiple carriers, it will be processed for multiple times for each carrier matched. |
Example Response
{
"code": 0,
"data": {
"accepted": [
{
"number": "RR123456789CN",
"carrier": 3011
}
],
"rejected": [
{
"carrier": 0,
"number": "21213123123230",
"error": {
"code": -18019902,
"message": "The tracking number '21213123123230' does not register, please register first."
}
}
]
}
}
Response Explanation:
Item | Description |
---|---|
code | The HTTP Status code and error code. |
data | The response data. |
-accepted | This shows the data that has been received and processed successfully. |
-rejected | This shows the tracking numbers failed to be processed. An error code will be returned. |
--number | Tracking number. |
--carrier | Carrier Code. |
--error | Error message collection |
---code | Error code. |
---message | Error description. |
Retrack a stopped tracking number - POST https://api.17track.net/track/v2.4/retrack
- The endpoint receives a maximum of 40 tracking numbers at a single time.
- Restart the automatic tracking for a tracking number that has been stopped.
- This operation is the opposite of the stoptrack endpoint.
- Every tracking number can only be restarted for once.
Example Request
curl -X POST \
--header '17token:SecurityKey' \
--header 'Content-Type:application/json' \
--data '[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]' \
https://api.17track.net/track/v2.4/retrack
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.17track.net/track/v2.4/retrack",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]",
CURLOPT_HTTPHEADER => [
"17token: your secret key",
"content-type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.17track.net/track/v2.4/retrack"),
Headers =
{
{ "17token", "your secret key" },
},
Content = new StringContent("[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
String value = "[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]";
RequestBody body = RequestBody.create(mediaType, value);
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/retrack")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("17token", "your secret key")
.build();
Response response = client.newCall(request).execute();
response.body();
const axios = require("axios");
const options = {
method: 'POST',
url: 'https://api.17track.net/track/v2.4/retrack',
headers: {
'content-type': 'application/json',
'17token': 'your secret key'
},
data: '[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]'
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
import requests
url = "https://api.17track.net/track/v2.4/retrack"
payload = [
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]
headers = {
"content-type": "application/json",
"17token": "your secret key"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Parameter Explanation:
Parameter | Required |
Type |
Description |
---|---|---|---|
number | Yes | String | The tracking number must conform to the tracking number format. |
carrier | No | Int. | Carrier Code. If not passed in and if the tracking number can be matched to multiple carriers, it will be processed for multiple times for each carrier matched. |
Example Response
{
"code": 0,
"data": {
"accepted": [
{
"number": "RR123456789CN",
"carrier": 3011
}
],
"rejected": [
{
"carrier": 0,
"number": "21213123123230",
"error": {
"code": -18019904,
"message": "Retrack is not allowed. You can only retrack stopped number."
}
}
]
}
}
Response Explanation:
Item |
Description |
---|---|
code | The HTTP Status code and error code. |
data | The response data. |
-accepted | This shows the data that has been received and processed successfully. |
-rejected | This shows the tracking numbers failed to be processed. An error code will be returned. |
--number | Tracking number. |
--carrier | Carrier Code. |
--error | Error message collection |
---code | Error code. |
---message | Error description. |
Delete a tracking number - POST https://api.17track.net/track/v2.4/deletetrack
- The endpoint receives a maximum of 40 tracking numbers at a single time.
- The delete action can not be undone.
Example Request
curl -X POST \
--header '17token:your secret key' \
--header 'Content-Type:application/json' \
--data '[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]' \
https://api.17track.net/track/v2.4/deletetrack
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.17track.net/track/v2.4/deletetrack",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]",
CURLOPT_HTTPHEADER => [
"17token: your secret key",
"content-type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.17track.net/track/v2.4/deletetrack"),
Headers =
{
{ "17token", "your secret key" },
},
Content = new StringContent("[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
String value = "[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]";
RequestBody body = RequestBody.create(mediaType, value);
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/deletetrack")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("17token", "your secret key")
.build();
Response response = client.newCall(request).execute();
response.body();
const axios = require("axios");
const options = {
method: 'POST',
url: 'https://api.17track.net/track/v2.4/deletetrack',
headers: {
'content-type': 'application/json',
'17token': 'your secret key'
},
data: '[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]'
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
import requests
url = "https://api.17track.net/track/v2.4/deletetrack"
payload = [
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]
headers = {
"content-type": "application/json",
"17token": "your secret key"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Parameter Explanation:
Parameter | Required |
Type |
Description |
---|---|---|---|
number | Yes | String | Tracking number must conform to the tracking number format. |
carrier | No | Int. | Carrier Code. If not passed in and if the tracking number can be matched to multiple carriers, it will be processed for multiple times for each carrier matched. |
Example Response
{
"code": 0,
"data": {
"accepted": [
{
"number": "RR123456789CN",
"carrier": 3011
}
],
"rejected": [
{
"carrier": 0,
"number": "21213123123230",
"error": {
"code": -18019902,
"message": "The tracking number '21213123123230' does not register, please register first."
}
}
]
}
}
Response Explanation:
Item | Description |
---|---|
code | The HTTP Status code and error code. |
data | The response data. |
-accepted | This shows the data that has been received and processed successfully. |
-rejected | This shows the tracking numbers failed to be processed. An error code will be returned. |
--number | Tracking number. |
--carrier | Carrier Code. |
--error | Error message collection |
---code | Error code. |
---message | Error description. |
Get the quota info - POST https://api.17track.net/track/v2.4/getquota
- You can use this endpoint to see the status of your quota. No parameter is needed.
Example Request
curl -X POST \
--header '17token:your secret key' \
--header 'Content-Type:application/json' \
https://api.17track.net/track/v2.4/getquota
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.17track.net/track/v2.4/getquota",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "[]",
CURLOPT_HTTPHEADER => [
"17token: your secret key",
"content-type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.17track.net/track/v2.4/getquota"),
Headers =
{
{ "17token", "your secret key" },
},
Content = new StringContent("[]")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
String value = "[]";
RequestBody body = RequestBody.create(mediaType, value);
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/getquota")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("17token", "your secret key")
.build();
Response response = client.newCall(request).execute();
response.body();
const axios = require("axios");
const options = {
method: 'POST',
url: 'https://api.17track.net/track/v2.4/getquota',
headers: {
'content-type': 'application/json',
'17token': 'your secret key'
},
data: '[]'
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
import requests
url = "https://api.17track.net/track/v2.4/getquota"
payload = []
headers = {
"content-type": "application/json",
"17token": "your secret key"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Example Response
{ "code": 0, "data": { "quota_total": 1100, "quota_used": 2, "quota_remain": 1098, "today_used": 0, "max_track_daily": 10000000, "free_email_quota": 300, "free_email_quotaused": 0 } }
Response Explanation:
Item | Type |
Description |
---|---|---|
code | Int. | The HTTP Status code and error code. |
data | Object | The response data. |
-quota_total | Int. | Current quota in total. |
-quota_used | Int. | Current quota used. |
-quota_remain | Int. | How many usable quota left. |
-max_track_daily | Int. | The daily quota limit set by you, with 0 meaning no limit. |
-free_email_quota | Int. | Free email quota. |
-free_email_quotaused | Int. | Email quota consumed. |
Search Tracking Info by Condition - POST https://api.17track.net/track/v2.4/gettracklist
- Use this endpoint to search tracking info and get returned data in 1 page with 40 messages at most.
- The parameters for this endpoint are mainly used as the filter condition for the search.
- This endpoint does not initiate any tracking action. It retrive info from the tracking data of the registered number.
Excample Request
curl -X POST \
--header '17token:your secret key' \
--header 'Content-Type:application/json' \
--data '{
"number": "RR123456789CN,RR111111111CN",
"carrier": 3011,
"data_origin":"Api",
"register_time_from": "2019-01-01",
"register_time_to": "2019-02-01",
"track_time_from": "2019-01-01",
"track_time_to": "2019-12-01",
"push_time_from": "2019-01-01",
"push_time_to": "2019-12-01",
"push_status": "Success",
"stop_track_time_from": "2019-01-01",
"stop_track_time_to": "2019-12-01",
"package_status": "NotFound",
"tracking_status": "Tracking",
"page_no": 1,
"order_by": "PushTimeAsc",
}' \
https://api.17track.net/track/v2.4/gettracklist
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.17track.net/track/v2.4/gettracklist",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS =>'{
"number": "RR123456789CN,RR111111111CN",
"carrier": 3011,
"data_origin":"Api",
"register_time_from": "2019-01-01",
"register_time_to": "2019-02-01",
"track_time_from": "2019-01-01",
"track_time_to": "2019-12-01",
"push_time_from": "2019-01-01",
"push_time_to": "2019-12-01",
"push_status": "Success",
"stop_track_time_from": "2019-01-01",
"stop_track_time_to": "2019-12-01",
"package_status": "NotFound",
"tracking_status": "Tracking",
"page_no": 1,
"order_by": "PushTimeAsc"
}',
CURLOPT_HTTPHEADER => [
"17token: your secret key",
"content-type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.17track.net/track/v2.4/gettracklist"),
Headers =
{
{ "17token", "your secret key" },
},
Content = new StringContent("{
"number": "RR123456789CN,RR111111111CN",
"carrier": 3011,
"data_origin":"Api",
"register_time_from": "2019-01-01",
"register_time_to": "2019-02-01",
"track_time_from": "2019-01-01",
"track_time_to": "2019-12-01",
"push_time_from": "2019-01-01",
"push_time_to": "2019-12-01",
"push_status": "Success",
"stop_track_time_from": "2019-01-01",
"stop_track_time_to": "2019-12-01",
"package_status": "NotFound",
"tracking_status": "Tracking",
"page_no": 1,
"order_by": "PushTimeAsc"
}")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
String value = "{
"number": "RR123456789CN,RR111111111CN",
"carrier": 3011,
"data_origin":"Api",
"register_time_from": "2019-01-01",
"register_time_to": "2019-02-01",
"track_time_from": "2019-01-01",
"track_time_to": "2019-12-01",
"push_time_from": "2019-01-01",
"push_time_to": "2019-12-01",
"push_status": "Success",
"stop_track_time_from": "2019-01-01",
"stop_track_time_to": "2019-12-01",
"package_status": "NotFound",
"tracking_status": "Tracking",
"page_no": 1,
"order_by": "PushTimeAsc"
}";
RequestBody body = RequestBody.create(mediaType, value);
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/gettracklist")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("17token", "your secret key")
.build();
Response response = client.newCall(request).execute();
response.body();
const axios = require("axios");
const options = {
method: 'POST',
url: 'https://api.17track.net/track/v2.4/gettracklist',
headers: {
'content-type': 'application/json',
'17token': 'your secret key'
},
data: JSON.stringify({
"number": "RR123456789CN,RR111111111CN",
"carrier": 3011,
"data_origin": "Api",
"register_time_from": "2019-01-01",
"register_time_to": "2019-02-01",
"track_time_from": "2019-01-01",
"track_time_to": "2019-12-01",
"push_time_from": "2019-01-01",
"push_time_to": "2019-12-01",
"push_status": "Success",
"stop_track_time_from": "2019-01-01",
"stop_track_time_to": "2019-12-01",
"package_status": "NotFound",
"tracking_status": "Tracking",
"page_no": 1,
"order_by": "PushTimeAsc"
});
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
import requests
url = "https://api.17track.net/track/v2.4/gettracklist"
payload = {
"number": "RR123456789CN,RR111111111CN",
"carrier": 3011,
"data_origin": "Api",
"register_time_from": "2019-01-01",
"register_time_to": "2019-02-01",
"track_time_from": "2019-01-01",
"track_time_to": "2019-12-01",
"push_time_from": "2019-01-01",
"push_time_to": "2019-12-01",
"push_status": "Success",
"stop_track_time_from": "2019-01-01",
"stop_track_time_to": "2019-12-01",
"package_status": "NotFound",
"tracking_status": "Tracking",
"page_no": 1,
"order_by": "PushTimeAsc"
}
headers = {
"content-type": "application/json",
"17token": "your secret key"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Parameter Explanation:
Parameter | Required |
Type |
Description |
---|---|---|---|
number | No | String | Tracking Number, pass in more than 1 number will ger more precise filters, 200 numbers at most(separated by comma). Each number must conform to the tracking number format. |
carrier | No | Int. | See Carrier Code. |
data_origin | No | Enum. | Upload Source. "Api" "Manual" "Import" |
package_status | No | Int. | See Package status. |
register_time_from | No | DateTime | The range of time of registration starts at. |
register_time_to | No | DateTime | The range of time of registration ends at. |
tracking_status | No | Enum. | "Tracking" "Stopped" |
sync_status | No | Boolean | Sync status:The latest status of data synchronization true:Sync successful false:Sync Failed |
track_time_from | No | DateTime | The range of time of tracking starts at. |
track_time_to | No | DateTime | The range of time of tracking ends at. |
push_time_from | No | DateTime | The range of time of push starts at. |
push_time_to | No | DateTime | The range of time of push ends at. |
push_status | No | Enum. | "NotPushed" "Success" "Failure" |
push_status_code | No | The HTTP Status code. | |
stop_track_time_from | No | DateTime | The range of time of stopped tracking starts at. |
stop_track_time_to | No | DateTime | The range of time of stopped tracking Ends at. |
page_no | No | Int. | Page Number. |
order_by | No | Enum. | Show in the oreder of: "RegisterTimeAsc" "RegisterTimeDesc" "PushTimeAsc" "PushTimeDesc" "TrackTimeAsc" "TrackTimeDesc" |
Example Request
{
"page": {
"data_total": 43,
"page_total": 2,
"page_no": 1,
"page_size": 40
},
"code": 0,
"data": {
"accepted": [
{
"number": "RR123456789CN",
"param": null,
"param_type": "None",
"data_origin": "Api",
"carrier": 3011,
"shipping_country": "CN",
"final_carrier": 0,
"recipient_country": "RU",
"register_time": "2022-03-14T07:45:38Z",
"tracking_status": "Tracking",
"package_status": "Delivered",
"track_time": "2022-03-14T07:45:22Z",
"sync_status": true,
"push_time": "2022-03-14T07:47:42Z",
"push_status": "Success",
"push_status_code":200,
"stop_track_time": "2022-05-12T10:29:03Z",
"stop_track_reason": "ByRequest",
"is_retracked": false,
"carrier_change_count": 1,
"tag": null,
"email":"",
"order_no": "86574382938",
"order_time": "2022-04-25T22:22:47+05:00",
"lang":"",
"remark": "test",
"latest_event_time": "2023-08-05T10:00:21+05:00",
"latest_event_info": "FAISALABAD,Shipment has been Delivered. Delivery Date & Time Aug 5 2023 9:48AM and Received By: Shahzad",
"days_after_order ":2,
"days_after_last_update ":null,
"days_of_transit ":2,
"days_of_transit_done ":2,
"delievery_time": "2023-08-05T05:00:21Z",
"pickup_time": "",
"destination_postal_code": null,
"origin_country": null,
"destination_country": null,
"destination_city": null,
"ship_date": null,
"shipper": null,
"consignee": null,
"phone_number_last_4": null,
"phone_number": null,
"cpf_or_cnpj": null,
"special_tracking_info": null
}
]
}
}
Response Explanation:
Item | Type |
Description |
---|---|---|
page | Object | Page information. |
-data_total | Int. | Total data count. |
-page_total | Int. | Total page count. |
-page_no | Int. | Current page index (default 0) |
-page_size | Int. | Number of data per page (default 40, maximum 40) |
code | Int. | The HTTP Status code and error code. |
data | Object | The response data. |
-accepted | Object | This shows the data that has been received and processed successfully. |
--number | String | Tracking number. |
--param_type | Enum. | Additional tracking parameters types. "None" "PostalCode" "PhoneLast4Digits" "Alpha-2CountryCode&PostalCode" "OriginOffice" "Client" |
--origin_country | String | Origin country. Use the two-letter country code in ISO 3166-1 format. Include as an additional tracking field when making a request to the /register. |
--ship_date | DateTime | Shipping date in YYYY/MM/DD format. Include as an additional tracking field when making a request to the /register. |
--destination_postal_code | String | The postal of the destination address. Include as an additional tracking field when making a request to the /register. |
--destination_country | String | Destination country.Use the two-letter country code in ISO 3166-1 format. Include as an additional tracking field when making a request to the /register. |
--destination_city | String | Destination city. Include as an additional tracking field when making a request to the /register. |
--shipper | String | Shipper name. Include as an additional tracking field when making a request to the /register. |
--consignee | String | Consignee name. Include as an additional tracking field when making a request to the /register. |
--phone_number_last_4 | String | The last digits of the shipper's or recipient's phone number. Include as an additional tracking field when making a request to the /register. |
--phone_number | String | The shipper's or recipient's phone number. Include as an additional tracking field when making a request to the /register. |
--cpf_or_cnpj | String | Individual Taxpayer Registry(CPF)/National Registry of Legal Entities(CNPJ). Include as an additional tracking field when making a request to the /register. |
--special_tracking_info | Object | This parameter format is an object, each consisting of "number_type" and "parameter". "number_type" represents different query channels provided by the carrier, and "parameter" is the corresponding value for that query channel. |
---number_type | String | Available channels for checking logistics information provided by carriers. Include as an additional tracking field when making a request to the /register. |
---parameter | String | The value of the query channel. Include as an additional tracking field when making a request to the /register. |
--data_origin | Enum. | Upload Source. "Api" "Manual" "Import" |
--carrier | Int. | Carrier code. |
--final_carrier | Int. | Carrier Code of the last-mile carrier. |
--package_status | Int. | Package status. |
--shipping_country | String | The country where the package is originated. |
--recipient_country | String | The country where the package is sent to. |
--register_time | String | The time when the tracking number is registered. |
--tracking_status | Enum. | Tracking status: "Tracking" "Stopped" |
--sync_status | Boolean | Sync status:The latest status of data synchronization true: Sync successful false: Sync failed |
--track_time | String | The latest tracking time. |
--push_time | String | The latest push time. |
--push_status | Enum. | Push status: "NotPushed" "Success" "Failure" |
--push_status_code | Int. | Code for push_status see [HTTP Status Code] and Error code. |
--stop_track_time | Int. | The time when the tracking stopped. |
--stop_track_reason | String | The reason why the tracking is stopped: "Expired":Stopped by system's expiration policy. "ByRequest":Stopped by a request. "InvalidCarrier":Stopped becuase the carrier is not valid. |
--is_retracked | Boolean | If the tracking number is re-tracked. |
--carrier_change_count | Int. | How many times the carrier of the tracking number is changed. 5 being the highest limit. |
--tag | String | Custom tag, see Tracking number registration. |
--order_no | String | Order Number |
--order_time | DateTime | Order Date |
String | ||
--lang | String | Translating Language Code |
--remark | String | Note |
--latest_event_time | DateTime | Latest Event Time |
--latest_event_info | String | Latest Event |
--days_after_order | Int. | Order Transit Time(in days) Calculation: 1. For delivered status, Order Transit Time(in days) = Delivery Date - First Event Date. 2. For non-delivered status, with tracking result, Order Transit Time(in days) = Current Date - First Event Date. 3. No tracking result, Order Transit Time(in days) = 0. |
--days_after_last_update | Int. | No Update Days: 1. For delivered, return to sender, and no result status, interval in days = 0. 2. For other cases, interval in days = Current Date - Last Event Date. |
--days_of_transit | Int. | Transit Time(in days) Calculation: For delivered status: 1. With "InTransit_PickedUp",Transit Time(in days) = Delivery Date - Pickedup Date 2. Without "InTransit_PickedUp",with "InfoReceived",Transit Time(in days) = Delivery Date - First Event Date after "InfoReceived". 3. Without both "InTransit_PickedUp" and “InfoReceived”,Transit Time(in days) = Delivery Date - First Event Date. For non-delivered status , with tracking result: 1. With “InTransit_PickedUp”,Transit Time(in days) = Current Date - Pickup Date 2. WIthout “InTransit_PickedUp",with "InfoReceived",Transit Time(in days) = Current Date - First Event Date after "InfoReceived". 3. WIthout "InTransit_PickedUp",with "InfoReceived",and only one tracking event, Transit Time(in days) = 0. 4. Without both "InTransit_PickedUp" and "InfoReceived",Transit Time(in days) = Current Date - First Event Date. No tracking result: Transit Time(in days) = 0. |
--days_of_transit_done | Int. | Delivery Time(in days) Calculation: For delivered status: 1. With "InTransit_PickedUp",Delivery Time(in days) = Delivery Date - Pickup Date 2. Without "InTransit_PickedUp",with "InfoReceived",Delivery Time(in days) =Delivery Date - First Event Date after "InfoReceived". 3. Without both "InTransit_PickedUp" and "InfoReceived",Delivery Time(in days) = Delivery Date - First Event Date. For non-delivered status: Delivery Time(in days) = 0. |
--delievery_time | DateTime | Delivery date |
--pickup_time | DateTime | Picked up date |
Get Tracking Details - POST https://api.17track.net/track/v2.4/gettrackinfo
- The endpoint receives a maximum of 40 tracking numbers at a single time.
- The usage logic of this endpoint is the same as getracklist.
Example Request
curl -X POST \
--header '17token:your secret key' \
--header 'Content-Type:application/json' \
--data '[
{
"number": "270434455123",
"carrier": 100003
},
{
"number": "21213123123230",
"carrier": 21051
}
]' \
https://api.17track.net/track/v2.4/gettrackinfo
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.17track.net/track/v2.4/gettrackinfo",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "[
{
"number": "270434455123",
"carrier": 100003
},
{
"number": "21213123123230",
"carrier": 21051
}
]",
CURLOPT_HTTPHEADER => [
"17token: your secret key",
"content-type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.17track.net/track/v2.4/gettrackinfo"),
Headers =
{
{ "17token", "your secret key" },
},
Content = new StringContent("[
{
"number": "270434455123",
"carrier": 100003
},
{
"number": "21213123123230",
"carrier": 21051
}
]")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
String value = "[
{
"number": "270434455123",
"carrier": 100003
},
{
"number": "21213123123230",
"carrier": 21051
}
]";
RequestBody body = RequestBody.create(mediaType, value);
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/gettrackinfo")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("17token", "your secret key")
.build();
Response response = client.newCall(request).execute();
response.body();
const axios = require("axios");
const options = {
method: 'POST',
url: 'https://api.17track.net/track/v2.4/gettrackinfo',
headers: {
'content-type': 'application/json',
'17token': 'your secret key'
},
data: '[
{
"number": "270434455123",
"carrier": 100003
},
{
"number": "21213123123230",
"carrier": 21051
}
]'
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
import requests
url = "https://api.17track.net/track/v2.4/gettrackinfo"
payload = [
{
"number": "270434455123",
"carrier": 100003
},
{
"number": "21213123123230",
"carrier": 21051
}
]
headers = {
"content-type": "application/json",
"17token": "your secret key"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Parameter Explanation:
Parameter | Required |
Type |
Description |
---|---|---|---|
number | Yes | String | The tracking number must conform to the tracking number format. |
carrier | No | Int. | Carrier code. If not passed in and if the tracking number can be matched to multiple carriers, it will be processed for multiple times for each carrier matched. |
Example Response
{
"code": 0,
"data": {
"accepted": [
{
"number": "RR123465789CN",
"carrier": 100003,
"param": null,
"tag": "myID",
"lang": null,
"destination_postal_code": null,
"origin_country": null,
"destination_country": null,
"destination_city": null,
"ship_date": null,
"shipper": null,
"consignee": null,
"phone_number_last_4": null,
"phone_number": null,
"cpf_or_cnpj": null,
"special_tracking_info": null,
"track_info": {
"shipping_info": {
"shipper_address": {
"country": "CN",
"state": "GD",
"city": "SHENZHEN",
"street": "HARTFORD CT DISTRIBUTION CENTER",
"postal_code": "518000",
"coordinates": {
"longitude": "114.085947",
"latitude": "22.547"
}
},
"recipient_address": {
"country": "AF",
"state": null,
"city": "KABUL",
"street": null,
"postal_code": null,
"coordinates": {
"longitude": null,
"latitude": null
}
}
},
"latest_status": {
"status": "InfoReceived",
"sub_status": "InfoReceived",
"sub_status_descr": null
},
"latest_event": {
"time_iso": "2022-03-02T20:43:24-06:00",
"time_utc": "2022-03-03T02:43:24Z",
"time_raw": {
"date": "2022-03-02",
"time": "20:43:24",
"timezone": "-06:00"
},
"description": "Shipment information sent to FedEx",
"description_translation": {
"lang": "en",
"description": "Shipment information sent to FedEx"
},
"location": "NJ",
"stage": "InfoReceived",
"sub_status": "InfoReceived",
"address": {
"country": "US",
"state": "NJ",
"city": "MARLTON",
"street": null,
"postal_code": "08053",
"coordinates": {
"longitude": null,
"latitude": null
}
}
},
"time_metrics": {
"days_after_order": 7,
"days_of_transit": 7,
"days_of_transit_done": 7,
"days_after_last_update": 57,
"estimated_delivery_date": {
"source":"Official",
"from": "2021-09-01T08:00:54-05:00",
"to": "2021-09-01T13:00:45-05:00"
}
},
"milestone": [
{
"key_stage": "InfoReceived",
"time_iso": "2023-08-14T00:00:00-05:00",
"time_utc": "2023-08-14T05:00:00Z",
"time_raw": {
"date": "2023-08-14",
"time": null,
"timezone": null
}
},
{
"key_stage": "PickedUp",
"time_iso": "2023-08-15T08:46:00-05:00",
"time_utc": "2023-08-15T12:46:00Z",
"time_raw": {
"date": "2023-08-15",
"time": "08:46:00",
"timezone": "-05:00"
}
},
{
"key_stage": "Departure",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "Arrival",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "AvailableForPickup",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "OutForDelivery",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "Delivered",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "Returning",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "Returned",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
}
],
"misc_info": {
"risk_factor": 0,
"service_type": "FedEx International Priority",
"weight_raw": "1.1 KG",
"weight_kg": "1.1",
"pieces": "1",
"dimensions": "22*20*16 CM",
"customer_number": "2459642000~270434455123~FX",
"reference_number": null,
"local_number": "270434455123",
"local_provider": "Fedex",
"local_key": 100003
},
"tracking": {
"providers_hash": 182180920,
"providers": [
{
"provider": {
"key": 100003,
"name": "Fedex",
"alias": "Fedex",
"tel": null,
"homepage": "http://www.fedex.com/",
"country": "TR"
},
"service_type": "FedEx International Priority",
"latest_sync_status": "Success",
"latest_sync_time": "2022-04-28T02:37:03Z",
"provider_lang": null,
"provider_tips": null,
"events_hash": -731027172,
"events": [
{
"time_iso": "2023-08-14T00:00:00-05:00",
"time_utc": "2023-08-14T05:00:00Z",
"time_raw": {
"date": "2023-08-14",
"time": null,
"timezone": null
},
"description": "At local FedEx facility",
"description_translation": {
"lang": "en",
"description": "At local FedEx facility"
},
"location": "ANCHORAGE, AK, US",
"stage": "InfoReceived",
"sub_status": "InfoReceived",
"address": {
"country": "US",
"state": "AK",
"city": "ANCHORAGE",
"street": null,
"postal_code": "99502",
"coordinates": {
"longitude": "35.86166",
"latitude": "104.195397"
}
}
}
]
},
{
"provider": {
"key": 1151,
"name": "Australia Post",
"alias": "Australia Post",
"tel": null,
"homepage": "http://auspost.com.au/",
"country": "AU"
},
"service_type": "International Post Express",
"latest_sync_status": "Success",
"latest_sync_time": "2022-04-12T22:12:54Z",
"provider_lang": null,
"provider_tips": null,
"events_hash": -225868020,
"events": [
{
"time_iso": "2022-03-04T15:33:00+08:00",
"time_utc": "2022-03-04T07:33:00Z",
"time_raw": {
"date": "2022-03-04",
"time": "15:33:00",
"timezone": null
},
"description": "InfoReceived",
"description_translation": {
"lang": "en",
"description": "InfoReceived"
},
"location": null,
"stage": "InfoReceived",
"sub_status": "InfoReceived",
"address": {
"country": null,
"state": null,
"city": null,
"street": null,
"postal_code": null,
"coordinates": {
"longitude": null,
"latitude": null
}
}
}
]
}
]
}
}
}
],
"rejected": [
{
"carrier":"3011",
"number": "21213123123230",
"error": {
"code": -18019902,
"message": "The tracking number '21213123123230' does not register, please register first."
}
}
]
}
}
Response Explanation
Item |
Type |
Description |
---|---|---|
code | Int. | The HTTP Status code and error code. |
data | Object | The response data. |
-accepted | Object | This shows the data that has been received and processed successfully. |
--number | String | Tracking number. |
--carrier | Int. | Carrier code |
--origin_country | String | Origin country. Use the two-letter country code in ISO 3166-1 format. Include as an additional tracking field when making a request to the /register. |
--ship_date | DateTime | Shipping date in YYYY/MM/DD format. Include as an additional tracking field when making a request to the /register. |
--destination_postal_code | String | The postal of the destination address. Include as an additional tracking field when making a request to the /register. |
--destination_country | String | Destination country.Use the two-letter country code in ISO 3166-1 format. Include as an additional tracking field when making a request to the /register. |
--destination_city | String | Destination city. Include as an additional tracking field when making a request to the /register. |
--shipper | String | Shipper name. Include as an additional tracking field when making a request to the /register. |
--consignee | String | Consignee name. Include as an additional tracking field when making a request to the /register. |
--phone_number_last_4 | String | The last digits of the shipper's or recipient's phone number. Include as an additional tracking field when making a request to the /register. |
--phone_number | String | The shipper's or recipient's phone number. Include as an additional tracking field when making a request to the /register. |
--cpf_or_cnpj | String | Individual Taxpayer Registry(CPF)/National Registry of Legal Entities(CNPJ). Include as an additional tracking field when making a request to the /register. |
--special_tracking_info | Object | This parameter format is an object, each consisting of "number_type" and "parameter". "number_type" represents different query channels provided by the carrier, and "parameter" is the corresponding value for that query channel. |
---number_type | String | Available channels for checking logistics information provided by carriers. Include as an additional tracking field when making a request to the /register. |
---parameter | String | The value of the query channel. Include as an additional tracking field when making a request to the /register. |
--tag | String | Custom tag. See tracking number registration for more info. |
--lang | String | Used to translate logistics events, specify the translation language code. |
--track_info | Object | Tracking info |
---shipping_info | Object | Location info. |
----shipper_address | Object | Location info of the origin country. |
-----country | String | Country or region (capital letter). |
-----state | String | State or province. |
-----postal_code | String | Post code. |
-----city | String | City. |
-----street | String | Street. |
-----coordinates | Object | Coordinates. |
------longitude | String | longitude. |
------latitude | String | latitude. |
----recipient_address | Object | Location info of the destination country. |
-----country | String | Country or region (capital letter). |
-----state | String | State or province. |
-----postal_code | String | Post code. |
-----city | String | City. |
-----street | String | Street. |
-----coordinates | Object | Coordinates. |
------longitude | String | longitude. |
------latitude | String | latitude. |
---latest_status | Object | The lastest status. |
----status | String | Main status. |
----sub_status | String | Sub-status. |
----sub_status_descr | String | Status description. |
---latest_event | Object | The latest event. See events set. |
---time_metrics | Object | Info related to timeliness, where estimated_delivery_date indicate a period of time. |
----days_after_order | Int. | Order Transit Time(in days) Calculation: 1. For delivered status, Order Transit Time(in days) = Delivery Date - First Event Date. 2. For non-delivered status, with tracking result, Order Transit Time(in days) = Current Date - First Event Date. 3. No tracking result, Order Transit Time(in days) = 0. |
----days_after_last_update | Int. | No Update Days: 1. For delivered, return to sender, and no result status, interval in days = 0. 2. For other cases, interval in days = Current Date - Last Event Date. |
----days_of_transit | Int. | Transit Time(in days) Calculation: For delivered status: 1. With "InTransit_PickedUp",Transit Time(in days) = Delivery Date - Pickedup Date 2. Without "InTransit_PickedUp",with "InfoReceived",Transit Time(in days) = Delivery Date - First Event Date after "InfoReceived". 3. Without both "InTransit_PickedUp" and “InfoReceived”,Transit Time(in days) = Delivery Date - First Event Date. For non-delivered status , with tracking result: 1. With “InTransit_PickedUp”,Transit Time(in days) = Current Date - Pickup Date 2. WIthout “InTransit_PickedUp",with "InfoReceived",Transit Time(in days) = Current Date - First Event Date after "InfoReceived". 3. WIthout "InTransit_PickedUp",with "InfoReceived",and only one tracking event, Transit Time(in days) = 0. 4. Without both "InTransit_PickedUp" and "InfoReceived",Transit Time(in days) = Current Date - First Event Date. No tracking result: Transit Time(in days) = 0. |
----days_of_transit_done | Int. | Delivery Time(in days) Calculation: For delivered status: 1. With "InTransit_PickedUp",Delivery Time(in days) = Delivery Date - Pickup Date 2. Without "InTransit_PickedUp",with "InfoReceived",Delivery Time(in days) =Delivery Date - First Event Date after "InfoReceived". 3. Without both "InTransit_PickedUp" and "InfoReceived",Delivery Time(in days) = Delivery Date - First Event Date. For non-delivered status: Delivery Time(in days) = 0. |
----estimated_delivery_date | Object | The estimiated date of delivery. It gives a range of dates. |
-----source | String | It refers to the party who provides info for "from" and "to" sections. It will show "17TRACK" when the info is provided by 17TRACK; show "Official" when the info is provided by carrier; and show "null" when the info is provided by none. |
-----from | String | The earliest estimated date of delivery (ISO format). E.g 2021-09-01T08:00:54-05:00 |
-----to | String | The latest estimated date of delivery (ISO format). E.g 2021-09-01T08:00:54-05:00 |
---milestone | Array | A set of date regarding each important stage of the shipping process. Purpose: Display key nodes and their occurrence sequence and time during the shipping process. Usage: Iterate through each milestone item, recommended order: InfoReceived >> PickedUp >> Departure >> Arrival >> OutForDelivery >> Delivered. (Use AvailableForPickup, Returned, Returning as needed based on specific cases) Note: If time_iso or time_utc is null, it means the carrier did not provide event description. milestone[]. key_stage can be used to query more specific event content in tracking.providers[].events[].stage. Meanings of milestone's key_stage: 1. InfoReceived : The carrier has received the order info and is about to pick up the package from the sender. 2. PickedUp : The package has been collected by the carrier. 3. Departure : The package has departed from a port. (Usually means after customs clearance.) 4. Arrival : The package has arrived at a port. (Not certain if the customs clearance is made.) 5. AvailableForPickup : The package has arrived at the pick up point of the destination. The recipient needs to go get it. 6. OutForDelivery : The package is out for delivery. 7. Delivered : The package is delivered and signed by the recipient. 8. Returned : The package was returned to the sender. 9. Returning : The package is being returned to the sender. This not always change to "Returned" even if the process is done. |
----key_stage | String | A set of all milestones. There are 9 of them. When time_iso and time_utc are populated, it means the relevent event has happened. These stages can be use to get a big picture of the shipping process. You can know the package has gone through a flow like "InfoReceived > PickedUp > Departure > Arrival > Delivered". |
----time_iso | String | 1. The time of the stage in ISO format, transfered from the local time of the carrier. If it can not be tranfered, the original time format will show instead. 2. If the upperstream carrier provide timezone info, it will be prioritize, otherwise the carrier's HQ time will be used. 3. 2022-03-02T20:43:24-06:00 means the timezone is UTC−06:00. 4.Remove the -06:00 is removed, it means the carrier's local time. 5. See this field is in tracking.providers[].provider[].events[].time_iso. |
----time_utc | String | 1. The time of the stage in UTC format, transfered from the ISO time. 2. For example: 2022-03-03T02:43:24Z. 3. See tracking.providers[].provider[].events[].time_utc. |
----time_raw | Object | Original date & time info provided by carrier: 1. Three groups of data, including YYYY-MM-DD, HH:MM:SS, Timezone. 2. It will show "null" if carrier does not provide any data. |
-----date | String | YYYY-MM-DD |
-----time | String | HH:MM:SS |
-----timezone | String | Timezone (If it shows "null" in Timezone section but a valid date & time in time_iso, it indicates that the Timezone info is added by 17TRACK.) |
---misc_info | Object | Package additional info. |
----risk_factor | String | Package risk factor. |
----service_type | String | Package service type |
----weight_raw | String | Original weight info. |
----weight_kg | String | Weight info in Kg. |
----pieces | String | Total pieces. |
----dimensions | String | Dimensions (length, width, height). |
----customer_number | String | The customer number of the recipient. |
----reference_number | String | A reference number. |
----local_number | String | The last-mile tracking code. |
----local_provider | String | The last-mile carrier. |
----local_key | Int. | The last-mile carrier code. |
---tracking | Object | Tracking info. |
----providers_hash | Int. | The hash value, calculated from the event content, can be used to determine if there are changes. |
----providers | Array | A set of carriers participated in the shipping process, in ascending order, with 0 being the second carrier, 1 being the first, etc. Note: When the parcel is a postal shipment, the "providers[0]" object is the destination carrier, "providers[1]" is the object is the originating carrier, " providers[0]" and "providers[1]" description, time may be duplicated. |
-----provider | Object | Carrier info |
------key | Int. | Carrier code. |
------name | String | Carrier name. |
------tel | String | Carrier phone number. |
------homepage | String | Carrier website. |
------country | String | Carrier country. |
-----service_type | String | Carrier service type. |
-----latest_sync_status | String | The latest status of data synchronization. Failure Success |
-----latest_sync_time | String | The last time of data synchronization. |
-----events_hash | Int. | The hash value of the events. |
-----provider_tips | String | The carrier notice. |
-----provider_lang | String | The carrier’s current tracking event language; if uncertain, it is null |
-----events | Array | The set of events. |
------time_iso | String | The time of the event in ISO format. If there is no valid data, it shows null. |
------time_utc | String | The time of the event in UTC format. If the time_iso is null, it shows null. |
------time_raw | Object | Original date & time info provided by carrier: 1. Three groups of data, including YYYY-MM-DD, HH:MM:SS, Timezone. 2. It will show "null" if carrier does not provide any data. |
-------date | String | YYYY-MM-DD |
-------time | String | HH:MM:SS |
-------timezone | String | Timezone (If it shows "null" in Timezone section but a valid date & time in time_iso, it indicates that the Timezone info is added by 17TRACK.) |
------description | String | Event description. Including: time, shipping details, key status. |
------description_translation | String | Describes the translation node. |
-------description | String | Description of the translated event. |
-------lang | String | Translation language code |
------location | String | Location. |
------stage | String | Stage. |
------sub_status | String | Sub-status. |
------address | Object | Address info. |
-------country | String | Country or region. |
-------state | String | State or province. |
-------city | String | City. |
-------street | String | Street. |
-------postal_code | String | Post code. |
-------coordinates | Object | coordinates. |
--------longitude | String | longitude. |
--------latitude | String | latitude. |
-rejected | Array | Rejects the return content of the request. |
--number | String | The tracking number must conform to the tracking number format. |
--carrier | Int. | Carrier Code. |
--error | Object | Error message collection |
---code | Int. | Error code. |
---message | String | Error description. |
Get a push manually - POST https://api.17track.net/track/v2.4/push
- The endpoint receives a maximum of 40 tracking numbers at a single time.
- The request will put the tracking number in a queue for processing before it is pushed by the system's universal scheduler.
Example Request
curl -X POST \
--header '17token:your secret key' \
--header 'Content-Type:application/json' \
--data '[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]' \
https://api.17track.net/track/v2.4/push
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.17track.net/track/v2.4/push",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]",
CURLOPT_HTTPHEADER => [
"17token: your secret key",
"content-type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.17track.net/track/v2.4/push"),
Headers =
{
{ "17token", "your secret key" },
},
Content = new StringContent("[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
String value = "[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]";
RequestBody body = RequestBody.create(mediaType, value);
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/push")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("17token", "your secret key")
.build();
Response response = client.newCall(request).execute();
response.body();
const axios = require("axios");
const options = {
method: 'POST',
url: 'https://api.17track.net/track/v2.4/push',
headers: {
'content-type': 'application/json',
'17token': 'your secret key'
},
data: '[
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]'
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
import requests
url = "https://api.17track.net/track/v2.4/push"
payload = [
{
"number": "RR123456789CN",
"carrier": 3011
},
{
"number": "21213123123230",
"carrier": 21051
}
]
headers = {
"content-type": "application/json",
"17token": "your secret key"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Parameter Explanation:
Parameter | Required |
Type |
Description |
---|---|---|---|
number | Yes | String | The tracking number must conform to the tracking number format. |
carrier | No | Int. | Carrier Code. If not passed in and if the tracking number can be matched to multiple carriers, it will be processed for multiple times for each carrier matched. |
Example Response
{ "code": 0, "data": { "accepted": [ { "number": "RR123456789CN", "carrier": 3011 } ], "rejected": [ { "carrier":0, "number": "21213123123230", "error": { "code": -18019909, "message": "No tracking information at this time." } } ] } }
Response Explanation:
Item | Description |
---|---|
code | The HTTP Status code and error code. |
data | The response data. |
-accepted | This shows the data that has been received and processed successfully. |
-rejected | This shows the tracking numbers failed to be processed. An error code will be returned. |
--number | Tracking number. |
--carrier | Carrier Code. |
--error | Error message collection |
---code | Error code. |
---message | Error description. |
Get Real Time Tracking Details - POST https://api.17track.net/track/v2.4/getRealTimeTrackInfo
- If the tracking number is not registered, the response result will not be saved in the current account; if the number is subscribed and the query result changes, a push (webhook) will be triggered;
- Currently, the following carriers do not support real-time query through this interface:
Carrier Name |
Carrier Code |
---|---|
USPS | 21051 |
Royal Mail | 11031 |
Australia post | 1151 |
Direct Freight Express | 101066 |
DHL eCommerce US | 7047 |
DHL Global Forwarding | 100766 |
- The maximum timeout for requests to this interface is 30 seconds;
- This interface provides two query modes, each with different query times and different quota deduction rules.
cacheLevel=0: Retrieves tracking information from the carrier within the last 3 hours (default). This is the manual refresh method, commonly used by most users, and deducts 1 quota per request.
cacheLevel=1: Initiates a real-time fetch action to obtain the current tracking information from the carrier, offering the most up-to-date results. This method deducts 10 quotas per request.
Example Request
curl -X POST \
--header '17token:密钥' \
--header 'Content-Type:application/json' \
--data '[
{
"number": "RR123456789CN",
"carrier": 3011
}
]' \
https://api.17track.net/track/v2.4/getRealTimeTrackInfo
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.17track.net/track/v2.4/getRealTimeTrackInfo',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'[
{
"number": "RR123456789CN",
"carrier":3011
}
]
',
CURLOPT_HTTPHEADER => array(
'content-type: application/json',
'17token: 密钥'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.17track.net/track/v2.4/getRealTimeTrackInfo");
request.Headers.Add("content-type", "application/json");
request.Headers.Add("17token", "密钥");
var content = new StringContent("[\r\n {\r\n \"number\": \"RR123456789CN\",\r\n \"carrier\":3011\r\n }\r\n]\r\n ", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "[\r\n {\r\n \"number\": \"RR123456789CN\",\r\n \"carrier\":3011\r\n }\r\n]\r\n ");
Request request = new Request.Builder()
.url("https://api.17track.net/track/v2.4/getRealTimeTrackInfo")
.method("POST", body)
.addHeader("content-type", "application/json")
.addHeader("17token", "密钥")
.build();
Response response = client.newCall(request).execute();
const axios = require('axios');
let data = JSON.stringify([
{
"number": "RR123456789CN",
"carrier": 3011
}
]);
let config = {
method: 'post',
maxBodyLength: Infinity,
url: 'https://api.17track.net/track/v2.4/getRealTimeTrackInfo',
headers: {
'content-type': 'application/json',
'17token': '密钥'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
import json
url = "https://api.17track.net/track/v2.4/getRealTimeTrackInfo"
payload = json.dumps([
{
"number": "RR123456789CN",
"carrier": 3011
}
])
headers = {
'content-type': 'application/json',
'17token': '密钥'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Request Parameter
Parameter | Required | Type | Description |
---|---|---|---|
number | Yes | String | Each request is limited to one tracking number.. It must conform to the tracking number format. |
carrier | No | Int. | 1. Pass in the Carrier Code if you want to specify a carrier for the tracking number. 2. Most UPU and commercial carriers can be auto-identified by our system. If no or an incorrect carrier code is provided, the system will identify the most likely carrier and return its Carrier Code. 3. If you receive a -18019903 error indicates that no carrier was found. Register the number again with a valid Carrier Code. |
final_carrier | No | Int. | Carrier Code of the last-mile carrier. (Applicable only for UPU numbers) |
auto_detection | No | Boolean | Controls carrier auto-detection. Default is 'true'. If enabled, the system will attempt to auto-detect the carrier based on the tracking number. Note: This does not always guarantee accuracy and will be ignored if a carrier parameter is provided. |
origin_country | No | String | Origin country. Use the two-letter country code in ISO 3166-1 format. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
ship_date | No | DateTime | Shipping date in YYYY/MM/DD format. The Additional Field required by some carriers to retrieve the tracking info. |
destination_postal_code | No | String | The postal of the destination address. The Additional Field required by some carriers to retrieve the tracking info. |
destination_country | No | String | Destination country. The Additional Field required by some carriers to retrieve the tracking info. |
destination_city | No | String | Destination city. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
shipper | No | String | Shipper name. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
consignee | No | String | Consignee name. This can help 17TRACK enhance the accuracy of shipment tracking and carrier auto-detection. |
phone_number_last_4 | No | String | The last digits of the shipper's or recipient's phone number. The Additional Field required by some carriers to retrieve the tracking info. |
phone_number | No | String | The shipper's or recipient's phone number.The Additional Field required by some carriers to retrieve the tracking info. |
cpf_or_cnpj | No | String | Individual Taxpayer Registry(CPF)/National Registry of Legal Entities(CNPJ). The Additional Field required by some carriers to retrieve the tracking info. |
special_tracking_info | No | Object | This parameter format is an object, each consisting of "number_type" and "parameter". "number_type" represents different query channels provided by the carrier, and "parameter" is the corresponding value for that query channel. |
-number_type | No | String | Available channels for checking logistics information provided by carriers. The Additional Field required by some carriers to retrieve the tracking info. |
-parameter | No | String | The value of the query channel. The Additional Field required by some carriers to retrieve the tracking info. |
cacheLevel | No | Int. | 17TRACK offers two query modes: 0: Retrieves tracking info from the carrier within the last 3 hours (default). This is the manual refresh method , commonly used by most users, deducting 1 quota per request. 1: Initiates an immediate fetch to retrieve the most up-to-date tracking information. This method provides the latest updates, and deducts 10 quotas per request. |
Successful Response Example
{
"code": 0,
"data": {
"accepted": [
{
"number": "RR123456789CN",
"carrier": 3011,
"param": null,
"lang": null,
"destination_postal_code": null,
"origin_country": null,
"destination_country": null,
"destination_city": null,
"ship_date": null,
"shipper": null,
"consignee": null,
"phone_number_last_4": null,
"phone_number": null,
"cpf_or_cnpj": null,
"special_tracking_info": null,
"tag": "",
"track_info": {
"shipping_info": {
"shipper_address": {
"country": "CN",
"state": null,
"city": null,
"street": null,
"postal_code": null,
"coordinates": {
"longitude": null,
"latitude": null
}
},
"recipient_address": {
"country": "",
"state": null,
"city": null,
"street": null,
"postal_code": null,
"coordinates": {
"longitude": null,
"latitude": null
}
}
},
"latest_status": {
"status": "NotFound",
"sub_status": "NotFound_Other",
"sub_status_descr": null
},
"latest_event": null,
"time_metrics": {
"days_after_order": 0,
"days_of_transit": 0,
"days_of_transit_done": 0,
"days_after_last_update": 0,
"estimated_delivery_date": {
"source": null,
"from": null,
"to": null
}
},
"milestone": [],
"misc_info": {
"risk_factor": 0,
"service_type": null,
"weight_raw": null,
"weight_kg": null,
"pieces": null,
"dimensions": null,
"customer_number": null,
"reference_number": null,
"local_number": null,
"local_provider": null,
"local_key": 0
},
"tracking": {
"providers_hash": 0,
"providers": [
{
"provider": {
"key": 3011,
"name": "China Post",
"alias": "China Post 中国邮政",
"tel": "",
"homepage": "https://yjcx.ems.com.cn/",
"country": "CN"
},
"provider_lang": null,
"provider_tips": "DLVRD_ACCPT_ZU",
"service_type": null,
"latest_sync_status": "Success",
"latest_sync_time": "2024-12-10T14:14:42Z",
"events_hash": 0,
"events": []
}
]
}
}
}
],
"rejected": []
}
}
Response Explanation
Item | Type | Description |
---|---|---|
code | Int. | The HTTP Status code and error code. |
data | Object | The response data. |
-accepted | Object | This shows the data that has been received and processed successfully. |
--number | String | Tracking number. |
--carrier | Int. | Carrier code |
--origin_country | String | Origin country. Use the two-letter country code in ISO 3166-1 format. Include as an additional tracking field when making a request. |
--ship_date | DateTime | Shipping date in YYYY/MM/DD format. Include as an additional tracking field when making a request. |
--destination_postal_code | String | The postal of the destination address. Include as an additional tracking field when making a request. |
--destination_country | String | Destination country.Use the two-letter country code in ISO 3166-1 format. Include as an additional tracking field when making a request. |
--destination_city | String | Destination city. Include as an additional tracking field when making a request. |
--shipper | String | Shipper name. Include as an additional tracking field when making a request. |
--consignee | String | Consignee name. Include as an additional tracking field when making a request. |
--phone_number_last_4 | String | The last digits of the shipper's or recipient's phone number. Include as an additional tracking field when making a request. |
--phone_number | String | The shipper's or recipient's phone number. Include as an additional tracking field when making a request. |
--cpf_or_cnpj | String | Individual Taxpayer Registry(CPF)/National Registry of Legal Entities(CNPJ). Include as an additional tracking field when making a request. |
--special_tracking_info | Object | This parameter format is an object, each consisting of "number_type" and "parameter". "number_type" represents different query channels provided by the carrier, and "parameter" is the corresponding value for that query channel. |
---number_type | String | Available channels for checking logistics information provided by carriers. Include as an additional tracking field when making a request. |
---parameter | String | The value of the query channel. Include as an additional tracking field when making a request. |
--tag | String | Custom tag. See tracking number registration for more info. |
--track_info | Object | Tracking info |
---shipping_info | Object | Location info. |
----shipper_address | Object | Location info of the origin country. |
-----country | String | Country or region (capital letter). |
-----state | String | State or province. |
-----postal_code | String | Post code. |
-----city | String | City. |
-----street | String | Street. |
-----coordinates | Object | Coordinates. |
------longitude | String | longitude. |
------latitude | String | latitude. |
----recipient_address | Object | Location info of the destination country. |
-----country | String | Country or region (capital letter). |
-----state | String | State or province. |
-----postal_code | String | Post code. |
-----city | String | City. |
-----street | String | Street. |
-----coordinates | Object | Coordinates. |
------longitude | String | longitude. |
------latitude | String | latitude. |
---latest_status | Object | The lastest status. |
----status | String | Main status. |
----sub_status | String | Sub-status. |
----sub_status_descr | String | Status description. |
---latest_event | Object | The latest event. See events set. |
---time_metrics | Object | Info related to timeliness, where estimated_delivery_date indicate a period of time. |
----days_after_order | Int. | Order Transit Time(in days) Calculation: 1. For delivered status, Order Transit Time(in days) = Delivery Date - First Event Date. 2. For non-delivered status, with tracking result, Order Transit Time(in days) = Current Date - First Event Date. 3. No tracking result, Order Transit Time(in days) = 0. |
----days_after_last_update | Int. | No Update Days: 1. For delivered, return to sender, and no result status, interval in days = 0. 2. For other cases, interval in days = Current Date - Last Event Date. |
----days_of_transit | Int. | Transit Time(in days) Calculation: For delivered status: 1. With "InTransit_PickedUp",Transit Time(in days) = Delivery Date - Pickedup Date 2. Without "InTransit_PickedUp",with "InfoReceived",Transit Time(in days) = Delivery Date - First Event Date after "InfoReceived". 3. Without both "InTransit_PickedUp" and “InfoReceived”,Transit Time(in days) = Delivery Date - First Event Date. For non-delivered status , with tracking result: 1. With “InTransit_PickedUp”,Transit Time(in days) = Current Date - Pickup Date 2. WIthout “InTransit_PickedUp",with "InfoReceived",Transit Time(in days) = Current Date - First Event Date after "InfoReceived". 3. WIthout "InTransit_PickedUp",with "InfoReceived",and only one tracking event, Transit Time(in days) = 0. 4. Without both "InTransit_PickedUp" and "InfoReceived",Transit Time(in days) = Current Date - First Event Date. No tracking result: Transit Time(in days) = 0. |
----days_of_transit_done | Int. | Delivery Time(in days) Calculation: For delivered status: 1. With "InTransit_PickedUp",Delivery Time(in days) = Delivery Date - Pickup Date 2. Without "InTransit_PickedUp",with "InfoReceived",Delivery Time(in days) =Delivery Date - First Event Date after "InfoReceived". 3. Without both "InTransit_PickedUp" and "InfoReceived",Delivery Time(in days) = Delivery Date - First Event Date. For non-delivered status: Delivery Time(in days) = 0. |
----estimated_delivery_date | Object | The estimiated date of delivery. It gives a range of dates. |
-----source | String | It refers to the party who provides info for "from" and "to" sections. It will show "17TRACK" when the info is provided by 17TRACK; show "Official" when the info is provided by carrier; and show "null" when the info is provided by none. |
-----from | String | The earliest estimated date of delivery (ISO format). E.g 2021-09-01T08:00:54-05:00 |
-----to | String | The latest estimated date of delivery (ISO format). E.g 2021-09-01T08:00:54-05:00 |
---milestone | Array | A set of date regarding each important stage of the shipping process. Purpose: Display key nodes and their occurrence sequence and time during the shipping process. Usage: Iterate through each milestone item, recommended order: InfoReceived >> PickedUp >> Departure >> Arrival >> OutForDelivery >> Delivered. (Use AvailableForPickup, Returned, Returning as needed based on specific cases) Note: If time_iso or time_utc is null, it means the carrier did not provide event description. milestone[]. key_stage can be used to query more specific event content in tracking.providers[].events[].stage. Meanings of milestone's key_stage: 1. InfoReceived : The carrier has received the order info and is about to pick up the package from the sender. 2. PickedUp : The package has been collected by the carrier. 3. Departure : The package has departed from a port. (Usually means after customs clearance.) 4. Arrival : The package has arrived at a port. (Not certain if the customs clearance is made.) 5. AvailableForPickup : The package has arrived at the pick up point of the destination. The recipient needs to go get it. 6. OutForDelivery : The package is out for delivery. 7. Delivered : The package is delivered and signed by the recipient. 8. Returned : The package was returned to the sender. 9. Returning : The package is being returned to the sender. This not always change to "Returned" even if the process is done. |
----key_stage | String | A set of all milestones. There are 9 of them. When time_iso and time_utc are populated, it means the relevent event has happened. These stages can be use to get a big picture of the shipping process. You can know the package has gone through a flow like "InfoReceived > PickedUp > Departure > Arrival > Delivered". |
----time_iso | String | 1. The time of the stage in ISO format, transfered from the local time of the carrier. If it can not be tranfered, the original time format will show instead. 2. If the upperstream carrier provide timezone info, it will be prioritize, otherwise the carrier's HQ time will be used. 3. 2022-03-02T20:43:24-06:00 means the timezone is UTC−06:00. 4.Remove the -06:00 is removed, it means the carrier's local time. 5. See this field is in tracking.providers[].provider[].events[].time_iso. |
----time_utc | String | 1. The time of the stage in UTC format, transfered from the ISO time. 2. For example: 2022-03-03T02:43:24Z. 3. See tracking.providers[].provider[].events[].time_utc. |
----time_raw | Object | Original date & time info provided by carrier: 1. Three groups of data, including YYYY-MM-DD, HH:MM:SS, Timezone. 2. It will show "null" if carrier does not provide any data. |
-----date | String | YYYY-MM-DD |
-----time | String | HH:MM:SS |
-----timezone | String | Timezone (If it shows "null" in Timezone section but a valid date & time in time_iso, it indicates that the Timezone info is added by 17TRACK.) |
---misc_info | Object | Package additional info. |
----risk_factor | String | Package risk factor. |
----service_type | String | Package service type |
----weight_raw | String | Original weight info. |
----weight_kg | String | Weight info in Kg. |
----pieces | String | Total pieces. |
----dimensions | String | Dimensions (length, width, height). |
----customer_number | String | The customer number of the recipient. |
----reference_number | String | A reference number. |
----local_number | String | The last-mile tracking code. |
----local_provider | String | The last-mile carrier. |
----local_key | Int. | The last-mile carrier code. |
---tracking | Object | Tracking info. |
----providers_hash | Int. | The hash value, calculated from the event content, can be used to determine if there are changes. |
----providers | Array | A set of carriers participated in the shipping process, in ascending order, with 0 being the second carrier, 1 being the first, etc. Note: When the parcel is a postal shipment, the "providers[1]" object is the destination carrier, "providers[0]" is the object is the originating carrier, " providers[0]" and "providers[1]" description, time may be duplicated. |
-----provider | Object | Carrier info |
------key | Int. | Carrier code. |
------name | String | Carrier name. |
------tel | String | Carrier phone number. |
------homepage | String | Carrier website. |
------country | String | Carrier country. |
-----service_type | String | Carrier service type. |
-----latest_sync_status | String | The latest status of data synchronization. Failure Success |
-----latest_sync_time | String | The last time of data synchronization. |
-----events_hash | Int. | The hash value of the events. |
-----provider_tips | String | The carrier notice. |
-----events | Array | The set of events. |
------time_iso | String | The time of the event in ISO format. If there is no valid data, it shows null. |
------time_utc | String | The time of the event in UTC format. If the time_iso is null, it shows null. |
------time_raw | Object | Original date & time info provided by carrier: 1. Three groups of data, including YYYY-MM-DD, HH:MM:SS, Timezone. 2. It will show "null" if carrier does not provide any data. |
-------date | String | YYYY-MM-DD |
-------time | String | HH:MM:SS |
-------timezone | String | Timezone (If it shows "null" in Timezone section but a valid date & time in time_iso, it indicates that the Timezone info is added by 17TRACK.) |
------description | String | Event description. Including: time, shipping details, key status. |
------description_translation | String | Describes the translation node. |
-------description | String | Description of the translated event. |
-------lang | String | Translation language code |
------location | String | Location. |
------stage | String | Stage. |
------sub_status | String | Sub-status. |
------address | Object | Address info. |
-------country | String | Country or region. |
-------state | String | State or province. |
-------city | String | City. |
-------street | String | Street. |
-------postal_code | String | Post code. |
-------coordinates | Object | coordinates. |
--------longitude | String | longitude. |
--------latitude | String | latitude. |
-rejected | Array | Rejects the return content of the request. |
--number | String | The tracking number must conform to the tracking number format. |
--carrier | Int. | Carrier Code. |
--error | Object | Error message collection |
---code | Int. | Error code. |
---message | String | Error description. |
Webhook
What is a webhook?
A webhook is not part of 17TRACK API. It's an an interface created by you in the form of a URL to receive the tracking status pushed by 17TRACK Tracking API.
Set up your webhook for 17TRACK Tracking API
Step 1 Create your Webhook URL.
- This should be done based on your own system or the platform you use. The below is a sample code in JAVA that may be helpful to you:
@RestController
class WebhookController {
WebhookController() {
}
@PostMapping("/notify")
void notify(@RequestBody String body) {
// body will be used to receive the push message
}
}
Step 2 Paste your Webhook URL to 17TRACK dashboard.
- Log in to your API account and go to https://api.17track.net/admin/settings. Click on the [Settings] button on the left, fill in the URL from step 1 on the right and click on the [Save] button.
Step 3 Do a quick test and see if it works.
- Go to the [WebHook test] section on the left, paste your Webhook URL to he input box and click on the [Test] button. If a notification in green pops up saying “Operation Done”, then it works. You can get a testing Webhook URL here https://webhook.site.
How does the push work?
- Webhook notifications are sent based on a queue machanism. It is recommended that you also use a queue to process the info received.
- Each webhook notification contains the complete info of a tracking number.
- If a 200 HTTP Status code is returned, the request was processed successfully.
- Any HTTP Status code other than 200 is considered as a failed push.
- If a notification push is failed, the system will retry another 3 times for the current package status. When it enters the next status, the system will follow the same process to push the notification and so on. See below for the retry interval:
Times of attempts | Times of retries | Retry interval (sec) |
---|---|---|
1 | - | - |
2 | 1 | 600 |
3 | 2 | 1800 |
4 | 3 | 3600 |
Notification Status & Content
TRACKING_STOPPED
- This means the number is no longer updated and no more tracking updated notification will be pushed.
- A "tracking stopped" message will be pushed if the tracking is stopped due to the system mechanism.
- You can use the retrack endpoint to restart the tracking.
Example Push
{ "event": "TRACKING_STOPPED", "data": { "number": "RR123456789CN", "carrier": 3011, "param": null, "tag": "" } }
Response Explanation:
Item | Description |
---|---|
event | Notification status. |
-number | The tracking number of which the auto-tracking process is stopped. |
-carrier | The carrier of the tracking number. |
TRACKING_UPDATED
- When the tracking number is registered successfully, and if there is a change to the package status, this notification will be triggered immediately.
Example Headers
"content-type",
"content-length",
"sign":"9a44ab6... ...4b4bf5",
... ...
Example Message Body
{
"event": "TRACKING_UPDATED",
"data": {
"number": "RR123456789CN",
"carrier": 3011,
"param": null,
"lang": null,
"destination_postal_code": null,
"origin_country": null,
"destination_country": null,
"destination_city": null,
"ship_date": null,
"shipper": null,
"consignee": null,
"phone_number_last_4": null,
"phone_number": null,
"cpf_or_cnpj": null,
"special_tracking_info": null,
"tag": "myID",
"track_info": {
"shipping_info": {
"shipper_address": {
"country": "CN",
"state": "GD",
"city": "SHENZHEN",
"street": "HARTFORD CT DISTRIBUTION CENTER",
"postal_code": "518000",
"coordinates": {
"longitude": "114.085947",
"latitude": "22.547"
}
},
"recipient_address": {
"country": "AF",
"state": null,
"city": "KABUL",
"street": null,
"postal_code": null,
"coordinates": {
"longitude": null,
"latitude": null
}
}
},
"latest_status": {
"status": "InfoReceived",
"sub_status": "InfoReceived",
"sub_status_descr": null
},
"latest_event": {
"time_iso": "2022-03-02T20:43:24-06:00",
"time_utc": "2022-03-03T02:43:24Z",
"time_raw": {
"date": "2022-03-02",
"time": "20:43:24",
"timezone": "-06:00"
},
"description": "Shipment information sent to FedEx",
"description_translation": {
"lang": "en",
"description": "Shipment information sent to FedEx"
},
"location": "NJ",
"stage": "InfoReceived",
"sub_status": "InfoReceived",
"address": {
"country": "US",
"state": "NJ",
"city": "MARLTON",
"street": null,
"postal_code": "08053",
"coordinates": {
"longitude": null,
"latitude": null
}
}
},
"time_metrics": {
"days_after_order": 7,
"days_of_transit": 7,
"days_of_transit_done": 7,
"days_after_last_update": 57,
"estimated_delivery_date": {
"source":"Official",
"from": "2022-03-02T18:43:24-06:00",
"to": "2022-03-03T19:43:24-06:00"
}
},
"milestone": [
{
"key_stage": "InfoReceived",
"time_iso": "2023-08-14T00:00:00-05:00",
"time_utc": "2023-08-14T05:00:00Z",
"time_raw": {
"date": "2023-08-14",
"time": null,
"timezone": null
}
},
{
"key_stage": "PickedUp",
"time_iso": "2023-08-15T08:46:00-05:00",
"time_utc": "2023-08-15T12:46:00Z",
"time_raw": {
"date": "2023-08-15",
"time": "08:46:00",
"timezone": "-05:00"
}
},
{
"key_stage": "Departure",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "Arrival",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "AvailableForPickup",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "OutForDelivery",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "Delivered",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "Returning",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
},
{
"key_stage": "Returned",
"time_iso": null,
"time_utc": null,
"time_raw": {
"date": null,
"time": null,
"timezone": null
}
}
],
"misc_info": {
"risk_factor": 0,
"service_type": "FedEx International Priority",
"weight_raw": "1.1 KG",
"weight_kg": "1.1",
"pieces": "1",
"dimensions": "22*20*16 CM",
"customer_number": "2459642000~270434455123~FX",
"reference_number": null,
"local_number": "270434455123",
"local_provider": "Fedex",
"local_key": 100003
},
"tracking": {
"providers_hash": 2067301750,
"providers": [
{
"provider": {
"key": 3011,
"name": "China Post",
"alias": "China Post",
"tel": null,
"homepage": "http://www.17track.net",
"country": "CN"
},
"service_type": "International Priority",
"latest_sync_status": "Success",
"latest_sync_time": "2022-06-09T05:46:31Z",
"provider_lang": "en",
"provider_tips":"",
"events_hash": -227928244,
"events": [
{
"time_iso": "2023-08-14T00:00:00-05:00",
"time_utc": "2023-08-14T05:00:00Z",
"time_raw": {
"date": "2023-08-14",
"time": null,
"timezone": null
},
"description": "At local FedEx facility",
"description_translation": {
"lang": "en",
"description": "At local FedEx facility"
},
"location": "ANCHORAGE, AK, US",
"stage": "InfoReceived",
"sub_status": "InfoReceived",
"address": {
"country": "US",
"state": "AK",
"city": "ANCHORAGE",
"street": null,
"postal_code": "99502",
"coordinates": {
"longitude": "35.86166",
"latitude": "104.195397"
}
}
}
]
}
]
}
}
}
}
Response Explanation:
Item |
Type |
Description |
---|---|---|
event | String | Notification status. |
data | Object | The response data. |
-number | String | Tracking number. |
-carrier | Int. | Carrier code |
-origin_country | String | Origin country. Use the two-letter country code in ISO 3166-1 format. Include as an additional tracking field when making a request to the /register. |
-ship_date | DateTime | Shipping date in YYYY/MM/DD format. Include as an additional tracking field when making a request to the /register. |
-destination_postal_code | String | The postal of the destination address. Include as an additional tracking field when making a request to the /register. |
-destination_country | String | Destination country.Use the two-letter country code in ISO 3166-1 format. Include as an additional tracking field when making a request to the /register. |
-destination_city | String | Destination city. Include as an additional tracking field when making a request to the /register. |
-shipper | String | Shipper name. Include as an additional tracking field when making a request to the /register. |
-consignee | String | Consignee name. Include as an additional tracking field when making a request to the /register. |
-phone_number_last_4 | String | The last digits of the shipper's or recipient's phone number. Include as an additional tracking field when making a request to the /register. |
-phone_number | String | The shipper's or recipient's phone number. Include as an additional tracking field when making a request to the /register. |
-cpf_or_cnpj | String | Individual Taxpayer Registry(CPF)/National Registry of Legal Entities(CNPJ). Include as an additional tracking field when making a request to the /register. |
-special_tracking_info | Object | This parameter format is an object, each consisting of "number_type" and "parameter". "number_type" represents different query channels provided by the carrier, and "parameter" is the corresponding value for that query channel. |
--number_type | String | Available channels for checking logistics information provided by carriers. Include as an additional tracking field when making a request to the /register. |
--parameter | String | The value of the query channel. Include as an additional tracking field when making a request to the /register. |
-tag | String | Custom tag. See tracking number registration for more info. |
-lang | String | Used to translate logistics events, specify the translation language code. |
-track_info | Object | Tracking info |
--shipping_info | Object | Location info. |
---shipper_address | Object | Location info of the origin country. |
----country | String | Country or region (capital letter). |
----state | String | State or province. |
----postal_code | String | Post code. |
----city | String | City. |
----street | String | Street. |
----coordinates | Object | Coordinates. |
-----longitude | String | longitude. |
-----latitude | String | latitude. |
---recipient_address | Object | Location info of the destination country. |
----country | String | Country or region (capital letter). |
----state | String | State or province. |
----postal_code | String | Post code. |
----city | String | City. |
----street | String | Street. |
----coordinates | Object | Coordinates. |
-----longitude | String | longitude. |
-----latitude | String | latitude. |
--latest_status | Object | The lastest status. |
---status | String | Main status. |
---sub_status | String | Sub-status. |
---sub_status_descr | String | Status description. |
--latest_event | Object | The latest event. See events set. |
--time_metrics | Object | Info related to timeliness, where estimated_delivery_date indicate a period of time. |
---days_after_order | Int. | Order Transit Time(in days) Calculation: 1. For delivered status, Order Transit Time(in days) = Delivery Date - First Event Date. 2. For non-delivered status, with tracking result, Order Transit Time(in days) = Current Date - First Event Date. 3. No tracking result, Order Transit Time(in days) = 0. |
---days_after_last_update | Int. | No Update Days: 1. For delivered, return to sender, and no result status, interval in days = 0. 2. For other cases, interval in days = Current Date - Last Event Date. |
---days_of_transit | Int. | Transit Time(in days) Calculation: For delivered status: 1. With "InTransit_PickedUp",Transit Time(in days) = Delivery Date - Pickedup Date 2. Without "InTransit_PickedUp",with "InfoReceived",Transit Time(in days) = Delivery Date - First Event Date after "InfoReceived". 3. Without both "InTransit_PickedUp" and “InfoReceived”,Transit Time(in days) = Delivery Date - First Event Date. For non-delivered status , with tracking result: 1. With “InTransit_PickedUp”,Transit Time(in days) = Current Date - Pickup Date 2. WIthout “InTransit_PickedUp",with "InfoReceived",Transit Time(in days) = Current Date - First Event Date after "InfoReceived". 3. WIthout "InTransit_PickedUp",with "InfoReceived",and only one tracking event, Transit Time(in days) = 0. 4. Without both "InTransit_PickedUp" and "InfoReceived",Transit Time(in days) = Current Date - First Event Date. No tracking result: Transit Time(in days) = 0. |
---days_of_transit_done | Int. | Delivery Time(in days) Calculation: For delivered status: 1. With "InTransit_PickedUp",Delivery Time(in days) = Delivery Date - Pickup Date 2. Without "InTransit_PickedUp",with "InfoReceived",Delivery Time(in days) =Delivery Date - First Event Date after "InfoReceived". 3. Without both "InTransit_PickedUp" and "InfoReceived",Delivery Time(in days) = Delivery Date - First Event Date. For non-delivered status: Delivery Time(in days) = 0. |
---estimated_delivery_date | Object | The estimiated date of delivery. It gives a range of dates. |
----source | String | It refers to the party who provides info for "from" and "to" sections. It will show "17TRACK" when the info is provided by 17TRACK; show "Official" when the info is provided by carrier; and show "null" when the info is provided by none. |
----from | String | The earliest estimated date of delivery (ISO format). E.g 2021-09-01T08:00:54-05:00 |
----to | String | The latest estimated date of delivery (ISO format). E.g 2021-09-01T08:00:54-05:00 |
---milestone | Array | A set of date regarding each important stage of the shipping process. Purpose: Display key nodes and their occurrence sequence and time during the shipping process. Usage: Iterate through each milestone item, recommended order: InfoReceived >> PickedUp >> Departure >> Arrival >> OutForDelivery >> Delivered. (Use AvailableForPickup, Returned, Returning as needed based on specific cases) Note: If time_iso or time_utc is null, it means the carrier did not provide event description. milestone[]. key_stage can be used to query more specific event content in tracking.providers[].events[].stage. Meanings of milestone's key_stage: 1. InfoReceived : The carrier has received the order info and is about to pick up the package from the sender. 2. PickedUp : The package has been collected by the carrier. 3. Departure : The package has departed from a port. (Usually means after customs clearance.) 4. Arrival : The package has arrived at a port. (Not certain if the customs clearance is made.) 5. AvailableForPickup : The package has arrived at the pick up point of the destination. The recipient needs to go get it. 6. OutForDelivery : The package is out for delivery. 7. Delivered : The package is delivered and signed by the recipient. 8. Returned : The package was returned to the sender. 9. Returning : The package is being returned to the sender. This not always change to "Returned" even if the process is done. |
---key_stage | String | A set of all milestones. There are 9 of them. When time_iso and time_utc are populated, it means the relevent event has happened. These stages can be use to get a big picture of the shipping process. You can know the package has gone through a flow like "InfoReceived > PickedUp > Departure > Arrival > Delivered". |
---time_iso | String | 1. The time of the stage in ISO format, transfered from the local time of the carrier. If it can not be tranfered, the original time format will show instead. 2. If the upperstream carrier provide timezone info, it will be prioritize, otherwise the carrier's HQ time will be used. 3. 2022-03-02T20:43:24-06:00 means the timezone is UTC−06:00. 4.Remove the -06:00 is removed, it means the carrier's local time. 5. See this field is in tracking.providers[].provider[].events[].time_iso. |
---time_utc | String | 1. The time of the stage in UTC format, transfered from the ISO time. 2. For example: 2022-03-03T02:43:24Z. 3. See tracking.providers[].provider[].events[].time_utc. |
---time_raw | Object | Original date & time info provided by carrier: 1. Three groups of data, including YYYY-MM-DD, HH:MM:SS, Timezone. 2. It will show "null" if carrier does not provide any data. |
----date | String | YYYY-MM-DD |
----time | String | HH:MM:SS |
----timezone | String | Timezone (If it shows "null" in Timezone section but a valid date & time in time_iso, it indicates that the Timezone info is added by 17TRACK.) |
--misc_info | Object | Package additional info. |
---risk_factor | String | Package risk factor. |
---service_type | String | Package service type |
---weight_raw | String | Original weight info. |
---weight_kg | String | Weight info in Kg. |
---pieces | String | Total pieces. |
---dimensions | String | Dimensions (length, width, height). |
---customer_number | String | The customer number of the recipient. |
---reference_number | String | A reference number. |
---local_number | String | The last-mile tracking code. |
---local_provider | String | The last-mile carrier. |
---local_key | Int. | The last-mile carrier code. |
--tracking | Object | Tracking info. |
---providers_hash | Int. | The hash value, calculated from the event content, can be used to determine if there are changes. |
---providers | Array | A set of carriers participated in the shipping process, in ascending order, with 0 being the second carrier, 1 being the first, etc. Note: When the parcel is a postal shipment, the "providers[0]" object is the destination carrier, "providers[1]" is the object is the originating carrier, " providers[0]" and "providers[1]" description, time may be duplicated. |
----provider | Object | Carrier info |
-----key | Int. | Carrier code. |
-----name | String | Carrier name. |
-----tel | String | Carrier phone number. |
-----homepage | String | Carrier website. |
-----country | String | Carrier country. |
----service_type | String | Carrier service type. |
----latest_sync_status | String | The latest status of data synchronization. Failure Success |
----latest_sync_time | String | The last time of data synchronization. |
----events_hash | Int. | The hash value of the events. |
----provider_tips | String | The carrier notice. |
----provider_lang | String | The carrier’s current tracking event language; if uncertain, it is null. |
----events | Array | The set of events. |
-----time_iso | String | The time of the event in ISO format. If there is no valid data, it shows null. |
-----time_utc | String | The time of the event in UTC format. If the time_iso is null, it shows null. |
-----time_raw | Object | Original date & time info provided by carrier: 1. Three groups of data, including YYYY-MM-DD, HH:MM:SS, Timezone. 2. It will show "null" if carrier does not provide any data. |
------date | String | YYYY-MM-DD |
------time | String | HH:MM:SS |
------timezone | String | Timezone (If it shows "null" in Timezone section but a valid date & time in time_iso, it indicates that the Timezone info is added by 17TRACK.) |
-----description | String | Event description. Including: time, shipping details, key status. |
-----description_translation | String | Describes the translation node. |
------description | String | Description of the translated event. |
------lang | String | Translation language code |
-----location | String | Location. |
-----stage | String | Stage. |
-----sub_status | String | Sub-status. |
-----address | Object | Address info. |
------country | String | Country or region. |
------state | String | State or province. |
------city | String | City. |
------street | String | Street. |
------postal_code | String | Post code. |
------coordinates | Object | coordinates. |
-------longitude | String | longitude. |
-------latitude | String | latitude. |
Create and Verify the Signature
To make sure the data you receive comes from 17TRACK, you can create a signiture by concatenating certain info given by each push notification and calculate the SHA256 value. Then you can verify that signiture as told in the Verification section below.
- The info needed to create the signature is in the sign attribute of the request header.
- The info needed to create the signature should not be changed, or the result can be different, causing the verification to fail.
Step 1 Prep the content.
Concatenate the original notification message and the API key with "/":
- The notification message:
{"event":"TRACKING_UPDATED","data":{"number":"RR123456789CN", "carrier":3011,"tag":null}}
- The security key:
After the concatenation, the result should look like this:123456ABCDEF
{"event":"TRACKING_UPDATED","data":{"number":"RR123456789CN","carrier":3011,"tag":null}}/123456ABCDEF
Step 2 Calculate SHA256.
Generate the signature by using SHA256 hex encoding. You can see a sample code in Java here:
/**
* requestText {String} The notification message
* key {String} The security key
* return {String} The signature returned
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {
String src = requestText + "/" + key;
MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));
BigInteger number = new BigInteger(1, hash);
StringBuilder hexString = new StringBuilder(number.toString(16));
while (hexString.length() < 64) {
hexString.insert(0, '0');
}
return hexString.toString();
}
Step 3 Compare the result.
If the calculated value is the same as the value returned, it means the data is coming from 17TRACK.