API de géolocalisation de flotte QWS : documentation

L'API Quartix Web Services (QWS) fournie par Traceur Entreprise permet aux entreprises et aux développeurs d'intégrer directement les données de géolocalisation de leur flotte de véhicules dans leurs propres outils métier : ERP, logiciels de planification, tableaux de bord internes ou applications client sur-mesure.

Grâce à cette API REST, il est possible de récupérer en temps réel la position, la vitesse et le statut de chaque véhicule ou chauffeur, mais aussi d'accéder à l'historique des trajets, aux résumés d'activité, au kilométrage et aux zones géographiques personnalisées.

L'API QWS est accessible pour 4€ HT ^{/ mois} par véhicule.

Pourquoi utiliser l'API de géolocalisation Quartix ?

Que vous souhaitiez afficher la position de vos véhicules sur votre propre carte, automatiser vos rapports de kilométrage, synchroniser vos données de suivi de flotte avec votre logiciel de gestion, ou déclencher des alertes lorsqu'un véhicule entre ou sort d'une zone définie, l'API QWS met à disposition l'ensemble des données de géolocalisation nécessaires. Elle repose sur un système d'authentification par jetons (JWT), des réponses au format JSON, et une structure de paramètres cohérente (région, site, groupe, véhicule, chauffeur) pour filtrer précisément les informations récupérées.

URL de base

Ce webservice est disponible sur les URL suivantes :

• https://qws.quartix.net/v2/api pour les utilisateurs UK & France
• https://qws.quartix.com/v2/api pour les utilisateurs US

Par exemple, le endpoint d'authentification initial est :

https://qws.quartix.net/v2/api/auth

Paramètres communs

Afin de proposer une interface structurée, de nombreux paramètres d'endpoints sont communs à plusieurs appels : RegionID, SiteID, GroupID, VehicleID, VehicleIDList, DriverID et DriverIDList. La plupart de ces paramètres sont optionnels ; par exemple, préciser successivement RegionID, SiteID et GroupID permet de réduire progressivement le nombre de véhicules et de chauffeurs retournés. Si une combinaison de paramètres est accessible à l'utilisateur connecté mais n'est pas valide (par exemple un SiteID et un GroupID tous deux valides pour l'utilisateur, mais où le groupe sélectionné n'appartient pas au site), une réponse 403 avec un texte explicatif est renvoyée. Si un paramètre fourni n'est pas accessible à l'utilisateur connecté, une réponse 400 indiquant un défaut d'autorisation est renvoyée, sans autre explication.

Plages de dates et heures

La représentation des dates et heures dépend du fuseau horaire du véhicule ou du chauffeur. Les plages horaires sont également affectées par les heures de début de service (shift) des véhicules et des chauffeurs. Dans cette version de QWS, les conventions suivantes sont adoptées :

• les valeurs de date/heure renvoyées par les appels sont toujours exprimées dans l'heure locale du véhicule ou du chauffeur ;
• les paramètres des appels (lorsque c'est pertinent) sont un jour de début et un jour de fin, sans heure précise. Le fuseau horaire et l'heure de début de service du véhicule ou du chauffeur sont utilisés pour déterminer les dates/heures de début et de fin de la période concernée. La période correspond généralement au début du service qui démarre le jour de début, jusqu'à la fin du service qui démarre le jour de fin.

Unités

Toutes les réponses sont exprimées en unités métriques : kilomètres pour les distances, kilomètres par heure pour les vitesses, et mètres pour les rayons (par exemple le rayon d'un lieu personnalisé).

Impersonation (accès multi-comptes)

Les utilisateurs ayant accès à plusieurs comptes clients doivent fournir un SiteName et un User supplémentaires, en plus de leurs identifiants de connexion. Ils obtiennent alors l'accès aux données du SiteName connecté uniquement ; changer de site nécessite une nouvelle authentification. Les utilisateurs « superuser » disposant de régions configurées obtiennent en revanche l'accès à plusieurs sites sans impersonation ni ré-authentification pour chaque site.

Authentification

La réponse à une demande d'authentification est une paire de jetons web JSON : un jeton d'authentification (AccessToken) et un jeton de rafraîchissement (RefreshToken). Ces jetons sont renvoyés à la fois dans la réponse et sous forme de cookies. Le client peut choisir l'une des deux approches suivantes : soit transmettre les deux jetons sous forme de cookies à chaque appel suivant, soit envoyer le jeton d'authentification dans l'en-tête à chaque appel. Si les cookies sont utilisés, les appels suivants régénèrent automatiquement les deux jetons et les redéfinissent dans les cookies si le jeton d'authentification a expiré. Si le jeton d'authentification est envoyé dans l'en-tête et a expiré, une erreur d'authentification est renvoyée : il faut alors utiliser l'appel /auth/refresh avec le jeton de rafraîchissement pour obtenir de nouveaux jetons.

Versioning

L'API est versionnée directement dans le chemin de l'URL (versions majeures uniquement).

Conventions générales

• Les appels et les réponses sont encodés en UTF-8.
• Les paramètres d'appel sont transmis soit en variables POST, soit en JSON dans le corps de la requête. Les réponses sont renvoyées en JSON dans le corps de la réponse.
• Les réponses sont contenues dans une enveloppe : { Meta: {Code: 200, Message: ok }, Data: {...} }.
• Les valeurs multiples pour les champs de chaîne de requête sont formatées en « CSV », séparées par des virgules, plutôt qu'en valeurs répétées, par exemple VehicleIDList=4,24 plutôt que VehicleIDList=4&VehicleIDList=24.

Gestion des erreurs

Des codes de statut HTTP appropriés sont utilisés pour décrire les erreurs au code client. Le corps des réponses d'erreur est toujours un objet de statut (code et message) fournissant des informations complémentaires.