Intégrer Boxtal dans votre boutique, pas à pas

Les particularités du mode test

• Des événements de suivi factices sont générés toutes les 20 minutes, de la création du bordereau jusqu'à la « livraison ».
• Ce suivi factice n'existe que pour Mondial Relay, Colissimo, Chronopost, UPS et TNT domestique.
• Seuls les bordereaux et, le cas échéant, les factures proforma sont générés. Les autres documents ne le sont pas.

De la cotation v1 à l'offre v3

La cotation se fait avec l'API v1, mais l'expédition se crée avec l'API v3. Il faut donc convertir l'offre choisie par le client en code d'offre v3 (shippingOfferCode). La conversion est directe : aucun appel supplémentaire n'est nécessaire.

1. Repérer les deux codes dans la réponse XML de la cotation

Pour chaque offre proposée, la réponse de la cotation v1 contient un bloc operator (le transporteur) et un bloc service (la prestation), chacun avec son propre code :

<operator>
    <code>CHRP</code>
    <label>Chronopost</label>
    <logo>https://resource.boxtal.com/images/carriers/chrp.png</logo>
</operator>
<service>
    <code>Chrono2ShopDirect</code>
    <label>Chrono 2Shop Direct</label>
</service>

Ici, le code opérateur est CHRP et le code service Chrono2ShopDirect. Les libellés (label) et le logo servent seulement à l'affichage au client.

2. Assembler le code d'offre v3

Le code d'offre v3 s'écrit code opérateur, tiret, code service :

Ce code s'utilise ensuite tel quel dans l'API v3 : shippingOfferCode pour créer l'expédition, et pour chercher les points relais compatibles avec cette offre.

Convertisseur

Collez un extrait ou la totalité de la réponse XML d'une cotation v1 : chaque couple opérateur / service trouvé est converti en code d'offre v3.

Statut de la commande d'expédition

Statut de suivi du colis

Incidents possibles à tout moment : FAILED_ATTEMPT, EXCEPTION, RETURNED. Le champ isFinal indique qu'aucun autre événement n'est attendu.

Tous les codes d'erreur

Principe

1. Vous créez une souscription par type d'événement avec POST /shipping/v3.1/subscription : URL de réception + clé secrète de validation.
2. À chaque événement, Boxtal envoie un POST HTTPS en JSON vers votre URL.
3. Vous vérifiez la signature, enregistrez l'information et répondez 200 rapidement (voir Enregistrer les événements).
4. Une surveillance automatique vous alerte si les événements cessent d'arriver (voir Détecter une absence d'événements).

Vérifier la signature

Pour vous assurer qu'une notification vient bien de Boxtal, vérifiez l'en-tête x-bxt-signature. Sa valeur est l'encodage HMAC SHA256 du JSON contenu dans le corps de la requête, avec comme secret la clé de validation (webhookSecret) de votre souscription. Boxtal recommande fortement cette vérification.

<?php
// webhook_boxtal.php
$secret  = 'votre-webhookSecret';            // celui donné à la souscription
$payload = file_get_contents('php://input'); // corps brut (octets UTF-8), NON décodé
$recu    = $_SERVER['HTTP_X_BXT_SIGNATURE'] ?? '';

$attendu = hash_hmac('sha256', $payload, $secret); // hexadécimal, sans préfixe

if (!hash_equals($attendu, $recu)) {
    http_response_code(401);
    exit;
}

$event = json_decode($payload, true);
// Enregistrez l'événement (base de données, file d'attente…) puis répondez vite.
http_response_code(200);

// Express : récupérer le corps brut avec express.raw()
const crypto = require('crypto');

app.post('/webhooks/boxtal', express.raw({ type: 'application/json' }), (req, res) => {
    const secret  = process.env.BOXTAL_WEBHOOK_SECRET;
    const recu    = req.get('x-bxt-signature') || '';
    // req.body = Buffer des octets reçus (UTF-8), à signer tel quel
    const attendu = crypto.createHmac('sha256', secret).update(req.body).digest('hex');

    if (recu.length !== attendu.length ||
        !crypto.timingSafeEqual(Buffer.from(recu), Buffer.from(attendu))) {
        return res.sendStatus(401);
    }

    const event = JSON.parse(req.body.toString('utf8'));
    // Enregistrez l'événement puis répondez vite.
    res.sendStatus(200);
});

Calculer une signature pour vos tests

Réponse et réessais

Répondez avec un code 2xx en moins de 2 secondes. Tout autre code (ou un délai trop long) déclenche des réessais. Après 10 tentatives, l'événement est abandonné.

Enregistrer les événements reçus

Chaque notification doit être conservée avant d'être traitée. Vous pouvez ainsi répondre vite à Boxtal, ignorer les doublons, rejouer un traitement qui a échoué et savoir à tout moment ce qui a été reçu.

Une table pour le journal des événements (MySQL / MariaDB)

CREATE TABLE boxtal_webhook_events (
  id                   BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  event_id             VARCHAR(100) NOT NULL,        -- champ "id" de la notification
  event_type           VARCHAR(40)  NOT NULL,        -- DOCUMENT_CREATED ou TRACKING_CHANGED
  shipping_order_id    VARCHAR(40)  NULL,            -- identifiant Boxtal de l'expédition
  shipment_external_id VARCHAR(100) NULL,            -- votre numéro de commande (externalId)
  payload              JSON         NOT NULL,        -- notification complète, telle que reçue
  received_at          DATETIME     NOT NULL,
  processed_at         DATETIME     NULL,            -- rempli une fois l'événement traité
  processing_error     TEXT         NULL,
  UNIQUE KEY uniq_event (event_id),                  -- un même événement n'est jamais enregistré deux fois
  KEY idx_order (shipping_order_id),
  KEY idx_received (received_at)
);

Le type JSON nécessite MySQL 5.7 ou MariaDB 10.2 au minimum ; sinon, utilisez LONGTEXT.

Le script de réception

<?php
// webhook_boxtal.php : vérifier, enregistrer, répondre vite
$secret  = getenv('BOXTAL_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');            // corps brut, non décodé
$recu    = $_SERVER['HTTP_X_BXT_SIGNATURE'] ?? '';

if (!hash_equals(hash_hmac('sha256', $payload, $secret), $recu)) {
    http_response_code(401);
    exit;
}

$event = json_decode($payload, true);
$pdo   = new PDO('mysql:host=localhost;dbname=boutique;charset=utf8mb4', 'utilisateur', 'motdepasse');

// INSERT IGNORE : si Boxtal renvoie le même événement (réessai), il est ignoré
$stmt = $pdo->prepare(
    'INSERT IGNORE INTO boxtal_webhook_events
       (event_id, event_type, shipping_order_id, shipment_external_id, payload, received_at)
     VALUES (?, ?, ?, ?, ?, NOW())'
);
$stmt->execute([
    $event['id'] ?? '',
    $event['type'] ?? '',
    $event['shippingOrderId'] ?? null,
    $event['shipmentExternalId'] ?? null,
    $payload,
]);

http_response_code(200);
// Le traitement (statut de commande, e-mail au client, téléchargement du bordereau)
// est fait ensuite par une tâche planifiée qui lit les lignes où processed_at est vide.

Détecter une absence d'événements

Un webhook qui ne reçoit plus rien ne génère aucune erreur visible : les bordereaux et le suivi cessent simplement d'arriver. Une surveillance automatique permet de repérer un problème de souscription, de certificat HTTPS, de pare-feu ou de serveur avant que vos clients ne le signalent.

Les requêtes de surveillance

-- 1. Expéditions créées depuis plus de 30 minutes sans bordereau reçu
SELECT s.boxtal_order_id, s.created_at
FROM   shop_shipments s
LEFT JOIN boxtal_webhook_events e
       ON e.shipping_order_id = s.boxtal_order_id AND e.event_type = 'DOCUMENT_CREATED'
WHERE  s.created_at < NOW() - INTERVAL 30 MINUTE
  AND  s.created_at > NOW() - INTERVAL 7 DAY
  AND  e.id IS NULL;

-- 2. Dernier événement de suivi reçu, toutes expéditions confondues
SELECT MAX(received_at) AS dernier_suivi
FROM   boxtal_webhook_events
WHERE  event_type = 'TRACKING_CHANGED';

-- 3. Événements reçus mais jamais traités (problème dans votre tâche planifiée)
SELECT COUNT(*) FROM boxtal_webhook_events
WHERE  processed_at IS NULL AND received_at < NOW() - INTERVAL 1 HOUR;

Une tâche planifiée qui alerte

<?php
// surveillance_webhooks.php : à lancer par cron toutes les heures
// 0 * * * * php /chemin/vers/surveillance_webhooks.php
$alertes = [];

// Expéditions en cours = créées ces 15 derniers jours et sans suivi final
$enCours = (int)$pdo->query("SELECT COUNT(*) FROM shop_shipments
                             WHERE created_at > NOW() - INTERVAL 15 DAY AND tracking_final = 0")->fetchColumn();
$dernier = $pdo->query("SELECT MAX(received_at) FROM boxtal_webhook_events
                        WHERE event_type = 'TRACKING_CHANGED'")->fetchColumn();

if ($enCours > 0 && (!$dernier || strtotime($dernier) < time() - 24 * 3600)) {
    $alertes[] = "Aucun événement de suivi depuis " . ($dernier ?: 'jamais') . " alors que $enCours expédition(s) sont en cours.";
}

// Les souscriptions sont-elles toujours actives ? (une fois par jour suffit)
$rep = boxtalGet('/shipping/v3.1/subscription');      // votre fonction d'appel authentifié
$actives = [];
foreach ($rep['content'] ?? [] as $sub) {
    if (($sub['status'] ?? '') === 'ACTIVE') $actives[] = $sub['eventType'];
}
foreach (['DOCUMENT_CREATED', 'TRACKING_CHANGED'] as $type) {
    if (!in_array($type, $actives, true)) $alertes[] = "Pas de souscription active pour $type.";
}

if ($alertes) {
    mail('tech@maboutique.fr', '[Boxtal] Problème de webhooks', implode("\n", $alertes));
}

Astuce de test : sur l'environnement de test, des événements de suivi fictifs sont générés toutes les 20 minutes. Coupez volontairement votre URL de réception pour vérifier que l'alerte se déclenche.

Exemples de notifications

Exemples tirés de la spécification. Le champ shipmentExternalId reprend votre externalId : pratique pour retrouver la commande de votre boutique.

Intégration pas à pas

1. Créer une application « Composant Carte »

Dans l'espace développeur, page Applications. Vous obtenez une clé d'accès et une clé secrète, distinctes de vos clés API v3.

2. Générer le jeton de la carte (côté serveur)

Votre serveur appelle l'endpoint d'authentification avec les clés Carte, puis transmet accessToken à la page. Détails ci-dessous.

3. Charger le script

La version « globale » est la plus simple à utiliser dans une page classique : elle crée l'objet BoxtalParcelPointMap dans la page. C'est celle utilisée dans les exemples ci-dessous.

<script src="https://maps.boxtal.com/app/v3/assets/dependencies/@boxtal/parcel-point-map/dist/index.global.js"></script>

D'autres versions existent pour les projets construits avec des modules JavaScript (dist/index.js, dist/index.mjs, ou le paquet npm @boxtal/parcel-point-map). Leur mode d'import est décrit dans la documentation de la carte.

4. Prévoir l'emplacement

<div id="parcel-point-map" style="width:100%;height:520px"></div>

5. Initialiser la carte

Avec la version globale, la classe se trouve dans l'objet du même nom : new BoxtalParcelPointMap.BoxtalParcelPointMap(…). Les réseaux affichés et les options se placent dans config.

const boxtalMaps = new BoxtalParcelPointMap.BoxtalParcelPointMap({
    domToLoadMap: '#parcel-point-map',          // sélecteur de l'élément qui accueille la carte
    accessToken: token,                         // jeton obtenu par votre serveur (clés Composant Carte)
    config: {
        locale: 'fr',                           // langue de la carte
        parcelPointNetworks: [{ code: 'MONR_NETWORK' }],   // réseau(x) de l'offre choisie
        options: {
            primaryColor: '#4CAF50',            // couleur des marqueurs et des boutons
            autoSelectNearestParcelPoint: false // true : présélectionne le point le plus proche
        }
    }
});

6. Lancer la recherche et récupérer le choix

L'adresse de recherche utilise les champs street, postalCode, city et country (code ISO), ainsi que la liste des réseaux. La fonction de rappel reçoit le point choisi par le client.

boxtalMaps.searchParcelPoints({
    street: '4 boulevard des Capucines',        // facultatif
    postalCode: '75009',
    city: 'Paris',
    country: 'FR',
    networks: ['MONR_NETWORK']
}, (parcelPoint) => {
    // Appelée quand le client choisit un point
    document.getElementById('pickup_point').value = parcelPoint.code;
});

Lancez la recherche juste après la création de la carte (à l'ouverture de la page), ou sur un bouton « Afficher les points relais ».

Le jeton de la carte

Même principe que pour l'API : POST https://api.boxtal.com/iam/account-app/token avec Authorization: Basic base64(cléAccès:cléSecrète), mais avec les clés de l'application Carte. La spécification de la carte ne mentionne que le serveur de production.

Exemple de petit script serveur

<?php
// carte_token.php : appelé par votre page de commande
$cle    = 'CLE_ACCES_CARTE';
$secret = 'CLE_SECRETE_CARTE';

$ch = curl_init('https://api.boxtal.com/iam/account-app/token');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_USERPWD        => $cle . ':' . $secret, // Basic Auth
    CURLOPT_RETURNTRANSFER => true,
]);
$reponse = json_decode(curl_exec($ch), true);
curl_close($ch);

header('Content-Type: application/json');
echo json_encode(['accessToken' => $reponse['accessToken'] ?? null]);

Mettez le jeton en cache côté serveur pendant sa durée de validité plutôt que d'en redemander un à chaque visite.

Configurateur de code

Remplissez les champs : le code complet de la page de commande se met à jour.

Exemples de demandes

Avant de coder : module officiel ou API ?

Boxtal propose déjà des intégrations officielles et gratuites : le module Boxtal Connect pour WooCommerce et pour PrestaShop, et l'application Boxtal pour Shopify. Elles synchronisent les commandes avec Boxtal, affichent la carte des points relais dans la boutique et mettent à jour le suivi des commandes expédiées.

Documentation des intégrations officielles : WooCommerce, PrestaShop, Shopify.

Conseil : quel CMS choisir pour une intégration sur mesure ?

Si le site n'existe pas encore et que la gestion des expéditions doit être personnalisée avec l'API Boxtal, le choix du CMS compte beaucoup. Le critère décisif est simple : pouvez-vous exécuter votre propre code sur le serveur de la boutique et modifier librement la page de commande ?

Notre recommandation

• Pour intégrer l'API le plus facilement : PrestaShop ou WooCommerce, hébergés sur votre propre serveur. Le code tourne au même endroit que la boutique, la page de commande est modifiable, et ces deux CMS prévoient nativement des transporteurs et des méthodes de livraison.
  • PrestaShop a l'architecture la plus proche du besoin : ses modules transporteurs et le hook displayCarrierExtraContent sont conçus pour afficher des points relais sous un transporteur. Un bon choix pour une boutique centrée sur le e-commerce, avec un catalogue important.
  • WooCommerce convient bien si le site mêle contenu et boutique, ou si l'équipe connaît déjà WordPress. Pour simplifier l'intégration de la carte, utilisez le checkout classique plutôt que le checkout en blocs.
• Shopify est le plus simple à exploiter au quotidien, mais le moins souple pour une intégration sur mesure : application à héberger, checkout fermé hors Shopify Plus, tarifs calculés selon le forfait. Sur Shopify, l'application officielle Boxtal reste souvent la meilleure solution.
• WordPress seul suffit pour expédier sans boutique en ligne (formulaire de demande, envois créés depuis l'administration).

Cette recommandation porte uniquement sur la facilité d'intégration de l'API Boxtal. Le choix d'un CMS dépend aussi du budget, du volume de commandes, des compétences de l'équipe et des autres fonctionnalités attendues.

Les principes communs à tous les CMS

Quel que soit le CMS, une intégration directe de l'API repose sur les mêmes briques. Ce sont aussi les points sur lesquels butent le plus souvent les intégrations faites maison.

Le composant Carte de Boxtal, sur tous les CMS

Pour faire choisir le point relais sur une carte, le plus simple est d'utiliser le composant Carte de Boxtal : un script prêt à l'emploi qui affiche les points relais autour de l'adresse du client et renvoie le point choisi. Son intégration suit toujours le même schéma, seul l'emplacement change selon le CMS :

1. Une application « Composant Carte » créée dans l'espace développeur Boxtal, avec ses propres clés, distinctes des clés API v3.
2. Un jeton fourni par le serveur : le site obtient le jeton avec les clés Carte, le garde en cache pendant sa durée de validité et le transmet à la page par une petite adresse dédiée. Les clés ne quittent jamais le serveur.
3. Le script de la carte (maps.boxtal.com, ou le paquet npm @boxtal/parcel-point-map), chargé uniquement sur la page où le choix se fait.
4. Un emplacement assez grand dans la page (la liste des points s'affiche à côté ou sous la carte selon la place disponible).
5. La recherche lancée avec l'adresse de livraison saisie par le client.
6. Le point choisi, reçu par la fonction de rappel de la carte, recopié dans un champ caché ou envoyé au serveur, puis enregistré sur la commande.

WordPress sans WooCommerce

Cas d'usage : site vitrine, association ou service qui expédie sans boutique en ligne : envois créés depuis l'administration, formulaire de demande d'expédition, retours clients… Il n'y a ni panier ni méthode de livraison : tout passe par une petite extension maison.

Comment l'intégrer

• Une extension dédiée, plutôt que le fichier functions.php du thème, dont le code est perdu au changement de thème.
• Les clés déclarées comme constantes dans wp-config.php, hors de la base de données et hors des sauvegardes de contenu.
• Les appels à Boxtal passent par les fonctions HTTP de WordPress (wp_remote_post(), wp_remote_get()), qui gèrent proxy et certificats. Le jeton est conservé dans un transient (cache temporaire de WordPress) pendant un peu moins que sa durée de validité.
• La réception des webhooks se fait par une route de l'API REST WordPress (adresse du type /wp-json/votre-extension/v1/webhook). Elle doit être publique et lire le corps brut de la requête pour vérifier la signature.

Le composant Carte

• Où l'afficher : sur la page du formulaire d'expédition, dans un bloc, un code court (shortcode) ou le gabarit de la page.
• Le script se charge uniquement sur cette page, avec le système de scripts de WordPress (wp_enqueue_script()).
• Le jeton Carte est fourni par une route REST de l'extension, qui l'obtient avec les clés Carte et le garde dans un transient.
• L'adresse de recherche vient des champs du formulaire. Le point choisi est recopié dans un champ caché, envoyé avec le formulaire et enregistré avec la demande d'expédition.
• Extensions de formulaires (Contact Form 7, Gravity Forms, WPForms…) : elles acceptent des champs cachés. Le script de la carte n'a qu'à remplir ce champ.

Limites et pièges

• WP-Cron ne s'exécute que lors des visites : sur un site peu fréquenté, les tâches planifiées (surveillance des webhooks, rattrapage) prennent du retard. Désactivez-le avec la constante DISABLE_WP_CRON et appelez wp-cron.php depuis un vrai cron du serveur.
• Extensions de sécurité et de cache : certaines bloquent l'API REST pour les visiteurs non connectés, ou mettent les réponses en cache. Excluez la route de webhook de leurs règles.
• Hébergeurs mutualisés : vérifiez que les appels sortants vers api.boxtal.com ne sont pas bloqués et que le délai maximal d'exécution PHP suffit.

WordPress avec WooCommerce

WooCommerce fournit le panier, les zones de livraison et le cycle de vie des commandes. L'intégration branche Boxtal à trois endroits : le calcul des frais de port, le choix du point relais et le passage de la commande au statut « En cours » (payée).

Comment l'intégrer

• Une méthode de livraison : l'extension déclare une méthode (classe dérivée de WC_Shipping_Method) que le marchand ajoute à ses zones de livraison, par exemple « Point relais » et « Domicile ». Chaque méthode correspond à une offre Boxtal et renvoie un tarif fixe ou une cotation API v1 mise en cache.
• Le point relais : le composant Carte s'affiche quand la méthode relais est sélectionnée. Le code du point est enregistré dans les métadonnées de la commande (voir ci-dessous).
• La création de l'expédition : déclenchée au passage au statut « En cours », mais exécutée en tâche de fond grâce à Action Scheduler, la file de tâches intégrée à WooCommerce. La validation de la commande n'attend ainsi pas la réponse de Boxtal, et un échec peut être relancé.
• Les webhooks : une route REST met à jour la commande (note interne, numéro de suivi, statut « Terminée » à la livraison) et peut envoyer le lien de suivi au client.

Le composant Carte

• Checkout classique : la carte s'insère sous les méthodes de livraison, à l'aide des emplacements prévus par le gabarit de commande. Elle s'affiche quand la méthode relais est cochée. WooCommerce recharge cette zone à chaque changement d'adresse ou de méthode : il faut réafficher la carte à chaque rechargement (événement JavaScript updated_checkout). Le point choisi est recopié dans un champ caché du formulaire, contrôlé à la validation (commande refusée si aucun point n'est choisi), puis enregistré sur la commande.
• Checkout en blocs : la page est construite en JavaScript (React). La carte doit être intégrée par un composant JavaScript propre aux blocs, et le point choisi transmis au serveur par la Store API de WooCommerce. C'est sensiblement plus long à développer : beaucoup de marchands repassent la page de commande en checkout classique pour cette raison.
• Jeton Carte : fourni par une route REST de l'extension, mis en cache dans un transient.
• Après la commande : affichez le point choisi dans le récapitulatif, l'e-mail de confirmation et la fiche commande de l'administration.

Limites et pièges

• Le checkout en blocs est la norme : depuis WooCommerce 8.3 (novembre 2023), les nouvelles boutiques utilisent par défaut un panier et une page de commande construits en blocs. Les hooks PHP de l'ancien checkout n'y fonctionnent pas. Afficher la carte et enregistrer le point demande alors une intégration propre aux blocs (JavaScript côté page, Store API côté serveur). Vérifiez d'abord quel checkout utilise la boutique. Le checkout classique reste disponible : la page peut être reconvertie en « Classic Shortcode ».
• Déclarer la compatibilité : une extension doit indiquer si elle est compatible avec le checkout en blocs et avec le stockage HPOS, sinon WooCommerce affiche un avertissement au marchand.
• Stockage des commandes (HPOS) : activé par défaut sur les nouvelles installations depuis WooCommerce 8.2, il range les commandes dans des tables dédiées. Toute lecture ou écriture doit passer par l'objet commande de WooCommerce, jamais par les fonctions des articles WordPress (get_post_meta(), update_post_meta()).
• Calcul des frais : il est relancé à chaque modification du panier. Une cotation API v1 sans cache ralentit fortement la commande.
• Double création : un statut peut être appliqué plusieurs fois (paiement relancé, changement manuel par le marchand). Testez toujours la présence de l'identifiant Boxtal sur la commande avant de créer.

Sources : checkout en blocs, HPOS.

PrestaShop

L'intégration prend la forme d'un module, qui crée ses propres transporteurs et s'accroche aux étapes de la commande. Les principes ci-dessous sont valables pour PrestaShop 1.7, 8 et 9.

Comment l'intégrer

• Un module transporteur : un module de type CarrierModule peut créer plusieurs transporteurs, par exemple un par offre Boxtal proposée. Il doit mémoriser chaque transporteur par son id_reference, qui ne change pas, car PrestaShop attribue un nouvel identifiant à un transporteur à chaque modification.
• Les frais de port : PrestaShop demande le prix au module pour chacun de ses transporteurs (getOrderShippingCost()). Le module renvoie un tarif fixe ou une cotation mise en cache.
• Le point relais : le hook displayCarrierExtraContent, prévu par PrestaShop pour afficher des points relais sous un transporteur, accueille le composant Carte à l'étape « Livraison » (voir ci-dessous).
• La création de l'expédition : sur le changement de statut de la commande (hook actionOrderStatusPostUpdate), quand elle passe à « Paiement accepté ».
• Les webhooks : un contrôleur front du module (une page du module accessible publiquement) lit le corps brut et vérifie la signature.
• Les clés : saisies dans la page de configuration du module et stockées dans la configuration de PrestaShop.

Le composant Carte

• Emplacement : le module renvoie, dans displayCarrierExtraContent, l'emplacement de la carte sous son transporteur relais.
• Script : chargé par le module uniquement sur la page de commande, via les fonctions d'ajout de scripts de PrestaShop.
• Jeton Carte : fourni par un contrôleur front du module, appelé en AJAX par la page, qui l'obtient avec les clés Carte et le garde en cache.
• Enregistrement du choix : comme la commande n'existe pas encore à cette étape, le point choisi est envoyé en AJAX au module et enregistré pour le panier en cours (une table du module liée au panier). À la validation de la commande, il est recopié sur la commande.
• Choix obligatoire : bloquez le passage à l'étape « Paiement » si le transporteur relais est choisi sans point sélectionné (contrôle JavaScript, complété côté serveur, par exemple avec le hook actionValidateStepComplete utilisé par de nombreux modules relais).
• Rechargements : l'étape « Livraison » se recharge quand le client change de transporteur ou d'adresse : réaffichez la carte à chaque fois.

Limites et pièges

• Thèmes : PrestaShop 9.1 (mars 2026) fait de Hummingbird 2.0 le thème par défaut, à la place de Classic. Le balisage du tunnel de commande diffère : le JavaScript qui place la carte et lit le choix du client doit être testé sur le thème réellement utilisé.
• Emplacement de la carte : selon le thème ou le module de commande, le contenu de displayCarrierExtraContent n'est visible que lorsque le transporteur est sélectionné, ou pas du tout avec certains modules de commande en une page. Certains modules transporteurs utilisent le hook displayAfterCarrier pour plus de robustesse. Vérifiez la compatibilité.
• Multi-transporteurs : PrestaShop 9.1 introduit, derrière une option à activer, la possibilité d'expédier une commande avec plusieurs transporteurs. Une commande peut alors donner lieu à plusieurs expéditions Boxtal : prévoyez une expédition par envoi, pas une par commande.
• Mode maintenance : il bloque l'accès public aux pages, y compris l'URL de webhook. Recevez les webhooks sur une préproduction publique.
• Optimisation JavaScript (CCC) : la compilation des scripts peut casser le chargement du script de la carte. Chargez-le en dehors de la compilation si besoin.

Sources : modules transporteurs, hook displayCarrierExtraContent (documentation PrestaShop 9).

Shopify

Shopify est une plateforme hébergée : aucun code PHP ne peut y être exécuté. L'intégration passe par une application, hébergée sur votre propre serveur, qui dialogue à la fois avec Shopify et avec Boxtal.

Comment l'intégrer

• Créer l'application : depuis le 1er janvier 2026, une nouvelle application personnalisée ne peut plus être créée depuis l'administration de la boutique. Elle se crée dans le Dev Dashboard de Shopify, puis s'installe sur la boutique par un lien d'installation. Les applications créées avant cette date continuent de fonctionner.
• Dialoguer avec Shopify : par l'Admin API en GraphQL. L'API REST est considérée comme héritée : les nouveaux développements doivent utiliser GraphQL.
• Recevoir les commandes payées : l'application s'abonne aux webhooks Shopify (par exemple orders/paid), puis crée l'expédition Boxtal. Ces webhooks ont leur propre signature (en-tête X-Shopify-Hmac-Sha256), distincte de celle de Boxtal.
• Renvoyer le suivi à Shopify : à la réception des événements Boxtal, l'application crée un « fulfillment » (expédition Shopify) avec le numéro et le lien de suivi, par la mutation fulfillmentCreate (fulfillmentCreateV2 est dépréciée). Elle vise les fulfillment orders de la commande, pas la commande elle-même. Shopify peut alors envoyer lui-même l'e-mail d'expédition au client.
• Afficher des frais de port calculés : via l'API CarrierService (« carrier-calculated shipping »). Elle est incluse dans les forfaits Advanced et Plus. Sur le forfait Shopify, elle s'obtient moyennant un supplément mensuel ou en passant à la facturation annuelle. Elle n'est pas disponible sur les forfaits Basic et Starter, où l'on utilise des tarifs fixes configurés dans Shopify.

Le point relais : la vraie difficulté

Le checkout Shopify ne peut pas être modifié librement :

• Les extensions affichées aux étapes d'information, de livraison et de paiement du checkout sont réservées au forfait Shopify Plus. La fiche de l'application officielle Boxtal indique d'ailleurs que l'intégration de la carte au checkout concerne les utilisateurs de Shopify Plus.
• L'API de Shopify qui ajoute des points relais natifs dans le checkout (Pickup Point Delivery Option Generator) est réservée aux applications personnalisées des boutiques Shopify Plus, sur demande d'accès.
• Les pages « Merci » et « Statut de la commande » acceptent des extensions sur tous les forfaits, à partir de Basic.

Hors Shopify Plus, deux solutions sont couramment utilisées :

• Choisir le point relais sur la page panier, avant le checkout, avec le composant Carte intégré au thème. Le code du point est mémorisé dans un attribut de panier, recopié automatiquement sur la commande. Risque : le client peut ensuite choisir une autre méthode de livraison au checkout. Contrôlez la cohérence avant de créer l'expédition.
• Faire choisir le point après l'achat, sur la page « Merci » ou « Statut de la commande », grâce à une extension. Prévoyez une relance si le client ne fait pas son choix, et un délai avant de créer l'expédition.

Le composant Carte

• Dans le thème (page panier) : c'est là que le composant Carte s'intègre sans restriction, sur tous les forfaits. L'emplacement et le script s'ajoutent au thème, de préférence par un bloc d'application (theme app extension) fourni par votre application, que le marchand place lui-même dans l'éditeur de thème sans modifier le code.
• Jeton Carte : la solution la plus courante est le proxy d'application (app proxy) de Shopify : une adresse sur le domaine de la boutique (par exemple /apps/boxtal/jeton) que Shopify relaie vers votre application, qui renvoie le jeton. Cela évite les problèmes d'appel entre domaines, et Shopify signe chaque requête relayée, ce qui permet à l'application de vérifier qu'elle vient bien de la boutique.
• Dans le checkout et sur les pages « Merci » / « Statut de la commande » : les extensions Shopify n'acceptent que les composants d'interface de Shopify, sans script externe ni accès à la page. Le composant Carte ne peut donc pas y être chargé tel quel. On y affiche plutôt une liste de points obtenue par votre application avec la recherche de points relais par offre, ou l'on utilise l'application officielle Boxtal, qui prend en charge la carte au checkout pour les boutiques Shopify Plus.

Limites et pièges

• Hébergement obligatoire : l'application doit tourner en permanence sur un serveur HTTPS pour recevoir les webhooks de Shopify et de Boxtal.
• Versions de l'API Shopify : une nouvelle version sort chaque trimestre et les plus anciennes sont retirées au bout d'environ un an. Prévoyez une mise à jour régulière de l'application.
• Droits d'accès : l'application doit demander les autorisations sur les commandes et les « fulfillment orders » dont elle a besoin, ni plus ni moins.

Sources : tarifs calculés par transporteur, personnalisation de la livraison au checkout, points relais natifs, application Boxtal.

Synthèse et astuces

• Commencez par le flux le plus simple : création d'expédition manuelle depuis l'administration, puis automatisez une fois les données validées.
• Préparez les données produit : poids et dimensions de chaque produit, catégorie de contenu par type de produit. Sans elles, ni tarif ni expédition fiables.
• Gardez une trace sur la commande : identifiant Boxtal, code du point relais, dernier statut de suivi, étiquette archivée.
• Vérifiez vos payloads avec l'outil de vérification shipping-order avant de les envoyer en production.

• API v3 : guide de démarrage
• API v3 : documentation de référence
• Composant Carte : guide de démarrage
• Composant Carte : documentation
• Composant Carte : démo
• API v1 : documentation (cotation)

Ce guide est construit à partir de la spécification OpenAPI v3 (version 3.1.0) et de la spécification du composant Carte (version 1.0.0). En cas de doute, la documentation officielle fait foi.