Anmelden

nShift Help Center

Zugriff auf Sendungsinformationen und Ereignisse über die Shipment Data API

Avatar
Simon Schrader Springer
Aktualisiert

Dieser Leitfaden richtet sich an Entwickler, die eine Integration mit der nShift Shipment Data API vornehmen möchten, um Sendungsinformationen und Ereignisse programmatisch abzurufen. Wir behandeln Authentifizierung, Endpunktverwendung sowie Anfrage-/Antwortstrukturen.

 

1. Authentifizierung: Zugriffstoken erhalten

Der Zugriff auf die Shipment Data API erfordert ein gültiges OAuth 2.0 Zugriffstoken. Wir verwenden den Client Credentials Grant Type für die Server-zu-Server-Authentifizierung.

Schritte zum Erhalt eines Tokens:

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

 

Beispielanfrage:

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'

 

Erfolgreiche Antwort (200 OK):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkI0MT...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "public_api_portal_shipment_data"
}
  • Speichern Sie das access_token. Dieses Token wird im Authorization-Header für nachfolgende API-Anfragen verwendet. Tokens haben eine Ablaufzeit (expires_in). Implementieren Sie eine Logik, um das Token bei Ablauf zu erneuern.

 

2. API-Endpunkte für Sendungsdaten

Wir stellen zwei Hauptendpunkte zur Verfügung, um Sendungsinformationen abzurufen, die unterschiedliche Anwendungsfälle bedienen:

 

Für detaillierte Sendungsdaten:

  • Endpunkt:https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/Aggregated/ByBarcode
  • Methode: POST
  • Header:
    • Authorization: Bearer {YOUR_ACCESS_TOKEN}
    • Content-Type: application/json
    • Accept: application/json (oder text/plain, wenn Sie lieber Klartextantworten möchten, aber JSON wird generell empfohlen)
  • 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
}

Der Request-Body akzeptiert Parameter wie query zur Angabe des Paket-Barcodes, optionale startDate und endDate im ISO-8601-Format zur Definition eines Suchzeitraums, pageSize zur Steuerung der Ergebnisse pro Seite, pageIndex für die Paginierung (beginnend bei 0) sowie optionale Tag-Filter wie installationTags, actorTags und carrierTags.

 

Beispielantwort (200 OK - gekürzt zur Übersicht, vollständiges Beispiel siehe Originaldaten):

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

 

Für zusammengefasste Sendungsinformationen, hauptsächlich Tracking-URLs und aktuelle Status.

  • Endpunkt:
  • https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/additional-information/ByBarcode
  • Methode: POST
  • Header & Request Body: Wie zuvor.

 

Beispielantwort (200 OK - gekürzt zur Übersicht):

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



 
import requests
import json

# --- Konfiguration ---
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():
    """Ruft ein Zugriffstoken mittels Client Credentials Grant ab."""
    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()  # Hebt HTTPError bei fehlerhaften Antworten (4xx oder 5xx) hervor
    return response.json()["access_token"]

def get_shipment_data(access_token, barcode, endpoint_url):
    """Ruft Sendungsdaten vom angegebenen Endpunkt ab."""
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {
        "query": barcode,
        "startDate": "2025-01-06T06:49:59.773Z", # Beispiel-Zeitraum
        "endDate": "2025-01-07T14:49:59.773Z"   # Beispiel-Zeitraum
    }
    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("Zugriffstoken erfolgreich erhalten.")

        # Aggregierte Sendungsdaten abrufen
        aggregated_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_AGGREGATED)
        print("\n--- Aggregierte Sendungsdaten ---")
        print(json.dumps(aggregated_data, indent=2))

        # Zusätzliche Informationen abrufen
        additional_info_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_ADDITIONAL_INFO)
        print("\n--- Zusätzliche Sendungsinformationen ---")
        print(json.dumps(additional_info_data, indent=2))

    except requests.exceptions.HTTPError as e:
        print(f"HTTP-Fehler: {e}")
        print(f"Statuscode der Antwort: {e.response.status_code}")
        print(f"Antwortinhalt: {e.response.text}")
    except Exception as e:
        print(f"Ein Fehler ist aufgetreten: {e}")

Indem Sie diesem Entwicklerleitfaden folgen und die offizielle Dokumentation konsultieren, können Sie die nShift Shipment Data API effektiv integrieren, um wertvolle Sendungsinformationen und Ereignisse für Ihre Anwendungen zu erhalten.

 

 

 

Verwandte Beiträge