Authentification API (TrackServiceKey)

Les API TrackRoad utilisent une clé API appelée TrackServiceKey. Pour REST, envoyez-la dans X-API-Key. Pour SOAP, envoyez-la dans SessionIDHeader sous la forme SessionID.

Flux d’authentification de l’API TrackRoad montrant TrackServiceKey utilisé comme X-API-Key pour REST et SessionIDHeader pour SOAP
Vue d’ensemble de l’authentification : TrackServiceKey est votre clé API — envoyez-la comme X-API-Key pour REST et comme SessionIDHeader/SessionID pour SOAP.

Besoin des endpoints et des modèles ?

Swagger fournit les schémas complets de requête et de réponse pour Dispatch, Routes, Route, Geocode, Credit et Distance.

Voir l’interface Swagger Vue d’ensemble de la référence API

Table des matières

  1. Fonctionnement de l’authentification
  2. Générez votre TrackServiceKey
  3. Authentification REST (X-API-Key)
  4. Authentification SOAP (SessionIDHeader)
  5. Login / Logout (hérité)
  6. Bonnes pratiques de sécurité
  7. Erreurs courantes (401/403)
  8. Endpoints associés
  9. FAQ

Fonctionnement de l’authentification#

TrackRoad utilise un concept d’authentification unique sur l’ensemble de son API : votre TrackServiceKey au niveau du compte.

  • TrackServiceKey est générée dans votre compte TrackRoad.
  • REST : envoyez-la dans X-API-Key à chaque requête.
  • SOAP : envoyez-la dans SessionIDHeader comme SessionID à chaque appel.

Recommandé pour les nouvelles intégrations : utilisez REST dès que possible et conservez SOAP uniquement pour les systèmes hérités.

Générez votre TrackServiceKey#

Avant d’appeler l’API TrackRoad, créez ou copiez votre clé d’authentification depuis votre compte.

  1. Connectez-vous à votre compte TrackRoad.
  2. Ouvrez Manage Users (ou les paramètres API, si disponibles).
  3. Générez ou copiez votre TrackServiceKey.
  4. Stockez-la en toute sécurité, uniquement côté serveur.

Si vous ne trouvez pas votre TrackServiceKey, contactez le support TrackRoad pour activer ou confirmer l’accès API.

Authentification REST (X-API-Key)#

Envoyez votre TrackServiceKey dans l’en-tête X-API-Key à chaque requête REST vers TrackRoad.

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

Conservez les clés API côté serveur. N’intégrez pas TrackServiceKey dans du JavaScript navigateur, des applications mobiles ou du code client public.

Authentification SOAP (SessionIDHeader)#

Les appels SOAP s’authentifient à l’aide de SessionIDHeader. Pour les services SOAP TrackRoad, envoyez votre TrackServiceKey comme valeur SessionID à chaque requête.

Login et Logout peuvent encore apparaître dans une ancienne documentation SOAP, mais ils ne sont pas requis pour les intégrations modernes qui utilisent déjà TrackServiceKey.

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

Endpoints Login / Logout (hérités)#

Login et Logout sont maintenus uniquement pour la rétrocompatibilité. Les nouvelles intégrations TrackRoad doivent s’authentifier avec TrackServiceKey : REST via X-API-Key et SOAP via SessionIDHeader.

Bonnes pratiques de sécurité#

La protection de votre clé API est essentielle pour des intégrations de production fiables et sécurisées.

  • N’exposez jamais les clés API dans du JavaScript front-end.
  • Utilisez des intégrations serveur à serveur ou backend sécurisées.
  • Stockez les clés dans des variables d’environnement, des gestionnaires de secrets ou des magasins de configuration sécurisés.
  • Faites tourner la clé immédiatement si vous suspectez une compromission.
  • Ne journalisez ni n’envoyez jamais les clés API par e-mail en texte brut.

Erreurs courantes (401/403)#

Si l’authentification échoue, vérifiez le nom de l’en-tête, la valeur de la clé, l’environnement et l’état du compte.

  • 401 Unauthorized : clé manquante ou invalide. Pour REST, vérifiez X-API-Key. Pour SOAP, vérifiez SessionIDHeader et SessionID.
  • 403 Forbidden : la clé peut être valide, mais l’accès est bloqué, expiré ou limité par le crédit ou les autorisations.

FAQ#

Comment authentifier les appels à l’API REST TrackRoad ?
Envoyez votre TrackServiceKey dans l’en-tête X-API-Key à chaque requête REST.
Comment authentifier les appels SOAP TrackRoad ?
Pour SOAP, envoyez votre TrackServiceKey dans SessionIDHeader comme SessionID à chaque requête SOAP.
Ai-je besoin de Login/Logout ?
Non. Les endpoints Login et Logout sont hérités. Les nouvelles intégrations doivent utiliser l’authentification TrackServiceKey.
Pourquoi est-ce que j’obtiens 401 Unauthorized ?
Les causes fréquentes incluent un en-tête X-API-Key manquant, une clé invalide, des espaces superflus ou l’utilisation du mauvais environnement ou hôte.

Étape suivante : essayez un endpoint

Une fois votre TrackServiceKey obtenue, commencez par Credit pour valider l’authentification, puis poursuivez avec Geocode, Route, Routes ou Dispatch.

Vérifier Credit Aller à Dispatch