Getting started with ShipmentData API – nShift

ShipmentData API

Environments {{URL}}

https://customer-api.consignorportal.com/ApiGateway/ShipmentData

This is a REST API and can only be used for sending/receiving requests so is not meant to be opened in a browser.

Authentication

The API support Bearer Authentication
See this article on how to generate the ClientId and ClientSecret

Example on how to request a token

curl -X POST "https://www.consignorportal.com/idsrv/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}}"

Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjI3QjA1ODk4Nzc1OEUwMkMI1NiIsInR2...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "public_api_shipmentserver"
}

The Token is valid for 60 minuts before it expires and you have to re-authenticate

All request has to have the token in the Authorization header

curl -X POST "{{URL}}/ShipServer/ApiGateway/ShipmentData/" 
-H "Authorization: bearer {{TOKEN}}"
-H "Content-Type: application/json"
--data-raw "{}"

Postman Collection

This collection contains request & response examples for all requests:
https://documenter.getpostman.com/view/22736309/2s8YmHxQWK

In order to use these requests against your own configuration/actor you need to:

How to configure and use the Postman collection

Generate a CLIENT_ID & CLIENT_SECRET using this article:
https://helpcenter.nshift.com/hc/en-us/articles/360026218413
Select the Environment DeliveryHUB API from the top right corner in Postman
Update the Initial & Current value on the variables in the selected environment:
CLIENT_ID, CLIENT_SECRET
Remember to Save the Environment
Open the Authorization folder
Run the Authenticate request
Update any of the request and click Send

API Index

POST	Get Shipment By Barcode	../ShipmentIdentifiers/ByBarcode
POST	Get Shipment By OrderNumber	../ShipmentIdentifiers/ByOrderNumber
POST	Get Shipment By PickupCode	../ShipmentIdentifiers/ByPickupCode
POST	Get Shipments By Data Range	../ShipmentIdentifiers/ByDateRange
GET	Get Shipment Information	../:shipmentUuid
GET	Get Shipment Additional Information	../:shipmentUuid/additional-information
GET	Get Shipment Container Information	../:shipmentUuid/container-information
GET	Get Shipment Document	../:shipmentUuid/binaries/:binaryUuid
GET	Get Shipment Summary Document	../:shipmentUuid/summary-document
GET	Get Package Summary Document	../:shipmentUuid/summary-document/:packageUuid
GET	Get Events	../:shipmentUuid/events/valid
POST	Add Documents	../:shipmentUuid/documents
PUT	Add Shipment Event	../:shipmentUuid/status
PUT	Add Package Event	../:shipmentUuid/packages/:packageUuid/status
PUT	Update the Receriver Address	../:shipmentUuid/address
PUT	Update the Amounts	../:shipmentUuid/amounts
PUT	Update the References	../:shipmentUuid/references-messages
PUT	Anonymize shipment	../:shipmentUuid/anonymize
DEL	Delete a document from a shipment	../:shipmentUuid/documents/:documentUuid

API Documentation

Locate | Get Shipment By Barcode

Lookup shipments based on the barcode.

Request

GET {{URL}}/Operational/ShipmentIdentifiers/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": []
}

query: string - the barcode to search for
startDate: ISODate -
max 31 days between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00
endDate: ISODate - max 31 days between start and end date
pageSize: int - The number of items to retrieve in one batch - default is 20.
pageIndex: int - Zero-based results batch index.
installationTags: [string] - Collection of installation identifiers to be applied on search.
actorTags: [string] -
Collection of actor identifiers to be applied on search.
if the user performing the search is a customer user, and no actors list is supplied, this will be defaulted in the backend by the list of actors the user has access to.
carrierTags: [string] -
Collection of carrier identifiers to be applied on search.
if the user performing the search is a carrier user, and no carriers list is supplied, this will be defaulted in the backend by the list of carriers the user has access to.

Locate | Get Shipment By OrderNumber

Lookup shipments based on the order number or additional order number

Request

GET {{URL}}/Operational/ShipmentIdentifiers/ByOrderNumber

Request body

The request body has to be application/json and the payload uses the following keys

{
   "query": "Order Number",
   "startDate": "{{today-14days}}",
   "endDate": "{{today}}",
   "pageSize": 20,
   "pageIndex": 0,
   "installationTags": [],
   "actorTags": [],
   "carrierTags": []
}

query: string - the order number to search for
startDate: ISODate -
max 31 days between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00
endDate: ISODate - max 31 days between start and end date
pageSize: int - The number of items to retrieve in one batch - default is 20.
pageIndex: int - Zero-based results batch index.
installationTags: [string] - Collection of installation identifiers to be applied on search.
actorTags: [string] -
Collection of actor identifiers to be applied on search.
if the user performing the search is a customer user, and no actors list is supplied, this will be defaulted in the backend by the list of actors the user has access to.
carrierTags: [string] -
Collection of carrier identifiers to be applied on search.
if the user performing the search is a carrier user, and no carriers list is supplied, this will be defaulted in the backend by the list of carriers the user has access to.

Locate | Get Shipment By PickupCode

Lookup shipments based on the PickupCode.

Request

GET {{URL}}/Operational/ShipmentIdentifiers/ByPickupCode

Request body

The request body has to be application/json and the payload uses the following keys

{
   "query": "ScanApp Pickup Code",
   "startDate": "{{today-14days}}",
   "endDate": "{{today}}",
   "pageSize": 20,
   "pageIndex": 0,
   "installationTags": [],
   "actorTags": [],
   "carrierTags": []
}

query: string - the ScanApp Pickup Codeto search for
startDate: ISODate -
max 31 days between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00
endDate: ISODate - max 31 days between start and end date
pageSize: int - The number of items to retrieve in one batch - default is 20.
pageIndex: int - Zero-based results batch index.
installationTags: [string] - Collection of installation identifiers to be applied on search.
actorTags: [string] -
Collection of actor identifiers to be applied on search.
if the user performing the search is a customer user, and no actors list is supplied, this will be defaulted in the backend by the list of actors the user has access to.
carrierTags: [string] -
Collection of carrier identifiers to be applied on search.
if the user performing the search is a carrier user, and no carriers list is supplied, this will be defaulted in the backend by the list of carriers the user has access to.

Locate | Get Shipments By Data Range

Lookup shipments based on a Date Range.

Request

GET {{URL}}/Operational/ShipmentIdentifiers/ByDateRange

Request body

The request body has to be application/json and the payload uses the following keys

{
   "startDate": "{{today-14days}}",
   "endDate": "{{today}}",
   "pageSize": 20,
   "pageIndex": 0,
   "installationTags": [],
   "actorTags": [],
   "carrierTags": []
}

startDate: ISODate -
max 24 hours between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00.
endDate: ISODate - max 24 hours between start and end date
pageSize: int - The number of items to retrieve in one batch - default is 20.
pageIndex: int - Zero-based results batch index.
installationTags: [string] - Collection of installation identifiers to be applied on search.
actorTags: [string] -
Collection of actor identifiers to be applied on search.
if the user performing the search is a customer user, and no actors list is supplied, this will be defaulted in the backend by the list of actors the user has access to.
carrierTags: [string] -
Collection of carrier identifiers to be applied on search.
if the user performing the search is a carrier user, and no carriers list is supplied, this will be defaulted in the backend by the list of carriers the user has access to.
dataRangeSource -
Determines the date field to query by in case of a data range lookup
Values can be: 1 - submit date 2 - date modified

Information | Get Shipment Information

Return the main shipment information

Request

GET {{URL}}/Operational/Shipments/:shipmentUuid

shipmentUuid: string - unique identifier for identifying a Shipment.

Information | Get Shipment Additional Information

R eturn the additional shipment information, such as tracking URLs, the latest status, and ETA.

Request

GET {{URL}}/Operational/Shipments/:shipmentUuid/additional-information

shipmentUuid: string - unique identifier for identifying a Shipment.

Information | Get Shipment Container Information

Return the container information for a shipment.

Request

GET {{URL}}/Operational/Shipments/:shipmentUuid/container-information

shipmentUuid: string - unique identifier for identifying a Shipment.

Information | Get Shipment Document

Return a document attached to the shipment

Request

GET {{URL}}/Operational/Shipments/:shipmentUuid/binaries/:binaryUuid

shipmentUuid: string - unique identifier for identifying a Shipment.
binaryUuid: string - unique identifier for identifying a document attached to a shipment.

Information | Get Shipment Summary Document

Return the proof of delivery for the shipment, as a PDF file.

Request

GET {{URL}}/Operational/Shipments/:shipmentUuid/summary-document

shipmentUuid: string - unique identifier for identifying a Shipment.

Information | Get Package Summary Document

Return the proof of delivery for the package, as a PDF file.

Request

GET {{URL}}/Operational/Shipments/:shipmentUuid/summary-document/:packageUuid

shipmentUuid: string - unique identifier for identifying a Shipment.
packageUuid: string - unique identifier for identifying a package.

Update | Get Events

Return the list of valid events that can be used to send as new shipment status

Request

GET {{URL}}/Operational/Shipments/:shipmentUuid/events/valid

shipmentUuid: string - unique identifier for identifying a Shipment.

Update | Add Documents

Add one or more documents to a shipment

Request

POST {{URL}}/Operational/Shipments/:shipmentUuid/documents

shipmentUuid: string - unique identifier for identifying a Shipment.

Request body

The request body has to be application/form-data and the payload uses the following keys

{
   "file0": "base64",
   "file1": "base64"
}

file0: base64 - Each file uploaded has a maximum size of 24 mb.

Update | Add Shipment Event

Update a shipment with a new status event

Request

PUT {{URL}}/Operational/Shipments/:shipmentUuid/status

shipmentUuid: string - unique identifier for identifying a Shipment.

Request body

The request body has to be application/json and the payload uses the following keys

{
   "EventType": "6_11565",
   "Comments": "it's now delivered using postman",
   "Date": "{{today}}",
   "StorageLocation": "Location A"
}

EventType - use the method Get Events to see valid a list of valid ids
Comments - the text on the event status
Date - the date of the event status
StorageLocation - a optimal value for storage, used together with ScanApp

Update | Add Package Event

Update a package with a new status event

Request

PUT {{URL}}/Operational/Shipments/:shipmentUuid/packages/:packageUuid/status

shipmentUuid: string - unique identifier for identifying a Shipment.
packageUuid: string - unique identifier for identifying a package.

Request body

The request body has to be application/json and the payload uses the following keys

{
   "EventType": "6_11565",
   "Comments": "it's now delivered using postman",
   "Date": "{{today}}",
   "StorageLocation": "Location A"
}

EventType- use the method Get Events to see valid a list of valid ids
Comments- the text on the event status
Date - the date of the event status
StorageLocation- a optimal value for storage, used together with ScanApp

Update | Update the Receriver Address

Update the address fields on a shipment.

Request

PUT {{URL}}/Operational/Shipments/:shipmentUuid/address

shipmentUuid: string - unique identifier for identifying a Shipment.

Request body

The request body has to be application/json and the payload uses the following object

{
   "name1": "string",
   "name2": "string",
   "street1": "string",
   "street2": "string",
   "countryCode": "string",
   "state": "string",
   "region": "string",
   "county": "string",
   "district": "string",
   "city": "string",
   "erpRef": "string",
   "email": "string",
   "phone": "string",
   "mobile": "string",
   "poPostCode": "string",
   "poCity": "string",
   "postCode": "string",
   "poBox": "string",
   "attention": "string",
   "fax": "string",
   "openingHours": "string",
   "receiverRef": "string",
   "province": "string",
   "vatNo": "string",
   "voecNumber": "string",
   "typeId": 0
}

Update | Update the Amounts

Update the Amounts

Request

PUT {{URL}}/Operational/Shipments/:shipmentUuid/amounts

shipmentUuid: string - unique identifier for identifying a Shipment.

Request body

The request body has to be application/json and the payload uses the following object

{
   "price1": 0,
   "price1CurrencyCode": "string",
   "price2": 0,
   "price2CurrencyCode": "string",
   "fixedPrice": 0,
   "fixedPriceCurrencyCode": "string",
   "carrierPrice": 0,
   "carrierPriceCurrencyCode": "string"
}

Update | Update the References

Update the References

Request

PUT {{URL}}/Operational/Shipments/:shipmentUuid/references-messages

shipmentUuid: string - unique identifier for identifying a Shipment.

Request body

The request body has to be application/json and the payload uses the following object

{
   "orderNumber": "string",
   "additionalReference": "string",
   "receiverReference": "string",
   "project": "string",
   "carrierMessage": "string",
   "driverMessage": "string",
   "receiverMessage": "string"
}

Update | Anonymize the shipment

Anonymize the shipment

Request

PUT {{URL}}/Operational/Shipments/:shipmentUuid/anonymize

shipmentUuid: string - unique identifier for identifying a Shipment.

Update | Delete a document from a shipment

Delete a document from a shipment

Request

DELETE {{URL}}/Operational/Shipments/:shipmentUuid/documents/:documentUuid

shipmentUuid: string - unique identifier for identifying a Shipment.
documentUuid: string - unique identifier for identifying a Document.

HTTP status codes:

200 OK - Data successfully received and is sent for processing
401 Unauthorized - Not valid credentials
400 Bad Request - Invalid input data
500 InternalServerError - Unknown error
429 Too many requests - Exceeded the limit of calls per minute. The limit is set according to the customer's subscription.

Normalized status names

System

1000 - Created
1001 - Transmit
1002 - Deleted
1003 - Internal
1004 - Customer advised
1005 - Undelete
1007 - Onboarded to container
1008 - Offboarded from container

In Transit

2000 - In Transit
2001 - Out for delivery
2002 - Ready for pickup
2003 - Arrived at terminal/hub
2004 - Collected by carrier
2005 - Customs Clearance
2008 - Departed from terminal/hub

Delivered

3000 - Delivered
3001 - Partially delivered
3002 - Carded
3003 - Delivered to neighbor

Information

4000 - Other status
4001 - Update ETA
4002 - Change of address
4003 - Notification(s)/Advise
4004 - Booking information confirmed
4005 - Measurement/Price Update

Carrier exception

5000 - Carrier Exception
5001 - Other incident
5002 - Delayed
5003 - Damaged
5004 - Change to delivery
5005 - Misrouted
5006 - Failed delivery attempt
5007 - Return to sender
5008 - Lost
5009 - Force majeure

Receiver Exception

6000 - Other incident
6001 - Return to sender
6002 - Customer refused
6003 - No property access
6004 - Delivery canceled
6005 - Carded

Sender Exception

7000 - Other incident
7001 - Delivery canceled
7002 - Return to sender
7003 - Insufficient address
7004 - Missing booking info

ShipmentDataApi_collection.json
20 KB Download

DeliveryHub Help

ShipmentData API

API Index

API Documentation

Related articles