Connecter Vizion : suivre les conteneurs et leurs jalons avec une API key délivrée par les ventes

L’API Key Vizion est délivrée par les ventes Vizion à l’ouverture de votre compte : il n’y a pas d’inscription en libre-service. Collez la clé comme seul champ api_key dans Integration, testez, mappez, activez.

Le connecteur Vizion fait un seul travail : le suivi de conteneurs pour le drayage. Vous lancez un suivi — une référence — avec un numéro de conteneur, de connaissement ou de réservation, et le connecteur ramène les mises à jour de jalons de cet envoi : chaque jalon porte un horaire planifié (une estimation, ETA) ou un horaire réel (ATA), pour voir à la fois ce qui est attendu et ce qui s’est réellement passé. C’est tout le périmètre : il n’importe pas les commandes, ne crée ni envois ni dispatch, ne réserve pas de rendez-vous au terminal et n’écrit rien dans Vizion. Une connexion fonctionne avec une API Key Vizion.

Prérequis#

• Un compte Vizion ouvert auprès des ventes Vizion, avec l’accès API inclus. L’API Key est délivrée par les ventes Vizion à l’ouverture du compte : il n’y a pas de page d’inscription en libre-service, donc si vous n’avez pas encore de clé, l’obtenir auprès des ventes Vizion est l’étape zéro, avant toute chose dans ce système.
• L’API Key elle-même, telle que les ventes Vizion vous l’ont délivrée. Conservez le message ou le document d’origine dans lequel elle est arrivée : si la clé est perdue ou refusée, seules les ventes Vizion peuvent la réémettre ; elle ne peut être ni consultée ni régénérée depuis une page de réglages.
• Au moins un numéro de conteneur, de connaissement ou de réservation que vous voulez réellement suivre, pour comparer les premiers jalons avec un envoi que vous connaissez. Quand vous avez le code transporteur (SCAC) de cet envoi, gardez-le aussi prêt : Vizion peut identifier le transporteur automatiquement, mais sa propre recommandation est de fournir le code transporteur chaque fois que vous le pouvez.

Obtenir les identifiants#

1. Contactez les ventes Vizion et ouvrez votre compte Vizion avec l’accès API, si ce n’est pas déjà fait. L’API Key est délivrée par les ventes Vizion dans le cadre de l’ouverture du compte.
2. Recevez l’API Key des ventes Vizion. Il n’y a ni inscription en libre-service ni page développeur où vous pourriez en créer une vous-même : si une page ou une personne propose d’« enregistrer » une clé Vizion pour vous en dehors du processus d’ouverture de compte, ce n’est pas ainsi que cette clé est délivrée.
3. Copiez la clé complète en une fois, exactement comme elle a été délivrée — les clés de cette connexion commencent par vizion_ — et gardez-la prête à coller. Ne la raccourcissez pas et n’y ajoutez aucun préfixe.
4. Il n’y a que cet identifiant, et qu’une seule adresse Vizion à connaître : https://prod.vizionapi.com. Il n’y a pas d’adresse sandbox séparée à configurer : la clé qui vous a été délivrée est testée et utilisée sur cette même adresse.

Remplir dans Integration#

1. Ouvrez Integration → Marketplace → Vizion → Nouvelle connexion.
2. api_key, obligatoire, Vizion API Key : collez la clé complète délivrée par les ventes Vizion, commençant par vizion_. C’est le seul champ de cette connexion. C’est un champ de type mot de passe, conservé comme secret. Collez la clé seule, exactement comme elle a été délivrée : le système l’envoie lui-même comme en-tête X-API-Key.
3. Enregistrez la connexion, puis lancez le test avant de changer quoi que ce soit d’autre : avec un seul champ, un test en échec concerne cette clé ou l’activation du compte derrière elle, et non la recherche du champ fautif parmi beaucoup d’autres.

Tester la connexion#

Cliquez sur Tester la connexion. Avec votre clé saisie, le test envoie une vraie demande en lecture seule : GET https://prod.vizionapi.com/references?limit=1, avec votre clé envoyée comme en-tête X-API-Key, avec un délai de 12 secondes. Il ne liste que vos références actives, limitées à une, et ne change donc rien dans Vizion. Une réponse réussie revient sous la forme « Vizion authentication passed ». Si la clé est refusée, le test signale HTTP_401. Si api_key est vide, il s’arrête avec MISSING_CREDENTIALS. Une demande qui ne peut pas aboutir signale CONNECTION_FAILED. Corrigez la cause indiquée par le résultat, puis retestez.

Mapping / choisir un modèle#

Choisissez le mapping standard Vizion. Il prend chaque mise à jour de jalon renvoyée par Vizion pour une référence et l’aligne avec le dossier du conteneur suivi ici dans le suivi de drayage, en conservant la distinction faite par Vizion lui-même : un jalon marqué comme planifié porte un horaire estimé (ETA), et un jalon non planifié porte l’horaire réel (ATA). Après un test réussi, lancez le suivi d’un conteneur, d’un connaissement ou d’une réservation que vous connaissez, et comparez les premiers jalons — événement, lieu, et caractère planifié ou réel de chaque horaire — avec ce qu’affiche Vizion pour le même envoi. S’ils correspondent, le mapping est correct et vous pouvez activer.

Activer#

Après activation, vous pouvez lancer le suivi à partir d’un numéro de conteneur, de connaissement ou de réservation, et la connexion fait arriver ici, dans le suivi de drayage, les mises à jour de jalons de ces références. Deux règles de Vizion s’appliquent au lancement d’une référence : donnez le connaissement ou le numéro de réservation, jamais les deux ensemble — une demande portant les deux est rejetée — et ajoutez le code transporteur (SCAC) chaque fois que vous l’avez, car l’identification automatique du transporteur est le recours de secours, pas la voie préférée. Les mises à jour d’une référence peuvent aussi arriver sous forme de notifications poussées, de même forme que les mises à jour récupérées : ce que vous voyez ici reste donc cohérent dans les deux cas. Surveillez les premières références dans Runs / Logs et comparez quelques envois avec Vizion avant de laisser la connexion sans surveillance.

Ce que cette connexion ne fait pas : elle n’importe ni commandes ni envois depuis un autre système, ne crée ni dispatch ni chargement, ne réserve ni ne modifie de rendez-vous au terminal, et n’envoie pas les données de suivi vers Vizion. De plus, elle ne suit que les références que vous lancez : elle n’importe pas un historique d’envois constitué ailleurs.

FAQ#

Le test échoue avec HTTP_401

Vizion a refusé la clé envoyée. Les causes habituelles sont une clé tronquée lors de la copie, un caractère différent de l’original délivré, ou une clé que Vizion a depuis remplacée ou pas encore activée sur votre compte. Cette connexion envoie la clé comme en-tête X-API-Key, exactement comme le spécifie la documentation officielle : la forme d’envoi n’est donc pas la variable, c’est la valeur de la clé.

Comparez la clé collée caractère par caractère avec l’original délivré par les ventes Vizion, corrigez toute différence, enregistrez et retestez. Si la clé collée correspond exactement à l’original et que le test signale toujours HTTP_401, contactez les ventes Vizion et demandez-leur de confirmer que la clé est active sur votre compte ou de la réémettre : seules les ventes Vizion peuvent le faire, il n’existe aucune page où la réinitialiser vous-même.

Le test s’arrête avec MISSING_CREDENTIALS

Le champ api_key est vide : il n’y a donc aucune clé à envoyer et le test ne peut rien vérifier. Cette connexion a exactement un champ, l’identifiant ne peut donc se cacher nulle part ailleurs.

Collez la clé complète délivrée par les ventes Vizion dans api_key, enregistrez la connexion et retestez. Si vous n’avez pas encore de clé, obtenez-la d’abord auprès des ventes Vizion : il n’existe pas de page d’inscription pour en créer une.

Il n’y a pas de page d’inscription : où obtenir une API Key Vizion ?

C’est voulu côté Vizion : l’API Key n’est pas en libre-service. Les clés sont délivrées par les ventes Vizion à l’ouverture d’un compte Vizion, donc il n’existe délibérément aucune page publique qui en crée une, et ce système ne peut pas non plus en générer une pour vous.

Contactez les ventes Vizion, ouvrez le compte avec l’accès API et recevez la clé de leur part. Revenez ensuite à cette connexion, collez la clé dans api_key, enregistrez et testez. Si votre entreprise a déjà un compte Vizion, demandez au collègue qui l’a ouvert où la clé délivrée est conservée, avant d’ouvrir un second compte.

Le lancement du suivi échoue avec INVALID_REQUEST : connaissement et réservation donnés ensemble

Vizion valide les deux numéros comme des alternatives : une demande de suivi peut porter un connaissement ou un numéro de réservation, mais une demande portant les deux à la fois est rejetée par cette validation. C’est une règle côté Vizion, pas une faute de l’un des numéros : chacun, seul, est acceptable.

Relancez le suivi avec un seul des deux numéros : gardez le connaissement ou le numéro de réservation et retirez l’autre. Vous pouvez aussi donner un numéro de conteneur comme identifiant. Ajoutez également le code transporteur (SCAC) quand vous l’avez.

Le lancement du suivi échoue avec INVALID_REQUEST : aucun identifiant donné

Aucun identifiant n’a été donné pour la référence. Vizion lance le suivi à partir d’un identifiant — un numéro de conteneur (container_id), de connaissement ou de réservation — et sans aucun des trois, il n’y a rien pour quoi ouvrir une référence.

Relancez le suivi avec l’un des trois numéros de cet envoi — et rappelez-vous la règle d’association : si vous utilisez le connaissement, n’ajoutez pas aussi le numéro de réservation. Ajoutez le code transporteur (SCAC) quand vous l’avez, pour que Vizion n’ait pas à identifier le transporteur automatiquement.

Le test échoue avec CONNECTION_FAILED, ou expire après 12 secondes

La demande en lecture seule vers prod.vizionapi.com n’a pas pu aboutir dans le délai. C’est un problème d’accès vers l’API Vizion, ou un ralentissement temporaire de Vizion : ce n’est pas la preuve que la clé est fausse, car la clé n’est jugée que lorsque l’API répond réellement.

Attendez un peu et retestez sans changer la clé. Si l’échec persiste, notez l’heure de l’échec tirée de Runs / Logs quand vous demandez de l’aide, et dites au support Vizion que la demande part vers https://prod.vizionapi.com avec la clé dans l’en-tête X-API-Key, pour qu’ils puissent vérifier la même fenêtre de leur côté.

L’horaire d’un jalon semble faux : il est dans le futur, ou il a bougé

Ce jalon est très probablement un jalon planifié. Dans les données Vizion, un jalon marqué planned=true porte un horaire estimé (une ETA), qui se situe par nature dans le futur et est révisé à mesure que l’envoi avance ; un jalon avec planned=false porte l’horaire réel (une ATA), qui est fixe une fois l’événement survenu. L’estimation qui change, c’est la donnée qui fonctionne comme prévu, pas un suivi erroné.

Lisez le jalon avec son marqueur planifié avant d’agir sur l’horaire : planifiez autour des horaires planifiés (ETA) et ne traitez que les horaires réels (ATA) comme de l’historique. Si un horaire marqué comme réel diffère de ce qu’affichent le transporteur ou le terminal pour le même événement, notez la référence et l’événement quand vous demandez au support Vizion de le vérifier.