Deze gids is bedoeld voor ontwikkelaars die willen integreren met de nShift Shipment Data API om programmatisch verzendinformatie en gebeurtenissen op te halen. We behandelen authenticatie, het gebruik van endpoints, en de structuur van verzoeken/antwoorden.

1. Authenticatie: verkrijgen van een toegangstoken

Toegang tot de Shipment Data API vereist een geldig OAuth 2.0 toegangstoken. We gebruiken het Client Credentials grant type voor server-naar-server authenticatie.

Stappen om een token te verkrijgen:

• Endpoint: https://account.nshiftportal.com/idp/connect/token
• Methode: 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}

Voorbeeldverzoek:

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'

Succesvolle reactie (200 OK):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkI0MT...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "public_api_portal_shipment_data"
}

• Sla het access_token op. Dit token wordt gebruikt in de Authorization header voor volgende API-verzoeken. Tokens hebben een vervaltijd (expires_in). Implementeer logica om het token te vernieuwen wanneer het vervalt.

2. API-endpoints voor verzendgegevens

We bieden twee primaire endpoints voor het ophalen van verzendinformatie, elk voor verschillende gebruikssituaties:

Voor gedetailleerde verzendgegevens:

• Endpoint:https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/Aggregated/ByBarcode)
• Methode: POST
• Headers:
  • Authorization: Bearer {YOUR_ACCESS_TOKEN}
  • Content-Type: application/json
  • Accept: application/json (of text/plain als u liever platte tekstantwoorden wilt, maar JSON wordt over het algemeen aanbevolen)
• 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
}

De request body accepteert parameters zoals query om de pakketbarcode te specificeren, optionele startDate en endDate in ISO 8601-formaat voor het definiëren van een zoekperiode, pageSize om het aantal resultaten per pagina te regelen, pageIndex voor paginering (beginnend bij 0), en optionele tagfilters zoals installationTags, actorTags en carrierTags.

Voorbeeldantwoord (200 OK - ingekort voor de leesbaarheid, zie volledig voorbeeld in originele data):

[
  {
    "shipment": {
      "uuid": "17ace13f-8b07-4ef3-b3e7-f78389514e20",
      "number": "70733741693409060",
      "shipmentType": 1,
      "shipmentTypeName": "Normal",
      // ... andere verzenddetails ...
      "events": [
        {
          "uuid": "4e35c2a7-5c43-4b4b-80c3-0ba54d8a5f52",
          "configurationName": "Printed",
          "normalizedStatusName": "Created",
          "date": "2025-01-07T09:57:05.593+00:00"
        },
        // ... meer gebeurtenissen ...
      ],
      "lines": [
        {
          "packages": [
            {
              "number": "00370733741693409071",
              "events": [
                {
                  "configurationName": "Damaged",
                  "normalizedStatusName": "Delivered",
                  "date": "2025-01-07T10:58:17.363+01:00"
                }
                // ... meer pakketgebeurtenissen ...
              ]
            }
          ]
        }
      ]
      // ... meer verzenddetails ...
    },
    "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"
          }
        }
      ]
    }
  }
]

Voor samengevatte verzendinformatie, voornamelijk tracking-URL's en laatste statussen.

• Endpoint:
• https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/additional-information/ByBarcode)
• Methode: POST
• Headers & Request Body: hetzelfde als hierboven.

Voorbeeldantwoord (200 OK - ingekort voor de leesbaarheid):

[
  {
    "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. Codevoorbeelden (Python)

import requests
import json

# --- Configuratie ---
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():
    """Haalt een toegangstoken op via 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()  # Geeft HTTPError bij slechte reacties (4xx of 5xx)
    return response.json()["access_token"]

def get_shipment_data(access_token, barcode, endpoint_url):
    """Haalt verzendgegevens op van het opgegeven endpoint."""
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {
        "query": barcode,
        "startDate": "2025-01-06T06:49:59.773Z", # Voorbeeld datumbereik
        "endDate": "2025-01-07T14:49:59.773Z"   # Voorbeeld datumbereik
    }
    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("Toegangstoken succesvol verkregen.")

        # Verkrijg geaggregeerde verzendgegevens
        aggregated_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_AGGREGATED)
        print("\n--- Geaggregeerde verzendgegevens ---")
        print(json.dumps(aggregated_data, indent=2))

        # Verkrijg aanvullende informatie
        additional_info_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_ADDITIONAL_INFO)
        print("\n--- Aanvullende verzendinformatie ---")
        print(json.dumps(additional_info_data, indent=2))

    except requests.exceptions.HTTPError as e:
        print(f"HTTP-fout: {e}")
        print(f"Response statuscode: {e.response.status_code}")
        print(f"Response body: {e.response.text}")
    except Exception as e:
        print(f"Er is een fout opgetreden: {e}")

Door deze ontwikkelaarsgids te volgen en de officiële documentatie te raadplegen, kunt u effectief integreren met de nShift Shipment Data API om waardevolle verzendinformatie en gebeurtenissen te verkrijgen voor uw toepassingen.