Tässä artikkelissa selitetään, miten sijaintikoodi (esim. terminaali- tai paikkakoodit kuten 9010 tai 0705) haetaan lähetyksen tapahtumista käyttäessä ShipmentData-rajapintaa. Keskitytään siihen, mistä tiedot löytyvät vastauksesta ja miten ne tulkitaan.

Todennusvaatimukset

Ennen ShipmentData-rajapinnan kutsumista tarvitset käyttöoikeustunnuksen:

• Auth URL: https://account.nshiftportal.com/idp/connect/token
• Grant-tyyppi: client_credentials
• Scope: public_api_portal_shipment_data

Kun vaihdat client_id ja client_secret tokeniksi, käytät tätä tokenia Authorization: Bearer -otsikossa API-kutsuissasi.

Vaihe 1: Hanki käyttöoikeustunnus

Käytä cURL-komentoa saadaksesi käyttöoikeustunnuksen:

curl -X POST 'https://account.nshiftportal.com/idp/connect/token'   
   -H 'Content-Type: application/x-www-form-urlencoded'   
   -d 'grant_type=client_credentials'   
   -d 'client_id=<YOUR_CLIENT_ID>'   
   -d 'client_secret=<YOUR_CLIENT_SECRET>'

Esimerkkivastaus:

{
  "access_token": "<JWT>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "public_api_portal_shipment_data"
}

Vaihe 2: Kysy lähetyksen tietoja viivakoodilla

Hae tapahtumia, jotka voivat sisältää sijaintikoodeja, käyttämällä Aggregated-by-Barcode-päätepistettä.

curl -X POST 'https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/Aggregated/ByBarcode'   
-H "Authorization: Bearer <ACCESS_TOKEN>"   
-H "Content-Type: application/json"   
-d '{
    "query": "<BARCODE>",
    "startDate": "2025-08-24T00:00:00Z",
    "endDate": "2025-08-26T23:59:59Z",
    "pageSize": 20,
    "pageIndex": 0,
    "installationTags": [],
    "actorTags": [],
    "carrierTags": [],
    "dateRangeSource": 1
}'

Vastaus sisältää tiedot lähetyksestä ja paketeista, mukaan lukien tapahtumat.

Missä sijaintikoodi näkyy

location-kenttä sisältyy joihinkin pakettitason tapahtumiin. Se edustaa tyypillisesti kuljetusyrityksen sisäistä paikka- tai terminaalikoodia.

• Pakettitason tapahtumat: shipment.lines[].packages[].events[].location (suositeltu)

Kun location on läsnä, se esiintyy yhdessä seuraavien kanssa:

• cityName
• postalCode
• country

• Valinnaisesti coordinates, joka sisältää leveys- ja pituusasteen

   

Esimerkki: Vastauskatkelma

Alla yksinkertaistettu esimerkki vastauksesta, jossa näkyy pakettitapahtuma sijaintikoodilla:

[
  {
    "shipment": {
      "lines": [
        {
          "packages": [
            {
              "number": "00073123400271295954",
              "events": [
                {
                  "uuid": "b4e5a99b-0aee-41a2-11dd-b1e539a1a4d1",
                  "configurationName": "The delivery of the shipment item is in progress",
                  "normalizedStatusId": 2001,
                  "normalizedStatusName": "Out for delivery",
                  "date": "2025-08-26T09:16:14+02:00",
                  "cityName": "Aalborg",
                  "postalCode": "9000",
                  "country": "Denmark",
                  "location": "9010"
                }
              ]
            }
          ]
        }
      ]
    }
  }
]

Tässä esimerkissä:

• location-koodi on 9010
• Tapahtuman tila on Out for delivery (kuljetuksessa)
• Kaupunki ja postinumero antavat lisätietoa (Aalborg, 9000)

Sijaintikoodin tulkinta

• location-arvo on kuljetusyrityskohtainen, ei postinumero.
• Koodit kuten 9010 tai 0705 ovat tunnisteita terminaaleille tai lajittelukeskuksille.
• Yhdistä cityName ja postalCode -arvoihin, jotta käyttäjät saavat selkeämmän kuvan.