Tämä opas on tarkoitettu kehittäjille, jotka haluavat integroitua nShift Shipment Data API:iin ohjelmallisesti hakeakseen toimitustietoja ja tapahtumia. Käymme läpi todennuksen, päätepisteiden käytön sekä pyyntöjen ja vastausten rakenteet.

1. Todennus: Pääsytunnuksen hankkiminen

Shipment Data API:in pääsy vaatii voimassa olevan OAuth 2.0 -pääsytunnuksen. Käytämme Client Credentials -valtuutustyyppiä palvelin-palvelin -todennukseen.

Vaiheet tokenin hankkimiseksi:

• Päätepiste: https://account.nshiftportal.com/idp/connect/token
• Metodi: POST
• Otsikot:
  • Content-Type: application/x-www-form-urlencoded
• Pyyntörunko (form-urlencoded):
  • grant_type=client_credentials
  • client_id={YOUR_CLIENT_ID}
  • client_secret={YOUR_CLIENT_SECRET}

Esimerkkipyyntö:

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'

Onnistunut vastaus (200 OK):

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

• Tallenna access_token. Tätä tokenia käytetään Authorization-otsikossa myöhemmissä API-pyynnöissä. Tokeneilla on vanhenemisaika (expires_in). Toteuta logiikka tokenin uudistamiseksi, kun se vanhenee.

2. Shipment Data API:n päätepisteet

Tarjoamme kaksi päätepistettä toimitustietojen hakemiseen, jotka palvelevat eri käyttötarkoituksia:

Yksityiskohtaiset toimitustiedot:

• Päätepiste:https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/Aggregated/ByBarcode)
• Metodi: POST
• Otsikot:
  • Authorization: Bearer {YOUR_ACCESS_TOKEN}
  • Content-Type: application/json
  • Accept: application/json (tai text/plain, jos haluat pelkän tekstivastauksen, mutta JSON on yleensä suositeltava)
• Pyyntörunko (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
}

Pyyntörunko hyväksyy parametrit kuten query, jolla määritellään paketin viivakoodi, valinnaiset startDate ja endDate ISO 8601 -muodossa hakujakson määrittämiseksi, pageSize tulosten määrän hallintaan per sivu, pageIndex sivutukseen (alkaen 0) sekä valinnaiset suodatustunnisteet kuten installationTags, actorTags ja carrierTags.

Esimerkkivastaus (200 OK - lyhennetty, katso täydellinen esimerkki alkuperäisestä datasta):

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

Yhteenvetotiedot toimituksista, pääasiassa seurantalinkit ja viimeisimmät tilat.

• Päätepiste:
• https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/additional-information/ByBarcode)
• Metodi: POST
• Otsikot ja pyyntörunko: Sama kuin aiemmin.

Esimerkkivastaus (200 OK - lyhennetty):

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

import requests
import json

# --- Konfiguraatio ---
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():
    """Hakee pääsytunnuksen Client Credentials -valtuutuksella."""
    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()  # Heittää HTTPErrorin virheellisissä vastauksissa (4xx tai 5xx)
    return response.json()["access_token"]

def get_shipment_data(access_token, barcode, endpoint_url):
    """Hakee toimitustietoja määritellystä päätepisteestä."""
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {
        "query": barcode,
        "startDate": "2025-01-06T06:49:59.773Z", # Esimerkkiaikaväli
        "endDate": "2025-01-07T14:49:59.773Z"   # Esimerkkiaikaväli
    }
    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("Pääsytunnus saatu onnistuneesti.")

        # Hae koottuja toimitustietoja
        aggregated_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_AGGREGATED)
        print("\n--- Koottu toimitustieto ---")
        print(json.dumps(aggregated_data, indent=2))

        # Hae lisätietoja
        additional_info_data = get_shipment_data(token, BARCODE_TO_TRACK, SHIPMENT_DATA_ENDPOINT_ADDITIONAL_INFO)
        print("\n--- Lisätoimitustiedot ---")
        print(json.dumps(additional_info_data, indent=2))

    except requests.exceptions.HTTPError as e:
        print(f"HTTP-virhe: {e}")
        print(f"Vastauskoodi: {e.response.status_code}")
        print(f"Vastausrunko: {e.response.text}")
    except Exception as e:
        print(fTapahtui virhe: {e}")

Noudattamalla tätä kehittäjäopasta ja tutustumalla viralliseen dokumentaatioon voit tehokkaasti integroitua nShift Shipment Data API:in ja saada arvokasta toimitustietoa ja tapahtumatietoja sovelluksiisi.