Develop Documentation

Get the API access key

Log in to the management console -> Settings ->Security-> Access Key, you can get the access key. If you need to change the key, you can directly operate the "Change key". If you change the key, the new key will take effect within 5 minutes. Once the key takes effect, the old one will expire immediately.

API endpoint

API endpoint: https://api.17track.net/track/v1

Data request

All API interfaces use the http(s) POST method to submit requests. The request and response data are in UTF-8 encoded JSON format. All request base addresses start with http(s)://api.17track.net/track/v1/. All requests need to be submitted with the key as the request header, with the header name 17token, as shown below (registration number request):

curl -X POST 
    --header '17token:your secret key'
    --header 'Content-Type:application/json'
    --data '[{"number":"RR123456789CN"}]'
    https://api.17track.net/track/v1/register

Data encapsulation

{
    "code": 0,
    "data": {
        "accepted":[],
        "rejected":[]
    }
}

The response results are in a unified data encapsulation format, as shown below;

Response status

HTTP status code

Error status code

The error status code is a concrete representation of the data processing result based on the return of the http status code.

Parameter format

Tracking number: The tracking number must be a continuous combination of 5 to 50 letters and numbers.

Carrier: The carrier code must be a valid shipping carrier's Key. For details, please refer to the carrier code.

Basic information

Carrier code

• Visit https://res.17track.net/asset/carrier/info/apicarrier.all.json for all available carriers currently supported. As we keep adding and supporting more and more carriers, please check and update it periodically. The relevant interfaces that are using the carrier code must be submitted by using the code "Key" in our own defined carrier information.Download carrier list.

Additional parameters for tracking

• Additional params are required to track the shipments of some carriers, please refer to the following:

Country code

• Visit https://res.17track.net/asset/carrier/info/country.all.json to get the latest country code. After getting the tracking information or receiving the push information, it is required to use the country codes of the origin and destination countries listed to correspond to the actual countries of the parcel.

Package status

Tracking status

Tracking information

Tracking information extension(Not enabled yet)

Event information

Important notes

• The tracking number of all interface requests needs to be registered first through the register interface.
• The interface frequency limit is 3req/s, a 429 error code will be returned when exceeding the limit.
• Repetitive requests for the same number with same carrier only consume one tracking quota. When it gets expired or being deleted and resubmitted, it will be recalculated.
• The system will automatically stop the tracking of parcels whose events have not been updated for 30 consecutive days or no event updates for 15 days after successful delivery;
• The system will reserve the data of numbers that are stopped for tracking for 90 days, and physically delete the corresponding data after the expiration dates.
• For stopped tracking numbers, they can be activated and re-tracked only once.

API Reference(v1.0)

Register

• 40 tracking numbers are allowed to submit for registration per time for the interface.
• POST /register

Request data example:

[
    {
        "number": "RR123456789CN",
        "extra_param":"",
        "carrier": 3011,
        "final_carrier": 21051,
        "auto_detection":false,
        "tag": "MyId"
    },
    {
        "number": "1234"
    }
]

Request data description:

Response data example:

{
    "code": 0,
    "data": {
        "accepted": [
            {
                "origin": 1,
                "number": "RR123456789CN",
                "carrier": 3011
            }
        ],
        "rejected": [
            {
                "number": "1234",
                "error": {
                    "code": -18010012,
                    "message": "The format of '1234' is invalid."
                }
            }
        ]
    }
}

Response result description:

Change Carrier

• sed to change the first carrier and the last-mile carrier. 40 tracking numbers are allowed to submit for change per time for the interface.
• POST /changecarrier

Request data example:

[
    {
        "number": "RR123456789CN",
        "carrier_old": 3011,
        "carrier_new": 3013,
        "final_carrier_old": 0,
        "final_carrier_new": 0
    }
]

Request data description:

Response data example:

{
    "code": 0,
    "data": {
        "accepted": [
            {
                "number": "RR123456789CN",
                "carrier": 3013
            }
        ],
        "rejected": []
    }
}

Response result description:

ChangeInfo

• Relevant additional information used to modify tracking.
• POST /changeinfo

Request data example：

{
    "number": "RR123456789CN",
    "carrier":3011,
    "items": {
        "param": "1234",
        "tag": "This is my order id."
    }
}

Request parameter description:

Response data example：

{
    "code": 0,
    "data": {
        "accepted": [
            {
                "number": "LW503511611CN",
                "carrier": 3011
            }
        ],
        "rejected": []
    }
}

Response parameter description:

StopTrack

• 40 tracking numbers are allowed to submit per time for the interface.
• POST /stoptrack

Request data example:

[
    {
        "number": "RR123456789CN",
        "carrier": 3011
    }
]

Request parameter description:

Response data example:

{
    "code": 0,
    "data": {
        "accepted": [
            {
                "number": "RR123456789CN",
                "carrier": 3011
            }
        ]
    }
}

Response parameter description:

Retrack

• 40 tracking numbers are allowed to submit per time for the interface.
• POST /Retrack

Request data example:

[
    {
        "number": "RR123456789CN",
        "carrier": 3011
    }
]

Request parameter description:

Response data example:

{
    "code": 0,
    "data": {
        "accepted": [
            {
                "number": "RR123456789CN",
                "carrier": 3011
            }
        ]
    }
}

Response result description:

GetTrackList

• Get tracking number list
• POST /gettracklist

Request data example:

{
    "number": "RR123456789CN",
    "carrier": 3011,
    "register_time_from": "2019-01-01 12:24:00",
    "register_time_to": "2019-02-01",
    "tracking_time_from": "2019-01-01",
    "tracking_time_to": "2019-12-01",
    "push_time_from": "2019-01-01",
    "push_time_to": "2019-12-01",
    "push_state": 0,
    "stop_time_from": "2019-01-01",
    "stop_time_to": "2019-12-01",
    "package_state": 10,
    "tracking_state": 0,
    "page_no": 1
}

Request parameter description:

Response data example:

{
    "code": 0,
    "data": {
        "accepted": [
            {
                "number": "RV929123748CN",
                "w1": 3011,
                "b": 301,
                "w2": 10011,
                "c": 1001,
                "e": 20,
                "rt": "2019-08-26 09:48:16",
                "tt": "2020-01-16 02:52:11",
                "pt": "2019-11-08 06:16:25",
                "ps": 200,
                "st": "2020-02-28 02:36:59",
                "sr": 1,
                "ir": true,
                "ts": false,
                "mc": 0,
                "tag": null
            }
        ]
    }
}

Response result description:

GetTrackInfo

• 40 tracking numbers are allowed to submit per time for the interface.
• POST /gettrackinfo

Request data example:

[
    {
        "number": "RR123456789CN",
        "carrier": 3011
    }
]

Request parameter description:

Response data example:

{
    "code": 0,
    "data": {
        "accepted": [
            {
                "number": "RM101474005CN",
                "tag": "",
                "track": {
                    "b": 301,
                    "c": 1803,
                    "e": 10,
                    "f": -1,                  
                    "w1": 3011,
                    "w2": 18031,                  
                    "z1": [
                        {
                            "a": "2015-05-13 14:47",
                            "b": null,
                            "c": "",
                            "d": "",
                            "z": "电子信息已收到"
                        }
                    ],
                    "z2": [
                        {
                            "a": "2015-05-31 00:00",
                            "b": null,
                            "c": "",
                            "d": "",
                            "z": "Distribué ANDORRE LA VIEILLE (09)."
                        }
                    ],
                    "z9": [],
                    "ygt1": 370,
                    "ygt2": 0,
                    "ygt9": 0,
                    "is1": 1,
                    "is2": 0,
                    "ln1": "zh-CHS",
                    "ln2": null,
                    "ln9": null,
                    "hs": 627236210,
                    "z0": {
                        "a": "2015-05-29 09:00",
                        "b": null,
                        "c": "BLAGOVESCH 1",
                        "d": "",
                        "z": "移交海关"
                    },
                    "ylt1": "2015-06-01 20:44:52",
                    "ylt2": "2079-01-01 00:00:00",
                    "ylt9": "2079-01-01 00:00:00",
                    "yt": "",
                    "zex": {
                        "trN": "",
                        "trC": 0
                    }
                }
            }
        ]
    }
}

Response result description:

DeleteTrack

• Delete the successfully registered tracking numbers.
• POST /deleteTrack

Request data example:

[
    {
        "number": "RR123456789CN",
        "carrier":3011
    }
]

Request parameter description:

Response data example:

{
    "code":0,
    "data":
    {
        "accepted":
        [
            {
                "number":"621366941543",
                "carrier":100271
            }
        ],
        "rejected":
        [
        ]
    }
}

Response result description:

Get a push manually

• POST /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
              }
            ]' \
    https://api.17track.net/track/v1/push

Parameter Explanation:

Example Response

{
  "code": 0,
  "data": {
    "accepted": [
      {
        "number": "RR123456789CN",
        "carrier": 3011
      }
    ]
  }
}

Response Explanation:

Webhook

Setting

Set the callback interface URL by logging into the management console -> Settings -> Webhook. If it is not set, no notification will be sent.

Notification policy: If the Webhook URL of the notification call returns http status code 200, it means that the notification call has been processed normally and will not retry, otherwise the notification call will be considered as a failure. If the notification call fails, it will retry in the next 10, 30, and 60 minutes successively. If the notification call still fails, the current change notification for the corresponding tracking number will be abandoned, while the subsequent notifications will not be affected.

Data and Sign

When the tracking event is updated or the number is no longer tracked according to the policy, the system will generate a POST request to be sent to the callback url you set on the Settings page. The push data format is uniformly adopted in the following format:

{
    "sign": "a829f039332706b9b888eba84b77bd01f425ed327d2c4a92b50bba5beb0a0260",
    "event": "TRACKING_STOPPED",
    "data": {
        "number": "RM101474005CN",
        "carrier":3011,
        "tag":""
    }
}

Data format

Sign verification

In order to ensure that the information source is pushed by 17TRACK, it is recommended to verify the sign of the received data. During the verification, splice the value of type, value of data, and the API access key with the slash: event/data/secretkey, and then calculate SHA256; if the calculated result is consistent with the sign, it means that the information source is legal.

Sign example

• The push data format is uniformly adopted in UTF-8 encoded JSON format. And parse the raw data (No formatting, spaces, or line breaks, etc. are needed). For example, the received data is:

    {"sign":"a829f039332706b9b888eba84b77bd01f425ed327d2c4a92b50bba5beb0a0260","event":"TRACKING_STOPPED","data":{"number":"RM101474005CN","carrier":3011}}
  

• then the parsed result would be:

    "event":"TRACKING_STOPPED"
  
    "data":{"number":"RM101474005CN","carrier":3011,"tag":""}
  

• If the secret key is 6A8D7CFC3F7A41149E0A4EE8ABD0DD8A, then the data to be signed would be

    TRACKING_STOPPED/{"number":"RM101474005CN","carrier":3011,"tag":""}/6A8D7CFC3F7A41149E0A4EE8ABD0DD8A
  

• Pass this data through SHA256 and use hexadecimal encoding. If the calculated result is consistent with sign, means the data is valid.

Notification type

Tracking stopped

{
    "sign": "a829f039332706b9b888eba84b77bd01f425ed327d2c4a92b50bba5beb0a0260",
    "event": "TRACKING_STOPPED",
    "data": {
      "number": "RM101474005CN",
      "carrier": 3011,
      "tag":""
    }
}

Tracking updated

{
    "sign": "34f40c8fc37f9a7100c65215b0df85c58cc4880cf2e832fe91c86de1bc00b181",
    "event": "TRACKING_UPDATED",
    "data": {
        "number": "STOAA0000272952YQ",
        "tag": "",
        "track": {
            "b": 301,
            "c": 2105,
            "e": 10,
            "f": -1,
            "w1": 190316,
            "w2": 0,
            "is1": 1,
            "is2": 0,
            "hs": 730243286,
            "ln1": "en",
            "ln2": null,
            "ln9": "en",
            "ygt1": 366,
            "ygt2": 0,
            "ygt9": 423,
            "ylt1": "2020-05-11 12:05:58",
            "ylt2": "2079-01-01 00:00:00",
            "ylt9": "2020-05-11 12:05:58",
            "yt": "",
            "z0": {
                "a": "2020-05-07 10:19",
                "b": null,
                "c": "",
                "d": "BLOOMINGTON, CA 92316",
                "z": "Departed Shipping Partner Facility, USPS Awaiting Item -> Your item departed a shipping partner facility at 10:19 am on May 7, 2020 in BLOOMINGTON, CA 92316. This does not indicate receipt by the USPS or the actual mailing date."
            },          
            "z1": [
                {
                    "a": "2020-05-07 10:19",
                    "b": null,
                    "c": "",
                    "d": "BLOOMINGTON, CA 92316",
                    "z": "Departed Shipping Partner Facility, USPS Awaiting Item -> Your item departed a shipping partner facility at 10:19 am on May 7, 2020 in BLOOMINGTON, CA 92316. This does not indicate receipt by the USPS or the actual mailing date."
                },
                {
                    "a": "2020-05-05 16:49",
                    "b": null,
                    "c": "",
                    "d": "BLOOMINGTON, CA 92316",
                    "z": "Arrived Shipping Partner Facility, USPS Awaiting Item"
                },
                {
                    "a": "2020-04-12 21:16",
                    "b": null,
                    "c": "",
                    "d": "FREMONT, CA 94538",
                    "z": "Picked Up by Shipping Partner, USPS Awaiting Item"
                }
            ],
            "z2": [],
            "z9": [
                {
                    "a": "2020-04-13 17:07",
                    "b": null,
                    "c": "China, Shenzhen",
                    "d": "",
                    "z": "Item inbound in sorting center."
                },
                {
                    "a": "2020-04-13 17:02",
                    "b": null,
                    "c": "China, Shenzhen",
                    "d": "",
                    "z": "Item accepted."
                }
            ],          
            "zex": {
                "trN": "92612927005099010009150135",
                "trC": 21051
            }
        }
    }
}