Exemple d'intégration, créer une boutique e-commerce avec l'API Boxtal

On crée un compte professionnel, puis dans l'espace développeur une application API v3 (expéditions, suivi, notifications), une application API v1 (cotation) et une application Composant Carte. On commence sur l'environnement de test, où les expéditions ne sont pas facturées.

Les clés restent sur le serveur, chiffrées. En production, le paiement différé doit être activé (SIRET valide). Voir Authentification et Environnements.

Chaque produit porte un poids, des dimensions, une valeur et une catégorie de contenu (choisie dans la liste Boxtal, utile à la cotation et à la douane). Ces données déterminent le colis déclaré et donc la justesse des cotations. Pour l'international, on ajoute un code SH (douane).

On découpe le monde en zones (France métropolitaine, Corse, Outre-mer, UE, Europe hors UE, International) et, au besoin, en zones personnalisées par pays. Règle simple, un pays n'appartient qu'à une seule zone. La France est l'exception, car elle se répartit entre plusieurs zones selon le code postal (20 pour la Corse, 97 et 98 pour l'Outre-mer).

Chaque mode de livraison d'une zone pointe vers une offre Boxtal (code OPERATEUR-Service) et fixe le prix, cotation plus marge, forfait ou grille par poids.

Avant de proposer un mode dans une zone, on vérifie par cotation que l'offre est bien disponible vers chaque pays de la zone. Pour les offres en point relais, ce test demande une précaution particulière, décrite dans Disponibilité d'une offre en relais par pays.

Quand le client saisit son adresse, le serveur cote en v1 pour le colis et récupère les offres. On applique la politique de prix du mode (marge en pourcentage puis fixe, arrondi par exemple aux 50 centimes supérieurs), puis on affiche les modes disponibles.

L'offre retenue se convertit en code v3 en reliant l'opérateur et le service par un tiret (par exemple MONR-CpourToi). On enregistre ce code sur la commande. Détails et pièges, cotation v1 et pièges à éviter.

Le prix affiché au client vient de la cotation v1, mais le prix facturé est celui que renvoie l'API v3 à la création de l'expédition (deliveryPriceExclTax, hors taxes). Les deux peuvent légèrement différer, d'où l'intérêt d'une marge et d'un arrondi.

Pour un mode relais, on affiche le composant Carte de Boxtal. Le jeton est généré côté serveur avec les clés de l'application Composant Carte (jamais avec les clés API v3), et seul ce jeton temporaire est transmis au navigateur.

La carte est initialisée avec le seul réseau du transporteur de l'offre, déduit du code opérateur (MONR-CpourToi donne MONR_NETWORK). Avec plusieurs réseaux, le client pourrait choisir un point d'un autre transporteur, incompatible avec l'offre cotée. Le client choisit son point, le serveur enregistre son code avec la commande. Voir points relais & Carte.

Après paiement, le serveur crée l'expédition en v3 avec le même code d'offre que celui coté, le point relais éventuel (pickupPointCode) et le numéro de commande. Boxtal renvoie un identifiant et le prix facturé.

L'étiquette n'est pas dans la réponse de création. Elle est en général disponible presque aussitôt, parfois après quelques secondes à quelques minutes, et Boxtal le signale par le webhook DOCUMENT_CREATED. Le document renvoie une URL signée, valable 7 jours, que le serveur utilise pour télécharger l'étiquette et la conserver avant de la servir à l'utilisateur. Voir créer une expédition.

On s'abonne une fois aux notifications, pour chaque type d'événement utile (DOCUMENT_CREATED pour l'étiquette, TRACKING_CHANGED pour le suivi). À chaque événement, Boxtal appelle une URL du serveur. L'en-tête x-bxt-signature contient une signature HMAC SHA-256 en hexadécimal, calculée sur le corps brut de la requête en UTF-8, à recalculer et comparer avant tout traitement. On met à jour le statut et on prévient le client. Une tâche planifiée resynchronise le suivi, en filet de sécurité si une notification se perd. Voir webhooks signés.

Contexte

Pour décider si un mode de livraison en point relais peut être proposé dans une zone, on vérifie, pour chaque pays de la zone, que l'offre en relais correspondante est disponible. La vérification se fait par des requêtes de cotation v1 vers une ville du pays.

Problème

Avec une seule ville par pays, le résultat n'est pas fiable. La réponse de la cotation dépend de l'adresse de destination, et une offre en relais peut être absente pour une ville alors qu'elle est bien disponible dans le pays. On risquait donc d'écarter à tort une offre pour tout un pays.

Solution

Faire le test sur trois villes différentes par pays. L'offre en relais est considérée comme disponible dans le pays dès qu'au moins une des trois cotations la renvoie. Elle n'est écartée que si aucune des trois ne la propose.

Contexte

Les vérifications de disponibilité et le calcul des tarifs de secours enchaînent beaucoup de cotations (pays × trois villes × offres, voire × tranches de poids).

Problème

Envoyées l'une après l'autre, ces requêtes dépassent le temps d'exécution accordé par l'hébergeur et la page finit en erreur 504.

Solution

Envoyer les requêtes en parallèle par petits lots (cURL multi en PHP), avec un délai maximal par requête, et conserver les résultats pour ne pas tout recalculer à chaque affichage.

Problème

Si la cotation ne répond pas (délai dépassé, erreur, API indisponible), le panier ne peut plus afficher de frais de port et le client ne peut pas commander.

Solution

Le mode bascule sur une grille de secours, alimentée par les dernières cotations réelles et majorée d'un pourcentage pour couvrir une éventuelle hausse. Le client peut toujours commander, et le prix réellement facturé reste celui de la création v3.

Problème

Pour les villes de test, certains formats de code postal provoquent une erreur 400, par exemple la Lettonie sans le préfixe LV- (1050) ou les Pays-Bas au format complet (3011 EA). D'autres pays, comme l'Argentine, attendent un format particulier.

Solution

Prévoir pour chaque pays un code postal au format accepté, et pour les cas délicats plusieurs candidats essayés l'un après l'autre en cas d'erreur 400.

Problème

La liste des pays de l'API v1 contient des codes qui ne sont pas des codes ISO, pour des territoires particuliers (Canaries E1, Açores P1, Büsingen D1, Campione I1…).

Solution

Les traiter à part dans les zones et les afficher avec leur pays de rattachement. Avant de réutiliser une adresse en v3, qui attend un code ISO (countryIsoCode), vérifier la correspondance.

Problème

Deux offres d'un même transporteur peuvent avoir un nom proche mais un code différent, souvent une version France et une version Europe (MONR-CpourToi et MONR-CpourToiEurope, CHRP-ChronoRelais et CHRP-ChronoRelaisEurope). La conversion v1 vers v3 se fait aussi avec un tiret, pas un tiret bas.

Solution

Comparer les codes nettoyés, jamais les libellés, et construire le code v3 sous la forme operator.code-service.code.

Problème

Le prix de la cotation v1 et le prix renvoyé par la v3 à la création de l'expédition peuvent différer légèrement.

Solution

Enregistrer les deux sur la commande pour pouvoir les comparer, et garder une marge suffisante dans la politique de prix.