1. What is logistics tracking

Logistics tracking is a crucial tool for monitoring the transportation process, enabling users to track transportation routes, exceptions, and major status changes.

The main features of the Tracking API include:

• Automatic Monitoring: Once a tracking number is registered, it is monitored automatically with query results being pushed without consuming additional quotas. Note: This feature operates asynchronously and is not suitable for front-end web pages, Mini Programs, or Apps.
• Enterprise-level Capacity: The Tracking API offers enterprise-level data processing capabilities, allowing for the registration of 400,000 tracking numbers per hour.
• Global Carrier Integration: The Tracking API supports integration with over 2000 global carriers, providing unified calling methods, response structures, and status nodes, effectively reducing development costs.
• Data Management Best Practices: It is highly recommended to store logistics information on your server or storage service.
• Unique Data Identification: Each piece of data is uniquely identified through the combination of Tracking Number + Carrier.
• Operational Process Overview: The operation process includes Shipment Subscription > Periodic Tracking > Shipment Status Changes Examination > Result Pushing.

2. Before use

2.1 Create a 17TRACK account

API accounts are not environment-specific. It is recommended to maintain separate API accounts for testing and production environments to ensure environment-specific configurations and data integrity. Please visit 17TRACK-Api to open an account.

 

2.2 Tracking number and Carrier code

• Visit 17TRACK to verify the availability of the prepared tracking number
• Visit Carriers to check supported carriers
• What is a Carrier Code? The carrier code is a parameter specification developed specifically for use with the Tracking API. You can find more information at Carrier Code. For example, the carrier code for USPS is 21051.

3. Integration Guide

3.1 Non-third-party systems integration

Target User

The following integration guide is specifically for leading logistics providers, merchants, service providers, and system providers who have their own proprietary systems and IT development teams.

Step 1

(For a quick test, you can verify the pushing via https://webhook.site)

1. Ensure that your server is accessible from the public network to receive tracking updates. This may require adjusting your firewall and gateway configurations to allow incoming connections from 17TRACK's servers.
2. Develop an interface that can receive tracking information and ensure it can handle multiple simultaneous requests. It's advisable to distribute data using independent services such as queues or caches for improved scalability.
3. Implement signature verification in your information-receiving interface to confirm the authenticity and integrity of the data received from 17TRACK. Refer to Verify The Signature for guidance. Sample code is provided below:

/**
* 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 2

1. Obtain the API key by logging in and visiting the API settings page at Api-Settings.
2. To set up the interface for receiving data, login and go to the API settings page at Api-settings. Then input the interface URL in the WebHook section.

Step 3

1. Call the registration interface (/register) to subscribe to tracking numbers. It is recommended to pass the data ID in the business system through a tag to facilitate future use of push results. (Interface reference: Register Tracking Number)

Step 4

1. Monitor the information-receiving interface operation. To ensure tracking results are used effectively and in a timely manner by the business end, please note: that data may be continuously pushed in concurrent states, with each push containing the full dataset. If normal reception fails and a temporary non-200 status code is returned, 17TRACK provides compensatory pushes, as detailed here: how does the push work

   If tracking results cannot be found, it may be due to the following scenarios:

   • Tracking is in progress. (Under normal circumstances, initial tracking results should be available within 1 minute, with subsequent tracking performed 3 to 4 times every 24 hours until delivery.)
   • Incorrect tracking number. In this case, call the Delete Track Interface (/deletetrack) and then re-subscribe.
   • Incorrect carrier. In this case, call the Change Carrier interface (/changecarrier) to update the carrier.
   • An abnormality in the carrier's interface.
   • Carriers have not updated the tracking data.
   • Additional tracking parameters are missing. When subscribing, it's necessary to include additional tracking parameters for certain carriers, such as cell phone numbers and zip codes.
   • Carriers have not updated their data for 30 consecutive days. In this case, 17TRACK will automatically stop tracking.

3.2 Third-party systems integration

Target User

The following integration guide is designed for small to medium-sized logistics providers and medium-sized merchants who utilize third-party ERP, TMS, WMS, and CRM systems

Step 1

(If only for a quick test, you can verify the pushing via https://webhook.site)

1. Please confirm with the system provider whether the current system supports receiving push tracking data via the Webhook method. [Different from self-developed systems]
2. Please confirm with the system provider if an alternative solution is available in case push is not supported: call the gettrackinfo interface (/gettrackinfo) to retrieve the data at regular intervals. (Note: This method cannot guarantee the same data return efficiency as the push method and is also not recommended by 17TRACK.) [Different from self-developed systems]
3. Please confirm with the system provider whether 17TRACK API access is supported. If supported, then confirm whether the current integrated version meets the business demands. If not, please negotiate with the system provider to integrate another version. [Different from self-developed systems]
4. If push is supported, then complete the signature verification logic in the information-receiving interface to ensure that the information source is safe and valid. Please refer to Verify the signature, example code is as follows:

/**
* 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 2

1. Get the API key: Log in to the API console, get the key on the Settings page, and provide the key to the system provider responsible for integrating. (See Api-Settings)
2. Skip this step if the system provider does not support the push method. If it does, contact the system provider to provide the push interface URL. (See Api-Settings)

Step 3

1. Call the registration interface (/register) to subscribe to tracking numbers. It is recommended for the system provider to pass the data ID in the business system through a tag to facilitate future use of push results. (Interface reference: Register Tracking Number)

Step 4

1. Please log in to the system you are using and review the results in the Tracking Module. If needed, seek assistance and answers from the system provider's customer service.
2. Monitor the information-receiving interface operation. To ensure that tracking results are timely and effectively utilized by the business end, please note: that data may be continuously pushed in concurrent states, with each push containing the full dataset. In cases where normal reception fails and a temporary non-200 status code is returned, 17TRACK provides compensatory pushes, as detailed here: how does the push work

If tracking results cannot be found, it may be due to the following scenarios:

• Tracking is in progress. (Under normal circumstances, initial tracking results should be available within 1 minute, with subsequent tracking performed 3 to 4 times every 24 hours until delivery.)
• Incorrect tracking number. In this case, call the Delete Track Interface (/deletetrack) and then re-subscribe.
• Incorrect carrier. In this case, call the Change Carrier interface (/changecarrier) to update the carrier.
• An abnormality in the carrier's interface.
• Carriers have not updated the tracking data.
• Additional tracking parameters are missing. When subscribing, it's necessary to include additional tracking parameters for certain carriers, such as cell phone numbers and zip codes.
• Carriers have not updated their data for 30 consecutive days. In this case, 17TRACK will automatically stop tracking.

4. Versions

Main versions

Difference	V1.0	V2.0 (May 2022)
Request Address	https://api.17track.net/track/v1	https://api.17track.net/track/v2
Registration interface (/register) simplifies auto-recognition operations	{ carrier : null , auto_detection : true }	{ carrier : null }
Simplified signature verification	TRACKING_STOPPED/ {"number":"RM101474005CN", "carrier":3011,"tag":""} /6A8D7CFC3F7A41149E0A4EE8ABD0DD8A	{"event":"TRACKING_UPDATED", "data":{"number":"RR123456789CN", "carrier":3011,"tag":null}} /123456ABCDEF
Response structuring + node semantics	Not supported	Supported
Independent query additional parameters	Used in conjunction with a tracking number	Independent parameter
Origin and Destination	Not supported	Supported
Timeliness information	Not supported	Supported
Status	7 status	9 main status, 27 sub-status
Attachment Information	Not supported	Weight, volume, etc. (if supported by the carrier).
Carrier information	Not supported	Name, alias, official phone number, official website, etc.
Translation of events	Not supported	8 languages supported

Sub Versions

v2.1 (Updated on August 2023) :

1. Added 3 clearance sub-states.
2. Added event status node.
3. The registration interface supports order number and note parameters.
4. Added order number, time limit, and other information to gettracklist interface.

v2.2 (Updated on October 2023) :

1. Incorporate the raw information structure for the timing of the logistics event.