Intégrer l'API d'un transporteur sur un site web propre : les quatre appels qui comptent et les erreurs qui reviennent

Nous avons publié des connecteurs MRW, SEUR, Correos Express, DHL, GLS, UPS et CTT pour Odoo, et nous avons intégré des transporteurs sur des sites sans Odoo derrière, comme eclipseando.com. Les API changent de nom et de format, mais le travail est toujours le même : quatre appels, trois ou quatre erreurs qui reviennent et une décision d'architecture qu'il vaut mieux prendre avant d'écrire la première ligne. Cet article est la version pour un site web propre ; si votre boutique tourne sur Odoo, l'essentiel est déjà résolu dans les connecteurs de transporteur.

Avant de programmer : l'accès et l'environnement de test

Aucun transporteur ne vous donne accès à son API parce que vous avez rempli un formulaire sur son site. Il faut un contrat de transport avec un commercial, et c'est de là que viennent les identifiants : un code client ou abonné, un utilisateur et un mot de passe ou une clé, et parfois un code de franchise ou d'agence. Demandez-les dès le premier jour, ainsi que l'environnement de test, que tous n'ont pas et qui ne se comporte pas toujours comme la production. Certaines API sont encore en SOAP avec XML (c'est le cas historique de plusieurs transporteurs espagnols) ; d'autres sont en REST avec JSON. Ce qu'il faut faire ne change pas, seul le temps nécessaire pour lire la documentation change.

Les quatre appels

Créer l'expédition : la moitié du travail consiste à nettoyer l'adresse

L'appel de création est celui où se concentrent les rejets. Chaque transporteur a sa propre idée de ce qu'est une adresse valide : longueur maximale de la rue, code postal de cinq chiffres exactement, province sous forme de code et non de texte, téléphone obligatoire et sans indicatif, et chez plusieurs, rien hors ASCII dans le nom. Ce qui fonctionne, c'est de normaliser avant d'appeler : séparer la rue et le numéro, tronquer les champs au maximum admis par chaque API, remplacer les accents quand l'API ne les accepte pas, et vérifier que le code postal existe pour ce pays. Et toujours conserver la requête et la réponse complètes, en XML ou JSON, avec la commande. Quand un colis se perd trois semaines plus tard, cette trace est la seule preuve de ce qui a été envoyé.

Suivi : une interrogation raisonnée, ou un webhook s'il existe

Peu de transporteurs préviennent par webhook ; chez la plupart, il faut les interroger. La bonne méthode est une tâche planifiée qui ne consulte que les expéditions ouvertes, à un intervalle raisonnable (toutes les heures suffit en général, plus souvent le jour de la livraison), qui s'arrête quand le statut est final et qui respecte les limites de l'API. Les codes d'événement se traduisent en un petit ensemble de statuts propres : accepté, en transit, en cours de livraison, livré, incident, retourné. Cinq ou six, pas quarante. Et chaque changement de statut déclenche l'alerte au client, ce qui est la raison d'être de tout cela.

Quand vous n'avez pas l'API parce que c'est votre fournisseur qui expédie

C'est plus fréquent qu'il n'y paraît : c'est vous qui vendez, mais le colis est préparé et expédié par un fournisseur avec son propre contrat de transport. Vous n'avez pas d'identifiants, vous ne pouvez ni créer l'expédition ni la consulter. Ce que vous avez presque toujours, ce sont les e-mails que le transporteur envoie à l'adresse de contact à chaque mouvement. Sur eclipseando.com, nous l'avons résolu ainsi avec GLS : une tâche lit la boîte mail toutes les dix minutes, reconnaît les quatre types d'e-mail (en route, en cours de livraison, en point de retrait avec date limite, destinataire absent), extrait le numéro d'expédition et la commande à laquelle il appartient, et transforme chacun en un statut et une alerte à l'acheteur. Les deux derniers sont les urgents : un colis en point de retrait retourne à l'expéditeur si personne ne vient le chercher, et un client qui ne sait pas qu'il s'y trouve n'ira pas.

Les erreurs que nous voyons en production

• Tester uniquement sur le sandbox. Plusieurs transporteurs ont un environnement de test qui accepte ce que la production rejette. Le test qui compte, c'est une expédition réelle vers votre propre bureau.
• Créer l'expédition à la confirmation de la commande sur le site. Elle se crée à la préparation du colis. Si elle est créée avant, chaque annulation devient une expédition fantôme qui est parfois facturée.
• Ne pas conserver la requête et la réponse. Sans le XML ou le JSON complet avec la commande, une réclamation oppose votre parole à celle du transporteur.
• Un seul numéro de suivi par commande. Cela fonctionne jusqu'à la première commande avec deux colis ou deux fournisseurs. Le suivi se modélise par expédition.
• Certificats et chiffrement anciens. Certaines API restent en TLS avec des chiffrements que les bibliothèques modernes rejettent par défaut. On le détecte le premier jour, pas le jour de la mise en production.

Avec Odoo derrière, presque rien de tout cela ne se programme

Si la boutique tourne sur Odoo, les quatre appels sont déjà écrits dans les connecteurs que nous publions sur l'App Store de Odoo, testés sur Odoo 19, 18 et 17 sur un vrai Odoo.sh : l'étiquette sort à la validation du bon de livraison, le suivi est interrogé par cron et écrit dans le bon de livraison, le manifeste se clôture depuis Odoo même et l'alerte au client part par e-mail ou SMS avec le modèle que vous voulez. Le site n'a qu'à lire le statut du bon de livraison. C'est pourquoi, quand on nous demande d'intégrer un transporteur sur un site web et que le client a déjà Odoo, la réponse est généralement de connecter le site à l'ERP, pas de réécrire l'intégration.

Questions fréquentes

Liens utiles sur FlexigoTech

Ce que nous faisons sur ce sujet