Denna guide är för utvecklare som vill integrera med nShift Shipment Data API för att programmässigt hämta försändelseinformation och händelser. Vi går igenom autentisering, användning av slutpunkter samt förfrågnings- och svarstrukturer.

1. Autentisering: Skaffa en åtkomsttoken

Åtkomst till Shipment Data API kräver en giltig OAuth 2.0-åtkomsttoken. Vi använder Client Credentials grant type för server-till-server-autentisering.

Steg för att skaffa en token:

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

Exempel på förfrågan:

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'

Lyckat svar (200 OK):

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

• Spara access_token. Denna token används i Authorization-headern för efterföljande API-förfrågningar. Token har en utgångstid (expires_in). Implementera logik för att förnya token när den går ut.

2. API-slutpunkter för försändelsedata

Vi tillhandahåller två huvudsakliga slutpunkter för att hämta försändelseinformation, där varje tjänar olika användningsområden:

För detaljerad försändelsedata:

• Slutpunkt:https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/Aggregated/ByBarcode)
• Metod: POST
• Headers:
  • Authorization: Bearer {YOUR_ACCESS_TOKEN}
  • Content-Type: application/json
  • Accept: application/json (eller text/plain om du föredrar svar i ren text, men JSON rekommenderas generellt)
• 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 accepterar parametrar som query för att specificera paketets streckkod, valfria startDate och endDate i ISO 8601-format för att definiera en sökperiod, pageSize för att styra antal resultat per sida, pageIndex för paginering (börjar från 0) samt valfria taggfilter som installationTags, actorTags och carrierTags.

Exempel på svar (200 OK - förkortat för översikt, se fullständigt exempel i originaldata):

[
  {
    "shipment": {
      "uuid": "17ace13f-8b07-4ef3-b3e7-f78389514e20",
      "number": "70733741693409060",
      "shipmentType": 1,
      "shipmentTypeName": "Normal",
      // ... andra försändelsedetaljer ...
      "events": [
        {
          "uuid": "4e35c2a7-5c43-4b4b-80c3-0ba54d8a5f52",
          "configurationName": "Printed",
          "normalizedStatusName": "Created",
          "date": "2025-01-07T09:57:05.593+00:00"
        },
        // ... fler händelser ...
      ],
      "lines": [
        {
          "packages": [
            {
              "number": "00370733741693409071",
              "events": [
                {
                  "configurationName": "Damaged",
                  "normalizedStatusName": "Delivered",
                  "date": "2025-01-07T10:58:17.363+01:00"
                }
                // ... fler pakethändelser ...
              ]
            }
          ]
        }
      ]
      // ... fler försändelsedetaljer ...
    },
    "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 sammanfattad försändelseinformation, främst spårnings-URL:er och senaste statusar.

• Slutpunkt:
• https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/additional-information/ByBarcode)
• Metod: POST
• Headers & Request Body: Samma som tidigare.

Exempel på svar (200 OK - förkortat för översikt):

[
  {
    "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. Kodexempel (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():
    """Hämtar en åtkomsttoken med 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()  # Kastar HTTPError vid dåliga svar (4xx eller 5xx)
    return response.json()["access_token"]

def get_shipment_data(access_token, barcode, endpoint_url):
    """Hämtar försändelsedata från angiven slutpunkt."""
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {
        "query": barcode,
        "startDate": "2025-01-06T06:49:59.773Z", # Exempel på datumintervall
        "endDate": "2025-01-07T14:49:59.773Z"   # Exempel på datumintervall
    }
    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("Åtkomsttoken erhölls framgångsrikt.")

        # Hämta aggregerad försändelsedata
        aggregated_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_AGGREGATED)
        print("\n--- Aggregerad försändelsedata ---")
        print(json.dumps(aggregated_data, indent=2))

        # Hämta ytterligare information
        additional_info_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_ADDITIONAL_INFO)
        print("\n--- Ytterligare försändelseinformation ---")
        print(json.dumps(additional_info_data, indent=2))

    except requests.exceptions.HTTPError as e:
        print(f"HTTP-fel: {e}")
        print(f"Statuskod i svar: {e.response.status_code}")
        print(f"Svarstext: {e.response.text}")
    except Exception as e:
        print(fEtt fel uppstod: {e}")

Genom att följa denna utvecklarguide och konsultera den officiella dokumentationen kan du effektivt integrera med nShift Shipment Data API för att få tillgång till värdefull försändelseinformation och händelser för dina applikationer.