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_credentialsclient_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 iAuthorization-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/jsonAccept: application/json(ellertext/plainhvis 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.