Updating package

Update the package to get the latest checkpoints and other information about it from delivery services. The update takes place in two steps:

Stage 1 — starting package update process

Request:

POST /packages/update?trackNumber={trackNumber}

Required GET request parameters:

Parameter Type Description
trackNumber String Package tracking number

Example of a successful response

After the request is executed, the package information will be updated on the server by queue order.

The response will contain a hash of the package information's current status. This is required for the second step of the update to check for the availability of updated data and update completion .

        
{
    "code": 200,
    "payload": "95e4adc3"
}
        
    

Error response codes

Followed by 400 HTTP status code. Possible values:

Code Description
903 Failed to update the package. Not enough time has passed since the last update, or the package has already been delivered. Followed by the date of the next possible update in 'payload' if an update is possible
909 Failed to update the package. The maximum number of packages allowed is currently being updated. Wait for the next package to complete the update and repeat the request

Error codes possible with HTTP status code other than 400:

Code Description
404 Package with the specified tracking number not found

 

 

Stage 2 — checking package update progress

Information about the package status can be checked by several suitable delivery services at a time. Some return the result faster than others, while others do so more slowly. We update the information immediately upon receiving responses from the delivery services' servers..

After starting the update process, if you need the update results while running your software, you can use this request, sending it periodically (no more than 1 request per 30 seconds) until the response value updating equals false, which means the update process has finished.

If the updating value in the response equals true, it means that package updating process has not been completed yet and, if necessary, the request must be repeated with a new value, hash, received in the response to the previous request .

If you also need to receive information as it is updated, use the hash value from the response and compare it to the current one. If they differ, it means the info was partially or fully updated..

There's no need to run the second step of the update. The package will update successfully in the background, which may be useful if you need real-time updated package data. In other cases, if you need to be notified when the update is completed, you can use WebHook, for example.

Request:

GET /packages/updating-status?trackNumber={trackNumber}&hash={hash}

Required GET request parameters:

Parameter Type Description
trackNumber String Package tracking number
hash String Hash of the current package state information obtained at the first update step

Example of a successful response

        
{
    "code": 200,
    "payload": {
        "updating": false,
        "hash": "95e4adc3",
        "package": {
            "created_at": "2021-07-06T13:46:25+03:00",
            "updated_at": "2021-07-06T13:46:25+03:00",
            "started_tracking_at": "2021-07-06T13:46:25+03:00",
            "track_number": "UA937578848US",
            "origin": null,
            "destination": null,
            "last_status": "Receiving status...",
            "status": -1,
            "checkpoints": [
                {
                    "id": "",
                    "date": "2021-07-06T13:46:25+03:00",
                    "title": "Tracking started",
                    "location": "The package most likely isn't shipped yet",
                    "latitude": null,
                    "longitude": null,
                    "courier_id": null
                }
            ],
            "last_status_date": "2021-07-06T13:46:25+03:00",
            "est_delivery_date_from": null,
            "est_delivery_date_to": null,
            "extra_track_numbers": [],
            "hash": "f25370e9",
            "consolidated_track_number": null,
            "consolidation_date": null,
            "destination_country_code": "ru",
            "updating": false,
            "last_tracking_date": null,
            "days_on_way": 1,
            "weight": null,
            "extra_info": [],
            "couriers_ids": [
                1,
                4,
                10,
                366
            ],
            "courier_id": null,
            "info": []
        }
    }
}
        
    

Response parameter description:

Parameter Type Description
updating Boolean Flag indicating the current package update status.
true stands for 'package is still being updated', false stands for 'update completed'.
When the value is false, you must stop sending update progress check requests immediately.
hash String Hash of the current package information.
If the value differs from the one you sent in the request, and the updating value in the response is true, use the new hash for subsequent requests as part of the current package update process.
package Package | null Package object with updated information. If no information was updated compared to the hash sent in the request, and the update has not been completed yet, the value will be null.

Error response codes

Followed by 400 HTTP status code. Possible values:

Code Description
903 Failed to update the package. Not enough time has passed since the last update, or the package has already been delivered. Followed by the date of the next possible update in 'payload' if an update is possible
909 Failed to update the package. The maximum number of packages allowed is currently being updated. Wait for the next package to complete the update and repeat the request
910 Package update progress check requests are too frequent. Repeat the request later.

Error codes possible with HTTP status code other than 400:

Code Description
404 Package with the specified tracking number not found