FAQ & Guide d'intégration API Boxtal

Une API est une porte d'entrée qui permet à votre site de dialoguer directement avec Boxtal, sans passer par l'espace client. Votre boutique peut ainsi rechercher des points relais, commander une expédition, récupérer les étiquettes et suivre les colis, de façon automatique.

L'API v3 (actuellement en version 3.1) est la génération actuelle de l'API Boxtal. C'est elle qui est recommandée pour toute nouvelle intégration : elle offre de meilleures performances et un fonctionnement plus moderne. L'API v1, plus ancienne, est officiellement dépréciée. Elle reste maintenue pour assurer la compatibilité avec les anciens modules e-commerce et parce qu'elle est encore nécessaire pour la cotation.

Les deux API servent le même objectif, mais l'API v3 a été conçue selon les standards actuels. Voici les principales différences.

Le point clé est la cotation : comme elle n'existe pas en v3, une boutique qui affiche des frais de port calculés doit continuer à utiliser l'API v1 pour cette seule étape. Les deux API se combinent sans difficulté : v1 pour obtenir les tarifs au panier, v3 pour tout le reste (points relais, expéditions, étiquettes, suivi).

Le passage de l'une à l'autre est simple : chaque offre renvoyée par la cotation v1 comporte un code transporteur (bloc operator, par exemple CHRP) et un code de prestation (bloc service, par exemple Chrono2ShopDirect). Le code d'offre à utiliser en v3 s'obtient en les reliant par un tiret : CHRP-Chrono2ShopDirect. Le détail, avec un convertisseur, est dans la section De la cotation v1 à l'offre v3 du guide.

Boxtal propose deux environnements séparés, chacun avec son adresse et ses comptes.

L'environnement de test (https://api.boxtal.build) sert à développer et à vérifier votre intégration. Il nécessite un compte dédié, distinct de votre compte habituel, et les expéditions qui y sont créées ne sont pas facturées. Pour que vous puissiez tester le suivi, Boxtal y génère des événements fictifs toutes les 20 minutes, de la création de l'étiquette jusqu'à la « livraison ». Ce suivi simulé concerne Mondial Relay, Colissimo, Chronopost, UPS et TNT domestique. Seuls les bordereaux et, le cas échéant, les factures proforma sont générés.

L'environnement de production (https://api.boxtal.com) est celui de votre activité réelle : les expéditions y sont facturées. On n'y bascule qu'une fois tout validé en test. Les clés de test ne fonctionnent qu'en test, et inversement.

Dans les deux cas, les échanges se font obligatoirement en HTTPS sécurisé (TLS 1.2).

Les identifiants se créent dans l'espace développeur Boxtal, page « Applications ». Chaque application fournit une clé d'accès et une clé secrète, et chacune a un rôle précis :

• Application API v3 : pour les points relais, les expéditions, les étiquettes, le suivi et les notifications.
• Application API v1 : pour la cotation, si vous affichez des tarifs calculés. Sur une marketplace, seule la plateforme en a besoin (voir Partie 3).
• Application Composant Carte : pour afficher la carte des points relais dans votre page de commande.

Ces clés doivent rester sur votre serveur. Seul le jeton de la carte, temporaire et limité à cet usage, peut être transmis au navigateur de vos clients. N'utilisez jamais les clés API v3 pour la carte : elles donnent accès à toutes les opérations, y compris la création d'expéditions facturées (voir le jeton de la carte).

À chaque appel, Boxtal doit savoir qui fait la demande. L'API v3 propose deux méthodes.

Le jeton temporaire (méthode recommandée). Votre serveur présente une fois sa clé d'accès et sa clé secrète au service d'authentification de Boxtal. Il reçoit en échange un jeton valable une heure, une sorte de badge provisoire qu'il joint ensuite à chacune de ses demandes. Avant l'expiration, il en redemande un nouveau. Les clés circulent ainsi le moins possible.

Le Basic Auth. Plus simple, cette méthode consiste à joindre directement la clé d'accès et la clé secrète à chaque demande. Elle fonctionne sur toutes les opérations, mais expose davantage vos clés.

Ce fonctionnement remplace le système de clés d'accès de l'API v1. Pour le détail des en-têtes et un simulateur, voir la section S'authentifier du guide.

Quand une demande ne peut pas aboutir, l'API répond avec un code d'état et un message structuré qui indique la nature du problème, et le plus souvent le champ en cause. Votre site peut donc afficher une explication précise plutôt qu'un simple échec.

La liste complète des codes d'erreur, avec leur signification et la correction à apporter, figure dans la section Comprendre les erreurs du guide.

La migration peut se faire progressivement, sans arrêter votre activité, car les deux API fonctionnent en parallèle.

• Créez vos identifiants v3 tout en gardant votre application v1 active.
• Migrez fonction par fonction : basculez d'abord la création des expéditions, puis les étiquettes et le suivi, en conservant la cotation en v1, la seule API qui la propose.
• Profitez-en pour adopter les notifications : plutôt que d'interroger Boxtal régulièrement, laissez-le prévenir votre site quand une étiquette est prête ou quand un colis avance.
• Validez tout en environnement de test avant de passer en production : création d'expédition, réception des notifications, gestion des erreurs.

Intégrer Boxtal, c'est relier votre boutique à Boxtal à trois moments de la vie d'une commande. Au panier, le client voit les modes de livraison et leur prix. Après le paiement, votre site commande le transport. Ensuite, Boxtal vous transmet l'étiquette du colis puis, au fil du trajet, les nouvelles du suivi.

C'est toujours votre site, côté serveur, qui dialogue avec Boxtal. Le navigateur de votre client ne voit jamais vos clés : il affiche seulement ce que votre site lui prépare, et éventuellement la carte des points relais.

Il faut d'abord un compte Boxtal professionnel et des clés d'accès, que l'on crée dans l'espace développeur. Une clé sert à gérer les expéditions (API v3), une autre au calcul des tarifs (API v1) si vous en avez besoin, et une troisième à la carte des points relais. Commencez sur l'environnement de test : les expéditions n'y sont pas facturées et vous pouvez tout essayer sans risque.

Préparez aussi vos données produit. Pour expédier un colis, Boxtal a besoin de son poids, de ses dimensions, de sa valeur et de la nature de son contenu (une catégorie choisie dans une liste fournie par Boxtal). Une boutique qui connaît déjà le poids et la taille de ses articles gagnera beaucoup de temps.

Enfin, à la mise en place, votre site s'abonne une fois pour toutes aux notifications de Boxtal : il indique l'adresse à laquelle il souhaite être prévenu quand une étiquette est prête et quand le suivi d'un colis évolue.

Deux approches sont possibles, et le choix dépend surtout de votre catalogue.

Les tarifs fixes. Vous décidez vous-même du prix affiché, par exemple 4,90 € en point relais et 7,90 € à domicile, avec livraison offerte au-delà d'un certain montant. Aucun appel à Boxtal n'est nécessaire à ce moment-là : c'est simple, prévisible et suffisant pour des produits de poids et de taille proches. Vous devez seulement choisir à l'avance quelle offre de transport Boxtal correspond à chaque mode proposé, car c'est elle qui sera commandée après le paiement.

Les tarifs calculés. Si vos colis varient beaucoup, ou si vous livrez dans plusieurs pays, mieux vaut demander le prix réel. Au moment où le client consulte son panier, votre site envoie à Boxtal le poids, les dimensions, l'adresse d'expédition et celle du client. Boxtal répond avec la liste des offres possibles et leur prix. Vous choisissez ensuite lesquelles afficher, et vous pouvez ajouter une marge ou arrondir. Ce calcul passe aujourd'hui par l'API v1, car l'API v3 ne propose pas la cotation. L'offre choisie par le client se convertit ensuite directement en code d'offre v3, en reliant le code transporteur et le code de prestation de la cotation par un tiret (par exemple MONR-CpourToi) : enregistrez ce code sur la commande, il servira à commander le transport (voir De la cotation v1 à l'offre v3).

Si le client opte pour une livraison en point relais ou en consigne (locker), il doit choisir où retirer son colis. Deux solutions s'offrent à vous. Vous pouvez utiliser le composant Carte de Boxtal : une carte prête à l'emploi, à intégrer dans votre page de commande, qui affiche les points relais autour de l'adresse du client et le laisse choisir celui qui lui convient. Elle peut aussi présélectionner automatiquement le point le plus proche, et votre site récupère le point choisi. C'est la solution la plus simple, sans développement cartographique (voir le composant Carte dans le guide). Vous pouvez aussi construire votre propre liste ou carte en interrogeant l'API, si vous voulez une présentation sur mesure.

Dans tous les cas, votre site enregistre l'identifiant du point choisi avec la commande. Il en aura besoin pour commander le transport.

Une fois la commande payée, votre site crée l'expédition chez Boxtal. Il transmet l'adresse de départ, celle du client, la description des colis, l'offre de transport retenue, le point relais s'il y en a un, et votre propre numéro de commande. Ce numéro vous permettra de retrouver facilement la commande quand Boxtal vous enverra des nouvelles.

Boxtal enregistre alors l'envoi auprès du transporteur et vous indique le prix facturé ainsi qu'une date de livraison estimée. Vous pouvez déclencher cette étape automatiquement dès le paiement, ou la garder manuelle, par exemple via un bouton dans votre back-office, si vous préférez vérifier chaque commande avant l'envoi.

Une fois l'expédition créée, l'étiquette est disponible presque immédiatement. Il peut toutefois arriver qu'elle mette de plusieurs secondes à quelques minutes à être disponible, en cas de forte affluence sur les serveurs des transporteurs. Votre site ne doit donc pas compter sur une étiquette instantanée : Boxtal le prévient dès qu'elle est prête et lui transmet un lien de téléchargement. Votre site peut alors l'afficher dans le back-office ou l'imprimer directement. Pour un envoi hors Union européenne, les documents de douane arrivent de la même façon.

Ces liens expirent au bout de 7 jours : si vous souhaitez garder les étiquettes, enregistrez les fichiers. Il ne reste plus qu'à coller l'étiquette sur le colis et à le déposer, ou à le remettre au transporteur.

À chaque étape du trajet (pris en charge, en transit, disponible au point relais, livré…), Boxtal prévient votre site. Celui-ci peut mettre à jour le statut de la commande et envoyer automatiquement un email ou un SMS au client, avec le lien de suivi du transporteur. Inutile d'interroger Boxtal en boucle pour savoir où en est chaque colis : l'information arrive d'elle-même.

• Commande annulée : une expédition peut être annulée depuis votre site. Boxtal peut toutefois refuser l'annulation si l'envoi n'est plus annulable, par exemple s'il est déjà en route.
• Demande refusée : une adresse incomplète, un colis trop lourd pour l'offre choisie ou une offre indisponible empêchent la création de l'expédition. Boxtal indique précisément ce qui ne va pas ; prévoyez de l'afficher clairement dans votre back-office.
• Notifications : si votre site ne répond pas à une notification, Boxtal réessaie pendant 24 heures. Votre site doit simplement répondre vite et savoir ignorer une notification déjà reçue.