Connecter Motive : importer les positions des véhicules dans le suivi

Terminez le flux OAuth 2.0 de Motive hors de ce système, collez l’access token dans Integration, laissez l’URL de base de l’API par défaut sauf endpoint régional, testez, mappez, activez.

Le connecteur Motive lit les positions des véhicules de votre flotte Motive (anciennement KeepTruckin) et les convertit en événements de suivi dans TMS, pour suivre un envoi en transit par la position du véhicule. C’est son seul rôle : il ne lit que les positions des véhicules. Il n’importe pas les commandes, ne crée ni dispatch ni chargement, ne lit ni les journaux conducteur ni les heures de service, et n’écrit rien dans Motive. Une connexion fonctionne avec un access token Motive.

Prérequis#

• Un compte flotte Motive avec des véhicules qui remontent leur position, et les véhicules à suivre déjà configurés dans Motive.
• Un moyen de terminer le flux authorization_code OAuth 2.0 de Motive hors de ce système : autoriser sur gomotive.com/oauth/authorize et échanger le code sur gomotive.com/oauth/token. Cette connexion n’a pas de bouton d’autorisation dans le système : vous apportez un access token déjà obtenu et vous le collez.
• Le token doit porter le droit d’accès aux positions des véhicules. Sans ce droit, le test répond MISSING_SCOPE : vérifiez donc les droits de l’App dans le Motive Developer Portal avant de tester.
• Vous savez si votre flotte utilise l’adresse API Motive par défaut ou un endpoint régional. La plupart des flottes utilisent l’adresse par défaut et laissent base_url vide.

Obtenir les identifiants#

1. Lancez le flux OAuth 2.0 de Motive hors de ce système : ouvrez gomotive.com/oauth/authorize et approuvez l’accès de votre App flotte, en suivant le flux authorization_code avec lequel votre App Motive a été configurée.
2. Échangez le code d’autorisation sur gomotive.com/oauth/token pour obtenir l’access token. Le token est une longue chaîne, sous la forme montrée à l’étape de saisie, commençant par des caractères comme eyJraWQiOiIyMDIwXzEi.
3. Copiez l’access token complet en une fois et gardez-le prêt à coller. Ne le raccourcissez pas et n’ajoutez ni espaces ni retours à la ligne : un token tronqué répond INVALID_TOKEN.
4. Rappelez-vous que ce token expire. À l’expiration, cette connexion ne peut pas le renouveler pour vous : vous refaites le même flux authorization_code OAuth et vous collez le nouveau token. Prévoyez ce renouvellement avant que la flotte cesse de remonter ses positions.

Remplir dans Integration#

1. Ouvrez Integration → Marketplace → Motive → Nouvelle connexion.
2. token, obligatoire, OAuth2 access token : collez l’access token complet échangé sur gomotive.com/oauth/token, par ex. une longue chaîne commençant par eyJraWQiOiIyMDIwXzEi. C’est un champ de type mot de passe, conservé comme secret.
3. base_url, facultatif, URL de base de l’API : laissez-le vide pour utiliser la valeur par défaut https://api.gomotive.com. Ne le remplissez que si votre flotte utilise un endpoint API régional Motive, et saisissez alors cette adresse d’endpoint exactement comme Motive l’a fournie.

Tester la connexion#

Cliquez sur Tester la connexion. Avec un token saisi, le test envoie une vraie demande en lecture seule : GET {base_url}/v2/vehicle_locations avec votre token comme identifiant Bearer, avec un délai de 12 secondes. Une réponse 200 signifie que le token est accepté et que l’endpoint des positions répond. Une réponse 401 revient sous la forme INVALID_TOKEN : le token est invalide ou a expiré. Une réponse 403 revient sous la forme MISSING_SCOPE : le token ne porte pas le droit d’accès aux positions des véhicules. Une demande sans réponse dans le délai revient sous la forme TIMEOUT. Corrigez la cause indiquée par le code, puis retestez : le test ne modifie aucune donnée dans Motive.

Mapping / choisir un modèle#

Choisissez le mapping standard Motive. Il prend chaque position de véhicule renvoyée pour votre flotte et la convertit en événement de suivi TMS pour ce véhicule, de sorte que les positions correspondent au véhicule et à l’envoi suivis dans TMS. Après un test réussi, lancez une lecture et comparez un véhicule dont vous savez qu’il est en route : comparez sa dernière position ici avec le même véhicule dans Motive. Si la position correspond, le mapping est correct et vous pouvez activer.

Activer#

Après activation, la connexion lit les positions des véhicules dans Motive avec votre token et tient le suivi TMS à jour avec les dernières positions de la flotte. Surveillez les premières lectures dans Runs / Logs et comparez quelques véhicules avec Motive avant de laisser la connexion sans surveillance, et notez la date d’expiration du token pour le renouveler à temps.

Ce que cette connexion ne fait pas : elle n’importe ni commandes ni chargements depuis Motive, ne crée ni ne modifie de dispatch, ne lit ni journaux conducteur, ni heures de service, ni relevés de carburant, et n’envoie ni positions ni aucune autre donnée vers Motive. Continuez à gérer cela dans Motive même, ou dans les systèmes où le travail se fait réellement.

FAQ#

Le test échoue avec INVALID_TOKEN (401)

Motive a refusé le token : il est invalide ou il a expiré. Les access tokens du flux authorization_code OAuth ne durent pas indéfiniment, et un token tronqué lors de la copie est refusé de la même façon : le test ne distingue pas un token coupé d’un token expiré.

Refaites le flux authorization_code OAuth de Motive (autorisez sur gomotive.com/oauth/authorize et échangez le code sur gomotive.com/oauth/token), copiez le nouvel access token en entier, collez-le dans le champ token, enregistrez et retestez. Cette connexion n’a pas de bouton de renouvellement : un nouveau token vient toujours d’un nouveau passage OAuth.

Le test échoue avec MISSING_SCOPE (403)

Le token lui-même a été accepté, mais il ne porte pas le droit d’accès aux positions des véhicules, donc Motive ne le laisse pas lire les positions. Les valeurs saisies ne sont pas le problème : le droit n’a pas été accordé à l’App lors de l’émission du token.

Ouvrez le Motive Developer Portal, vérifiez les droits de l’App et assurez-vous que l’accès aux positions des véhicules est accordé, puis refaites le flux OAuth pour émettre un token avec ce droit, collez le nouveau token et retestez.

Le test échoue avec TIMEOUT

La demande de positions n’a pas répondu en 12 secondes. C’est un problème d’accès vers l’API Motive — une base_url incorrecte, un endpoint régional qui ne répond pas pour votre flotte, ou un ralentissement temporaire de l’API Motive — et non la preuve que le token est faux.

Vérifiez d’abord base_url : laissez-le vide pour la valeur par défaut https://api.gomotive.com, sauf si votre flotte utilise vraiment un endpoint régional. Puis retestez. Si le délai se répète avec l’adresse par défaut, attendez un peu et réessayez, et gardez l’heure de l’échec tirée de Runs / Logs quand vous demandez de l’aide.

Cela se connectait avant, puis les positions ont cessé de se mettre à jour

La cause la plus fréquente est l’arrivée de l’access token à sa date d’expiration. La connexion garde l’ancien token et ne peut pas le renouveler seule : les lectures commencent alors à échouer, généralement avec INVALID_TOKEN dans les journaux, alors que rien d’autre n’a changé dans la connexion.

Refaites le flux authorization_code OAuth, collez le nouvel access token dans le champ token, enregistrez et testez. Une fois le test réussi, les positions reprennent. Cette fois, notez la nouvelle date d’expiration pour que le prochain renouvellement ait lieu avant l’échéance.

Connecté, mais un véhicule n’affiche aucune position

La connexion renvoie les positions que Motive détient pour la flotte : si Motive lui-même n’a pas de position actuelle pour ce véhicule — véhicule éteint, hors couverture ou sans remontée — ce système n’a rien à afficher pour lui. Une connexion saine ne peut pas inventer une position que Motive n’a pas.

Vérifiez d’abord ce même véhicule dans Motive. Si Motive affiche une position actuelle et que ce système ne l’affiche pas, lancez une lecture manuelle, comparez le véhicule dans Runs / Logs et retestez la connexion. Si Motive n’affiche rien non plus, corrigez la remontée de ce véhicule côté Motive.

Pourquoi aucune commande ni aucun dispatch n’arrive par Motive ?

Parce que ce connecteur ne lit que les positions des véhicules. Les commandes, les chargements et les dispatches ne font pas partie de ce qu’il peut lire dans Motive : une liste de commandes vide ici est donc le comportement attendu, pas une connexion cassée.

Continuez à créer et gérer commandes et dispatches dans les systèmes où ce travail se fait, et utilisez cette connexion pour ce qu’elle fait : suivre dans le suivi TMS les véhicules qui transportent ces envois.