This article explains how to retrieve a POD image associated with a shipment using the ShipmentData API. The process involves two API calls: one to get shipment details and another to retrieve the image itself.
Authentication
If you have not used the ShipmentData API before, you must start by creating a bearer token for authentication.
- Log into nShift Portal with your Owner user.
- Go to Settings > API Configuration > Clients and click Add.
- Name the new entry and add a description.
- Check the Enabled box.
- Set the Allowed Scopes to Portal Shipment Data API (public_api_portal_shipment_data) and click Save.
- The Client ID and Client Secret must be copied and stored locally.
- Request an access token using the Client ID and Client secret.
Example of how to request a token:
curl -X POST "https://account.nshiftportal.com/idp/connect/token"
--header "Content-Type: application/x-www-form-urlencoded"
--data-urlencode "grant_type=client_credentials"
--data-urlencode "client_id={{CLIENT_ID}}"
--data-urlencode "client_secret={{CLIENT_SECRET}}"
The token is valid for 60 minutes and must be included in the header of all requests to the ShipmentData API. For more detailed step-by-step instructions with images, see API configuration setup
Getting the Shipment details
Start by making a POST request to get the shipment details. This can be done by using the barcode as in the example below. It is also possible to use other query parameters. See the list of methods here.
BaseURL: https://api.nshiftportal.com/track/shipmentdata
Request
POST {{URL}}/Operational/Shipments/ByBarcode
Request body
The request body has to be application/json and the payload uses the following keys
{
"query": "{{SHIPMENTNUMBER}}",
"startDate": "{{today-14days}}",
"endDate": "{{today}}",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
The response contains your shipment data. You need the Shipment UUID and the Binary UUID to retrieve the POD image.
The Shipment UUID is located at the top of the shipment object. The shipment object includes a binaries array that contain objects, each with a UUID representing a binary file like an image.
Retrieving the image
Once you have both the shipment UUID and the binary UUID, send a GET request to the following endpoint to download the image:
Request
GET {{URL}}/Operational/Shipments/:shipmentUuid/binaries/:binaryUuid?isSigned=false
Example:
/Operational/Shipments/daf511e0-367b-4786-9ad3-613858587644/binaries/2fc5a12a-73c7-4c9c-9762-38f9a7c059bc?isSigned=false
The successful response (HTTP 200 OK) will contain the image data in the response body.