Autenticazione API (TrackServiceKey)

Le API di TrackRoad utilizzano una chiave API chiamata TrackServiceKey. Per REST, inviala come X-API-Key. Per SOAP, inviala in SessionIDHeader come SessionID.

Flusso di autenticazione API TrackRoad che mostra TrackServiceKey usata come X-API-Key per REST e SessionIDHeader per SOAP
Panoramica dell’autenticazione: TrackServiceKey è la tua chiave API — inviala come X-API-Key per REST e come SessionIDHeader/SessionID per SOAP.

Ti servono endpoint e modelli?

Swagger fornisce gli schemi completi di richiesta e risposta per Dispatch, Routes, Route, Geocode, Credit e Distance.

Apri Swagger UI Panoramica del riferimento API

Indice dei contenuti

  1. Come funziona l’autenticazione
  2. Genera la tua TrackServiceKey
  3. Autenticazione REST (X-API-Key)
  4. Autenticazione SOAP (SessionIDHeader)
  5. Login / Logout (legacy)
  6. Best practice di sicurezza
  7. Errori comuni (401/403)
  8. Endpoint correlati
  9. FAQ

Come funziona l’autenticazione#

TrackRoad utilizza un unico concetto di autenticazione su tutta la sua superficie API: la tua TrackServiceKey a livello di account.

  • TrackServiceKey viene generata nel tuo account TrackRoad.
  • REST: inviala nell’intestazione X-API-Key in ogni richiesta.
  • SOAP: inviala in SessionIDHeader come SessionID in ogni chiamata.

Consigliato per le nuove integrazioni: usa REST ove possibile e mantieni SOAP solo per i sistemi legacy.

Genera la tua TrackServiceKey#

Prima di chiamare l’API TrackRoad, crea o copia la tua chiave di autenticazione dal tuo account.

  1. Accedi al tuo account TrackRoad.
  2. Apri Manage Users (oppure le impostazioni API, se disponibili).
  3. Genera o copia la tua TrackServiceKey.
  4. Conservala in modo sicuro solo lato server.

Se non riesci a trovare la tua TrackServiceKey, contatta il supporto TrackRoad per abilitare o confermare l’accesso API.

Autenticazione REST (X-API-Key)#

Invia la tua TrackServiceKey nell’intestazione X-API-Key in ogni richiesta REST a TrackRoad.

curl -X POST "https://trackservice.trackroad.com/rest/credit" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY"

Conserva le chiavi API lato server. Non incorporare TrackServiceKey in JavaScript del browser, app mobili o codice client pubblico.

Autenticazione SOAP (SessionIDHeader)#

Le chiamate SOAP si autenticano usando SessionIDHeader. Per i servizi SOAP di TrackRoad, invia la tua TrackServiceKey come valore SessionID in ogni richiesta.

Login e Logout possono ancora comparire nella documentazione SOAP più vecchia, ma non sono necessari per le integrazioni moderne che già utilizzano TrackServiceKey.

<soap:Header>
  <SessionIDHeader xmlns="http://TrackService.TrackRoad.com/">
    <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
  </SessionIDHeader>
</soap:Header>

Endpoint Login / Logout (legacy)#

Login e Logout sono mantenuti solo per retrocompatibilità. Le nuove integrazioni TrackRoad dovrebbero autenticarsi con TrackServiceKey: REST tramite X-API-Key e SOAP tramite SessionIDHeader.

Best practice di sicurezza#

Proteggere la tua chiave API è essenziale per integrazioni di produzione affidabili e sicure.

  • Non esporre mai le chiavi API nel JavaScript frontend.
  • Usa integrazioni server-to-server o backend sicure.
  • Conserva le chiavi in variabili d’ambiente, secret manager o archivi di configurazione sicuri.
  • Ruota immediatamente la chiave se sospetti una compromissione.
  • Non registrare né inviare mai via email le chiavi API in testo semplice.

Errori comuni (401/403)#

Se l’autenticazione non riesce, verifica il nome dell’intestazione, il valore della chiave, l’ambiente e lo stato dell’account.

  • 401 Unauthorized: chiave mancante o non valida. Per REST, controlla X-API-Key. Per SOAP, controlla SessionIDHeader e SessionID.
  • 403 Forbidden: la chiave può essere valida, ma l’accesso è bloccato, scaduto o limitato da credito o permessi.

FAQ#

Come autentico le chiamate REST API di TrackRoad?
Invia la tua TrackServiceKey nell’intestazione X-API-Key in ogni richiesta REST.
Come autentico le chiamate SOAP di TrackRoad?
Per SOAP, invia la tua TrackServiceKey in SessionIDHeader come SessionID in ogni richiesta SOAP.
Ho bisogno di Login/Logout?
No. Gli endpoint Login e Logout sono legacy. Le nuove integrazioni dovrebbero usare l’autenticazione TrackServiceKey.
Perché ricevo 401 Unauthorized?
Le cause comuni includono un’intestazione X-API-Key mancante, una chiave non valida, spazi extra oppure l’uso dell’ambiente o host sbagliato.

Passo successivo: prova un endpoint

Una volta ottenuta la tua TrackServiceKey, inizia con Credit per verificare l’autenticazione, poi continua con Geocode, Route, Routes o Dispatch.

Controlla Credit Vai a Dispatch