Denne vejledning er til udviklere, der ønsker at integrere med nShift Shipment Data API for programmatisk at hente forsendelsesinformation og hændelser. Vi gennemgår autentificering, brug af endpoints samt forespørgsels- og svarstrukturer.

1. Autentificering: Hentning af et adgangstoken

Adgang til Shipment Data API kræver et gyldigt OAuth 2.0 adgangstoken. Vi anvender Client Credentials grant type til server-til-server autentificering.

Trin til at hente et token:

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

Eksempel på forespørgsel:

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'

Succesfuldt svar (200 OK):

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

• Gem access_token. Dette token bruges i Authorization-headeren ved efterfølgende API-forespørgsler. Tokens har en udløbstid (expires_in). Implementer logik til at forny token, når det udløber.

2. API-endpoints for forsendelsesdata

Vi tilbyder to primære endpoints til at hente forsendelsesinformation, hver med forskellige anvendelsestilfælde:

For detaljerede forsendelsesdata:

• Endpoint:https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/Aggregated/ByBarcode)
• Metode: POST
• Headers:
  • Authorization: Bearer {YOUR_ACCESS_TOKEN}
  • Content-Type: application/json
  • Accept: application/json (eller text/plain hvis du foretrækker svar i almindelig tekst, men JSON anbefales generelt)
• 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
}

Request body accepterer parametre som query til at angive pakkens stregkode, valgfrie startDate og endDate i ISO 8601 format til at definere en søgeperiode, pageSize til at styre antal resultater pr. side, pageIndex til pagination (startende fra 0) og valgfrie tag-filtre som installationTags, actorTags og carrierTags.

Eksempel på svar (200 OK - forkortet for overskuelighed, se fuldt eksempel i original data):

[
  {
    "shipment": {
      "uuid": "17ace13f-8b07-4ef3-b3e7-f78389514e20",
      "number": "70733741693409060",
      "shipmentType": 1,
      "shipmentTypeName": "Normal",
      // ... andre forsendelsesdetaljer ...
      "events": [
        {
          "uuid": "4e35c2a7-5c43-4b4b-80c3-0ba54d8a5f52",
          "configurationName": "Printed",
          "normalizedStatusName": "Created",
          "date": "2025-01-07T09:57:05.593+00:00"
        },
        // ... flere hændelser ...
      ],
      "lines": [
        {
          "packages": [
            {
              "number": "00370733741693409071",
              "events": [
                {
                  "configurationName": "Damaged",
                  "normalizedStatusName": "Delivered",
                  "date": "2025-01-07T10:58:17.363+01:00"
                }
                // ... flere pakkehændelser ...
              ]
            }
          ]
        }
      ]
      // ... flere forsendelsesdetaljer ...
    },
    "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 opsummeret forsendelsesinformation, primært tracking-URL'er og seneste statusser.

• Endpoint:
• https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/additional-information/ByBarcode)
• Metode: POST
• Headers & Request Body: Samme som før.

Eksempel på svar (200 OK - forkortet for overskuelighed):

[
  {
    "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. Kodeeksempler (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():
    """Henter et adgangstoken ved brug af 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()  # Kaster HTTPError ved dårlige svar (4xx eller 5xx)
    return response.json()["access_token"]

def get_shipment_data(access_token, barcode, endpoint_url):
    """Henter forsendelsesdata fra det angivne endpoint."""
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {
        "query": barcode,
        "startDate": "2025-01-06T06:49:59.773Z", # Eksempel på datointerval
        "endDate": "2025-01-07T14:49:59.773Z"   # Eksempel på datointerval
    }
    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("Adgangstoken hentet succesfuldt.")

        # Hent aggregerede forsendelsesdata
        aggregated_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_AGGREGATED)
        print("\n--- Aggregerede forsendelsesdata ---")
        print(json.dumps(aggregated_data, indent=2))

        # Hent yderligere information
        additional_info_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_ADDITIONAL_INFO)
        print("\n--- Yderligere forsendelsesinformation ---")
        print(json.dumps(additional_info_data, indent=2))

    except requests.exceptions.HTTPError as e:
        print(f"HTTP-fejl: {e}")
        print(f"Respons statuskode: {e.response.status_code}")
        print(f"Responsindhold: {e.response.text}")
    except Exception as e:
        print(f"En fejl opstod: {e}")

Ved at følge denne udviklervejledning og konsultere den officielle dokumentation kan du effektivt integrere med nShift Shipment Data API for at få adgang til værdifuld forsendelsesinformation og hændelser til dine applikationer.