Connecter Terminal49 : suivre les conteneurs par conteneur, connaissement ou réservation
Obtenez vous-même une Developer Key gratuite sur app.terminal49.com/developers/api-keys, collez-la comme seul champ api_key dans Integration, testez, mappez, activez.
Le connecteur Terminal49 fait un seul travail : le suivi de conteneurs pour le drayage. Vous lancez le suivi avec un numéro de conteneur, de connaissement ou de réservation, et le connecteur ramène les jalons, les horaires des navires et la disponibilité au terminal — y compris le Last Free Day, les retenues (holds) et les frais signalés par le terminal. 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 Terminal49. Une connexion fonctionne avec une API Key Terminal49.
Prérequis#
- Un compte Terminal49 auquel vous pouvez vous connecter sur app.terminal49.com, pour ouvrir vous-même la page des clés API développeur. La clé est en libre-service : pour commencer, aucun appel commercial ni délai d’approbation n’est nécessaire.
- Au moins un numéro de conteneur, de connaissement ou de réservation que vous voulez réellement suivre, pour pouvoir comparer les premiers résultats avec un envoi que vous connaissez.
- Estimez votre volume de suivi avant de dépendre de la clé gratuite : une Developer Key gratuite suit jusqu’à 100 conteneurs. C’est largement suffisant pour évaluer la connexion, mais planifiez la clé de production selon le nombre de conteneurs suivis en même temps.
Obtenir les identifiants#
- Connectez-vous sur app.terminal49.com et ouvrez la page des clés API développeur : app.terminal49.com/developers/api-keys.
- Créez une clé sur cette page. Une Developer Key gratuite suffit pour connecter et évaluer : elle suit jusqu’à 100 conteneurs.
- Copiez l’API Key complète en une fois et gardez-la prête à coller. Ne la raccourcissez pas et n’y ajoutez aucun préfixe : la clé seule constitue tout l’identifiant.
- Il n’y a que cet identifiant. Il n’y a ni nom d’utilisateur, ni mot de passe, ni clé sandbox, ni seconde clé à collecter, et le test et la production utilisent la même adresse Terminal49 : la même clé sert au test et à la production.
Remplir dans Integration#
- Ouvrez Integration → Marketplace → Terminal49 → Nouvelle connexion.
- api_key, obligatoire, Terminal49 API Key : collez la clé complète copiée depuis app.terminal49.com/developers/api-keys. C’est le seul champ de cette connexion. C’est un champ de type mot de passe, conservé comme secret. Collez la clé seule, sans le mot « Token » ni « Bearer » devant : le système ajoute lui-même la forme de l’en-tête.
- 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é, 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://api.terminal49.com/v2/tracking_requests?page[size]=1, avec votre clé envoyée sous la forme « Authorization: Token <API_KEY> », avec un délai de 12 secondes. Il ne lit que la première page de vos demandes de suivi existantes et ne change donc rien dans Terminal49. Une réponse réussie revient sous la forme « Terminal49 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 Terminal49. Il prend chaque résultat de suivi renvoyé par Terminal49 — jalons, horaire du navire et disponibilité au terminal comme le Last Free Day, les retenues et les frais — et l’aligne avec le dossier du conteneur suivi ici dans le suivi de drayage. 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 jalons et les dates du terminal côte à côte avec ce qu’affiche Terminal49 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 — donnez-en un des trois, plus le SCAC du transporteur quand vous l’avez — et la connexion tient à jour ici les jalons, l’horaire du navire et la disponibilité au terminal de ces conteneurs. Les demandes de suivi sont limitées à 100 par minute côté Terminal49 : les très gros démarrages en masse sont donc étalés au lieu d’être lancés d’un seul coup. Surveillez les premiers résultats dans Runs / Logs et comparez quelques conteneurs avec Terminal49 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 Terminal49. De plus, elle ne suit que les conteneurs pour lesquels vous lancez le suivi : elle ne découvre ni n’importe tout votre historique d’envois depuis Terminal49.
FAQ#
Le test échoue avec HTTP_401
Terminal49 a refusé la clé envoyée. Les causes habituelles sont une clé tronquée lors de la copie, un mot supplémentaire collé devant, ou une clé supprimée ou remplacée dans votre compte Terminal49 après la copie. L’adresse et la connexion sont correctes : ce code ne concerne que la clé.
Ouvrez app.terminal49.com/developers/api-keys, créez une nouvelle clé, copiez-la en entier sans rien devant, collez-la dans le champ api_key, enregistrez et retestez. Si vous vérifiez l’API à la main, rappelez-vous que la forme de l’en-tête est « Authorization: Token <API_KEY> » : une vérification de type Bearer échoue même avec la bonne clé.
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 tirée de app.terminal49.com/developers/api-keys dans api_key, enregistrez la connexion et retestez.
Le test échoue avec CONNECTION_FAILED, ou expire après 12 secondes
La demande en lecture seule vers l’API Terminal49 n’a pas pu aboutir dans le délai. C’est un problème d’accès vers api.terminal49.com, ou un ralentissement temporaire de Terminal49 : 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, pour pouvoir comparer la fenêtre avec le côté Terminal49.
Le lancement du suivi échoue avec INVALID_REQUEST
Aucun identifiant n’a été donné pour la demande de suivi. Terminal49 lance le suivi à partir d’un identifiant — un numéro de conteneur, de connaissement ou de réservation — et sans aucun des trois, il n’y a rien à lancer.
Relancez le suivi avec l’un des trois numéros de cet envoi, et ajoutez le SCAC du transporteur quand vous l’avez : cela aide Terminal49 à rattacher la demande au bon transporteur.
Le lancement du suivi échoue avec HTTP_429 quand beaucoup de conteneurs sont lancés à la fois
Vous avez atteint la limite de débit de Terminal49 : les demandes de suivi sont plafonnées à 100 par minute. Ni la clé ni les conteneurs en échec ne sont en cause : ils ont simplement été envoyés plus vite que Terminal49 ne les accepte.
Relancez les conteneurs en échec par plus petits lots, étalés sur plus d’une minute, au lieu de réessayer tout l’ensemble d’un coup. Ceux qui ont déjà démarré continuent d’être suivis normalement.
Les nouveaux conteneurs ne sont plus suivis après environ 100
Vous utilisez la Developer Key gratuite, qui suit jusqu’à 100 conteneurs. La connexion et la clé fonctionnent — les cent premiers le prouvent — mais la clé gratuite n’a pas de place pour davantage de conteneurs en même temps.
Basculez la connexion vers une clé Terminal49 dont le quota de conteneurs correspond à votre volume réel : créez ou obtenez cette clé dans votre compte Terminal49, collez-la dans api_key à la place de la clé gratuite, enregistrez et testez. Le suivi déjà lancé avec la clé gratuite n’est pas un réglage de ce système : vérifiez d’abord le quota de la clé chaque fois que le volume augmente.