Denne veiledningen er for utviklere som ønsker å integrere med nShift Shipment Data API for å programmessig hente forsendelsesinformasjon og hendelser. Vi dekker autentisering, bruk av endepunkter, samt forespørsels- og responsstrukturer.

1. Autentisering: Skaffe en tilgangstoken

Tilgang til Shipment Data API krever en gyldig OAuth 2.0 tilgangstoken. Vi bruker Client Credentials grant type for server-til-server autentisering.

Steg for å skaffe token:

• Endepunkt: https://account.nshiftportal.com/idp/connect/token
• Metode: POST
• Headers:
  • Content-Type: application/x-www-form-urlencoded
• Forespørselsinnhold (form-urlencoded):
  • grant_type=client_credentials
  • client_id={YOUR_CLIENT_ID}
  • client_secret={YOUR_CLIENT_SECRET}

Eksempel på forespørsel:

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'

Vel Lykket Respons (200 OK):

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

• Lagre access_token. Denne tokenen brukes i Authorization-headeren for påfølgende API-forespørsler. Tokenen har utløpstid (expires_in). Implementer logikk for å fornye token når den utløper.

2. API-endepunkter for forsendelsesdata

Vi tilbyr to hovedendepunkter for å hente forsendelsesinformasjon, hver for forskjellige bruksområder:

For detaljerte forsendelsesdata:

• Endepunkt: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 foretrekker ren tekst som svar, men JSON anbefales vanligvis)
• Forespørselsinnhold (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
}

Forespørselsinnholdet aksepterer parametere som query for å spesifisere pakkens strekkode, valgfrie startDate og endDate i ISO 8601-format for å definere søkeperiode, pageSize for å kontrollere antall resultater per side, pageIndex for paginering (starter fra 0), og valgfrie tag-filtre som installationTags, actorTags og carrierTags.

Eksempel på respons (200 OK - forkortet for oversikt, se fullstendig eksempel i originaldata):

[
  {
    "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 hendelser ...
      ],
      "lines": [
        {
          "packages": [
            {
              "number": "00370733741693409071",
              "events": [
                {
                  "configurationName": "Damaged",
                  "normalizedStatusName": "Delivered",
                  "date": "2025-01-07T10:58:17.363+01:00"
                }
                // ... flere pakkehendelser ...
              ]
            }
          ]
        }
      ]
      // ... 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 oppsummert forsendelsesinformasjon, primært sporings-URLer og siste statuser.

• Endepunkt:
• https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/additional-information/ByBarcode)
• Metode: POST
• Headers & Forespørselsinnhold: Samme som tidligere.

Eksempel på respons (200 OK - forkortet for oversikt):

[
  {
    "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

# --- Konfigurasjon ---
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 en tilgangstoken ved bruk av 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 for dårlige responser (4xx eller 5xx)
    return response.json()["access_token"]

def get_shipment_data(access_token, barcode, endpoint_url):
    """Henter forsendelsesdata fra spesifisert endepunkt."""
    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å datoperiode
        "endDate": "2025-01-07T14:49:59.773Z"   # Eksempel på datoperiode
    }
    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("Tilgangstoken hentet vellykket.")

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

        # Hent tilleggsinformasjon
        additional_info_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_ADDITIONAL_INFO)
        print("\n--- Tilleggsforsendelsesinformasjon ---")
        print(json.dumps(additional_info_data, indent=2))

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

Ved å følge denne utviklerveiledningen og konsultere den offisielle dokumentasjonen, kan du effektivt integrere med nShift Shipment Data API for å få tilgang til verdifull forsendelsesinformasjon og hendelser for dine applikasjoner.