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"
          }
        }
      ]
    }
  }
]

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)

# --- Pseudocode for accessing nShift Shipment Data API ---

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.