Tracking via API

Test tracking example file with liste below scenarios can be found here. 

Tracking can be fetched in several ways:

• SenderParcelNrs can be used to get the tracking events for up to 50 parcels.

/api/v1/tracking/sender-parcel-nrs/get-many

the client parcel numbers can be used comma separated.

• ParcelNrs can be used to get the tracking events for up to 50 parcels

/api/v1/tracking/parcel-nrs/get-many

In most cases the parcel numbers can be gotten in the response from a successful parcel creation. In some postal cases an offline UPU format parcel range is provided, in which case the client should already have the pool of parcel numbers to use

• Up to 500 tracking events not grouped by parcels with tracking-event start date and Fetch ID

/api/v1/tracking

Fetches the tracking events in cursor fashion. FetchId is a cursor position and FetchDone and NextFetchId in response is the next cursor state. StartDate is a event time started. Events are not grouped by parcels the belong to, response contains events and general parcel info in the order they have been processed by PostPlus.

Below is the detailed description of how to fetch tracking using fetchId cursor value with batch endpoint:

First ever request can be done with empty fetchId parameter, but with startDate parameter.

StartDate is used for preventing downloading the whole tracking history and starting from some sensible date in the past.

All the consecutive requests might have the same startDate parametere value, since the paging is done by using fetchId paramter.

Below is the sample response

Please note response fields

- "nextFetchId" with value "Cj7tmDjWkdoUyVmb8R8B77", that should be used in the next batch request

- "eventId" with value "WoxFW73f47o2d55PPHwzit" - this is the unique identificator of the event. One or more responses might contain events with the same eventId value, this means the event data was updated.

Then the next request should include fetchId parameter value ("fetchId=Cj7tmDjWkdoUyVmb8R8B77") that was saved from the previous response ("nextFetchId": "Cj7tmDjWkdoUyVmb8R8B77")

This allows our API to provide next page of tracking data, starting from previously saved fetchId value.

PostPlus event codes need to be used to import tracking. All available event codes can be found by sending request GET /api/v1/tracking/event-codes.

While all events come with a specific message, only the code needs to match, and the message can be adjusted.

Tracking can be imported in two different ways: with explicit event ID or one with auto-generated ID (based on event time, event parcel number etc). Both use the same API endpoint: POST api/v1/integrations/tracking-import

When the integrator has their own unique IDs, they can provide them as event IDs, which will allow them to update the specific event by sending a request with the same ID again.

The below example request contains both options. First parcel event has eventID, second one has this field left out and it will be auto generated:

The integrator needs a production integration API key, which will be provided by your PostPlus account manager.