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_credentialsclient_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äänAuthorization-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/jsonAccept: application/json(taitext/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.