Sign in
nShift Help Center

Accessing Shipment Information and Events via the Shipment Data API

Avatar
Simon Schrader Springer
Updated

This guide is for developers looking to integrate with the nShift Shipment Data API to programmatically retrieve shipment information and events. We'll cover authentication, endpoint usage, request/response structures.

 

1. Authentication: Obtaining an Access Token

Access to the Shipment Data API requires a valid OAuth 2.0 access token. We utilize the Client Credentials grant type for server-to-server authentication.

Steps to obtain a token:

  • Endpoint: https://account.nshiftportal.com/idp/connect/token
  • Method: POST
  • Headers:
    • Content-Type: application/x-www-form-urlencoded
  • Request Body (form-urlencoded):
    • grant_type=client_credentials
    • client_id={YOUR_CLIENT_ID}
    • client_secret={YOUR_CLIENT_SECRET}

 

Example Request:

curl -X POST \
  'https://account.nshiftportal.com/idp/connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

 

Successful Response (200 OK):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkI0MT...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "public_api_portal_shipment_data"
}
  • Store the access_token. This token will be used in the Authorization header for subsequent API requests. Tokens have an expiration time (expires_in). Implement logic to refresh the token when it expires.

 

2. API Endpoints for Shipment Data

We provide two primary endpoints for retrieving shipment information, each serving different use cases:

 

For detailed shipment data:

  • Endpoint:https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/Aggregated/ByBarcode)
  • Method: POST
  • Headers:
    • Authorization: Bearer {YOUR_ACCESS_TOKEN}
    • Content-Type: application/json
    • Accept: application/json (or text/plain if you prefer plain text responses, but JSON is generally recommended)
  • Request Body (JSON):
{
  "query": "00370733741693409071",
  "startDate": "2025-01-06T06:49:59.773Z",
  "endDate": "2025-01-07T14:49:59.773Z",
  "pageSize": 20,
  "pageIndex": 0,
  "installationTags": [],
  "actorTags": [],
  "carrierTags": [],
  "dateRangeSource": 1
}

The request body accepts parameters such as query to specify the package barcode, optional startDate and endDate in ISO 8601 format for defining a search period, pageSize to control results per page, pageIndex for pagination (starting from 0), and optional tag filters like installationTags, actorTags, and carrierTags.

 

Example Response (200 OK - truncated for brevity, see full example in original data):

[
  {
    "shipment": {
      "uuid": "17ace13f-8b07-4ef3-b3e7-f78389514e20",
      "number": "70733741693409060",
      "shipmentType": 1,
      "shipmentTypeName": "Normal",
      // ... other shipment details ...
      "events": [
        {
          "uuid": "4e35c2a7-5c43-4b4b-80c3-0ba54d8a5f52",
          "configurationName": "Printed",
          "normalizedStatusName": "Created",
          "date": "2025-01-07T09:57:05.593+00:00"
        }
        // ... more events ...
      ],
      "lines": [
        {
          "packages": [
            {
              "number": "00370733741693409071",
              "events": [
                {
                  "configurationName": "Damaged",
                  "normalizedStatusName": "Delivered",
                  "date": "2025-01-07T10:58:17.363+01:00"
                }
                // ... more package events ...
              ]
            }
          ]
        }
      ]
      // ... more shipment details ...
    },
    "additionalInformation": {
      "trackingUrls": [],
      "insuranceClaimUrl": "",
      "latestStatuses": [
        {
          "shipmentUuid": "17ace13f-8b07-4ef3-b3e7-f78389514e20",
          "shipmentNumber": "70733741693409060",
          "status": {
            "normalizedStatusName": "Delivered",
            "date": "2025-01-07T10:58:17.363+01:00"
          }
        },
        {
          "shipmentUuid": "17ace13f-8b07-4ef3-b3e7-f78389514e20",
          "shipmentNumber": "70733741693409060",
          "packageUuid": "972f6fbe-ee53-45a1-ad92-ad15e9d523e3",
          "packageNumber": "00370733741693409071",
          "status": {
            "normalizedStatusName": "Delivered",
            "date": "2025-01-07T10:58:17.363+01:00"
          }
        }
      ],
      "deliveryStart": "2025-01-01T02:37:45.562Z",
      "deliveryEnd": "2025-01-10T19:18:10.742Z",
      "deliveryWindowSource": 4
    }
  }
]

 

For summarized shipment information, primarily tracking URLs and latest statuses.

  • Endpoint:
  • https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/additional-information/ByBarcode)
  • Method: POST
  • Headers & Request Body: Same as before.

 

Example Response (200 OK - truncated for brevity):

[
  {
    "trackingUrls": [],
    "insuranceClaimUrl": "",
    "latestStatuses": [
      {
        "shipmentUuid": "17ace13f-8b07-4ef3-b3e7-f78389514e20",
        "shipmentNumber": "70733741693409060",
        "status": {
          "normalizedStatusName": "Delivered",
          "date": "2025-01-07T10:58:17.363+01:00"
        }
      },
      {
        "shipmentUuid": "17ace13f-8b07-4ef3-b3e7-f78389514e20",
        "shipmentNumber": "70733741693409060",
        "packageUuid": "972f6fbe-ee53-45a1-ad92-ad15e9d523e3",
        "packageNumber": "00370733741693409071",
        "status": {
          "normalizedStatusName": "Delivered",
          "date": "2025-01-07T10:58:17.363+01:00"
        }
      }
    ]
  }
]

 

3. Code Examples (Python)



 
import requests
import json

# --- Configuration ---
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
TOKEN_ENDPOINT = "https://account.nshiftportal.com/idp/connect/token"
SHIPMENT_DATA_ENDPOINT_AGGREGATED = "https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/Aggregated/ByBarcode"
SHIPMENT_DATA_ENDPOINT_ADDITIONAL_INFO = "https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/additional-information/ByBarcode"
BARCODE_TO_TRACK = "00370733741693409071"

def get_access_token():
    """Retrieves an access token using Client Credentials grant."""
    data = {
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET
    }
    headers = {"Content-Type": "application/x-www-form-urlencoded"}
    response = requests.post(TOKEN_ENDPOINT, headers=headers, data=data)
    response.raise_for_status()  # Raise HTTPError for bad responses (4xx or 5xx)
    return response.json()["access_token"]

def get_shipment_data(access_token, barcode, endpoint_url):
    """Retrieves shipment data from the specified endpoint."""
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {
        "query": barcode,
        "startDate": "2025-01-06T06:49:59.773Z", # Example date range
        "endDate": "2025-01-07T14:49:59.773Z"   # Example date range
    }
    response = requests.post(endpoint_url, headers=headers, json=payload)
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    try:
        token = get_access_token()
        print("Access Token obtained successfully.")

        # Get Aggregated Shipment Data
        aggregated_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_AGGREGATED)
        print("\n--- Aggregated Shipment Data ---")
        print(json.dumps(aggregated_data, indent=2))

        # Get Additional Information
        additional_info_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_ADDITIONAL_INFO)
        print("\n--- Additional Shipment Information ---")
        print(json.dumps(additional_info_data, indent=2))

    except requests.exceptions.HTTPError as e:
        print(f"HTTP Error: {e}")
        print(f"Response Status Code: {e.response.status_code}")
        print(f"Response Body: {e.response.text}")
    except Exception as e:
        print(f"An error occurred: {e}")

By following this developer guide and consulting the official documentation, you can effectively integrate with the nShift Shipment Data API to access valuable shipment information and events for your applications.

 

 

Related articles