--- title: "Événements : expéditions" description: "Quand partent les webhooks d'expédition (création, modification, suppression), ce qu'ils contiennent et quelles cascades les déclenchent." url: https://www.ciklik.academy/fr/webhooks/evenements-expeditions/ lang: fr lastUpdated: 2026-10-09 --- # Événements : expéditions > Box et PrestaShop > > Cette page vaut pour les boutiques box comme pour les boutiques PrestaShop. Les bons de livraison n’existent que sur les boutiques box. Cette page détaille les trois clés d’événement liées à l’expédition : `created_shippingbox`, `updated_shippingbox`, `deleted_shippingbox`. Une expédition (“shippingbox”) est un colis planifié : un abonnement en génère une à chaque cycle, une commande boutique peut en générer une directement. Pour la configuration générale, voir [Comprendre un envoi de webhook](https://www.ciklik.academy/fr/webhooks/comprendre-un-envoi-de-webhook/). ## Objet expédition Chaque envoi lié à une expédition porte l’objet complet. | Champ | Type | Nullable | Sens | | ------------------------------ | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `tenant_id` | entier | non | boutique propriétaire | | `id` | entier | non | identifiant interne | | `uuid` | chaîne | non | identifiant public | | `address` | objet | oui | voir [Objet adresse](https://www.ciklik.academy/fr/webhooks/evenements-clients-adresses-optins/#objet-adresse) | | `transporter` | objet | oui | voir [Objet transporteur](#objet-transporteur) | | `created_at` | date ISO 8601 | non | création | | `updated_at` | date ISO 8601 | non | dernière modification | | `scheduled_at` | date ISO 8601 | oui | départ planifié | | `tracking_link` | chaîne | oui | nul sans numéro de suivi (combiné à l’URL de suivi du transporteur) ni URL de suivi enregistrée directement sur l’expédition | | `subscription_uuid` | chaîne | oui | abonnement d’origine ; nul pour une expédition boutique | | `address_id` | entier | oui | id de l’adresse | | `phone` | chaîne | oui | téléphone destinataire | | `status` | chaîne | non | libre (`created`, `shipped`…), **pas** une énumération fermée | | `tracking_number` | chaîne | oui | numéro de suivi | | `customer_id` | chaîne | oui | id **public** du client (`cus_...`), **pas** le numérique | | `supply_id` | chaîne | oui | lot logistique | | `transporter_id` | entier | oui | id du transporteur | | `first_name` | chaîne | oui | prénom destinataire | | `last_name` | chaîne | oui | nom destinataire | | `postcode` | chaîne | oui | code postal | | `address1` | chaîne | oui | adresse | | `address2` | chaîne | oui | complément | | `division` | chaîne | oui | subdivision administrative | | `city` | chaîne | oui | ville | | `country` | chaîne | oui | pays | | `mail` | chaîne | oui | e-mail client à l’envoi | | `subscriptions_count` | chaîne | oui | abonnements du client, **en chaîne** | | `transporter_name` | chaîne | oui | nom du transporteur | | `shipped_count` | chaîne | oui | envois du cycle, **en chaîne** | | `site_name` | chaîne | oui | boutique | | `options` | chaîne | oui | déclinaison, valeurs séparées par `\|` | | `iso_code` | chaîne | oui | code pays ISO | | `relay` | objet | oui | point relais choisi | | `relay_id` | chaîne | oui | id du point relais | | `orderable_name` | chaîne | oui | nom du produit expédié | | `orderable_id` | chaîne | oui | id du produit, **en chaîne** | | `orderable_type` | chaîne | oui | type de produit expédié : formule (`App\Plan`) ou produit (`App\Product`) | | `order_id` | entier | oui | commande liée | | `ref` | chaîne | oui | référence produit | | `customization_products` | tableau | oui | choix de personnalisation | | `extra_customization_products` | tableau | oui | personnalisations ajoutées après coup | ## Objet transporteur L’objet `transporter` suit la structure décrite ci-dessous. Il est nul quand l’expédition n’a pas de transporteur assigné. | Champ | Type | Nullable | Sens | | ------------------ | ---------------- | -------- | -------------------------------- | | `id` | entier | non | identifiant interne | | `countries` | tableau d’objets | non | pays couverts (`id`, `name`) | | `plan_blacklisted` | tableau d’objets | non | formules exclues (`id`, `name`) | | `name` | chaîne | non | nom du transporteur | | `description` | chaîne | oui | description commerciale | | `price` | nombre | non | prix, flottant | | `gift` | booléen | non | disponible pour une carte cadeau | | `active` | booléen | non | transporteur actif | | `shipped_count` | entier | non | envois par cycle | | `type` | chaîne | non | type de transporteur | | `relayOptions` | objet | oui | voir ci-dessous | `relayOptions` est une **structure non contractuelle** : son contenu varie selon le transporteur relais choisi (Mondial Relay, Colissimo, DPD) et peut changer sans préavis. N’en exploitez pas les clés individuellement. Dans les exemples de cette page, il vaut `null` (pas de point relais). ## `created_shippingbox` Objet envoyé : expédition complète. Délai avant l’envoi : aucun. Exemple complet : dans le contrat OpenAPI (`/openapi/ciklik-webhooks.yaml`), webhook `created_shippingbox`. ### Quand il part - Création ou renouvellement d’un abonnement (génération standard, y compris boutique composable). - Commande boutique générant directement une expédition, hors abonnement. - **Report anti-churn** : un report d’échéance produit un `updated_subscription` suivi d’**autant de `created_shippingbox` que de mois reportés**. Voir [Événements : abonnements](https://www.ciklik.academy/fr/webhooks/evenements-abonnements/#updated_subscription). ### Quand il ne part pas Aucun cas connu : toute création d’expédition déclenche l’envoi. ### Ce que contient changed Toujours un tableau vide (`[]`) : un `created_*` n’a par définition rien à comparer à un état antérieur. ### Effets en cascade Aucun, au-delà de son origine. Le cas du report anti-churn est lui-même un effet en cascade d’un `updated_subscription`, pas l’inverse. ### Exemple ```json { "tenant_id": 1, "id": 1, "uuid": "c636e863-bdf5-4914-b108-05e117cb0c12", "address": { "id": 1, "user_id": 1, "address": "12 rue des Lilas", "address1": "Bâtiment B, 3e étage", "postcode": "69003", "city": "Lyon", "phone": "+33612345678", "first_name": "Claire", "last_name": "Martin", "region_id": 1, "division": null, "division_name": null, "deletable": false, "company_name": null, "country": { "id": 1, "name": "France", "alphaCode": "FR" }, "external_id": 4821 }, "transporter": { "id": 1, "countries": [ { "id": 1, "name": "France" } ], "plan_blacklisted": [], "name": "Colissimo domicile", "description": "Livraison à domicile sous 48h", "price": 4.9, "gift": false, "active": true, "shipped_count": 1, "type": "subs", "relayOptions": null }, "created_at": "2026-09-10T08:15:42.000000Z", "updated_at": "2026-09-10T08:15:42.000000Z", "scheduled_at": "2026-09-15T00:00:00.000000Z", "tracking_link": null, "subscription_uuid": "sub_N8PxGUEdS2U7DP", "address_id": 1, "phone": "+33612345678", "status": "created", "tracking_number": null, "customer_id": "cus_Qx7hR3eaEowcv1DX", "supply_id": null, "transporter_id": 1, "first_name": "Claire", "last_name": "Martin", "postcode": "69003", "address1": "12 rue des Lilas", "address2": "Bâtiment B, 3e étage", "division": null, "city": "Lyon", "country": "France", "mail": "claire.martin@example.com", "subscriptions_count": "1", "transporter_name": "Colissimo domicile", "shipped_count": "1", "site_name": "Boutique Exemple", "options": null, "iso_code": "fr", "relay": null, "relay_id": null, "orderable_name": "Box mensuelle", "orderable_id": "1", "orderable_type": "App\\Plan", "order_id": 1, "ref": "BOX-MENSUELLE", "customization_products": [ { "id": 1, "quantity": 1 } ], "extra_customization_products": null, "changed": [] } ``` ## `updated_shippingbox` Objet envoyé : expédition complète, dans son état au moment de l’envoi. Délai avant l’envoi : aucun. Exemple complet : dans le contrat OpenAPI (`/openapi/ciklik-webhooks.yaml`), webhook `updated_shippingbox`. ### Quand il part - Modification directe de l’expédition (adresse, statut, numéro de suivi…) par l’API vendors ou depuis le back-office (**Ventes > Bons de livraison**). - Cascade depuis une adresse, un abonnement ou un client modifié : voir “Effets en cascade”. ### Quand il ne part pas - Liaison d’une expédition à sa commande d’origine (écriture silencieuse). - Ajout de personnalisations supplémentaires depuis l’interface interne (`extra_customization_products`, écriture silencieuse). - Recalcul du compteur `shipped_count` ou correctif d’options par une commande de maintenance interne. > Le passage à “expédié” n’est pas toujours notifié > > Le passage du statut à `shipped` déclenche un `updated_shippingbox` quand il est posé par l’API vendors (`POST /deliveries/{id}`, champ `status` ou `tracking_number`) ou par l’action **Ajouter des numéros de suivi** de la fiche Site, option de passage au statut expédié cochée. Il **n’en déclenche aucun** quand il provient du connecteur logistique Wonderweb : c’est l’un des pièges les plus coûteux pour un intégrateur qui attendrait ce webhook pour notifier un client ou mettre à jour un stock sur ces canaux. En cas de doute sur l’origine du passage à `shipped`, interrogez l’API plutôt que d’attendre un webhook. ### Ce que contient changed Un objet `{colonne : valeur brute}`. > Attention à l’interprétation > > Avant l’envoi, Ciklik resynchronise depuis l’adresse et l’abonnement liés les champs `first_name`, `last_name`, `phone`, `postcode`, `address1`, `address2`, `city`, `country`, `mail`, `subscriptions_count`, `transporter_name`, `iso_code`, `relay` et `relay_id` : les champs texte sont réécrits en **majuscules et sans accents**, indépendamment de ce que l’appelant a réellement modifié. Le `changed` contient donc ces champs synchronisés **en plus** de ceux modifiés par l’appelant, sans distinction entre les deux : n’en déduisez pas que le client a saisi son adresse en majuscules. Un même changement peut aussi produire **deux** envois `updated_shippingbox` pour la même expédition, quand un traitement interne enregistre deux fois la même expédition. ### Effets en cascade Trois origines produisent, chacune, un `updated_shippingbox` par expédition planifiée depuis le premier jour de l’avant-dernier mois (M-2, par exemple le 1er juillet pour un envoi en septembre), expéditions déjà parties incluses : | Origine | Déclencheur | Portée | | ---------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | Adresse | `updated_address`, quel que soit le champ modifié | chaque abonnement lié à l’adresse | | Abonnement | changement d’adresse, de transporteur, de déclinaison, de point relais ou de personnalisation produit | l’abonnement modifié | | Client | **changement de l’e-mail du client** | chaque abonnement du client, en plus de l’`updated_user` | La cascade du changement d’e-mail est établie dans le code : un client dont l’e-mail change et qui a 12 expéditions dans cette fenêtre déclenche 1 `updated_user` puis **12 `updated_shippingbox`** (détail sur [Événements : clients, adresses et inscriptions](https://www.ciklik.academy/fr/webhooks/evenements-clients-adresses-optins/#updated_user)). Le changement sur l’abonnement déclenche en plus un ou deux `updated_checkoutorder` par commande en cours de création (voir [Événements : commandes, transactions et factures](https://www.ciklik.academy/fr/webhooks/evenements-commandes-transactions-factures/)). ### Exemple ```json { "changed": { "phone": "06 12 34 56 78", "first_name": "CLAIRE", "last_name": "MARTIN", "postcode": "69007", "address1": "27 AVENUE JEAN JAURES", "address2": "", "city": "LYON", "country": "FRANCE", "mail": "claire.martin-dupont@example.com", "status": "shipped", "tracking_number": "6A12345678901" } } ``` Le reste de la charge utile est identique à celle de `created_shippingbox`. Ici, `first_name`, `last_name`, `address1`, `city`, `country`, `phone`, `postcode` et `mail` proviennent de la resynchronisation ; seuls `status` et `tracking_number` sont réellement modifiés par l’appelant. ## `deleted_shippingbox` Objet envoyé : expédition complète, même après suppression (l’état est relu au moment de l’envoi, sans tenir compte de la suppression). Délai avant l’envoi : aucun. Exemple complet : dans le contrat OpenAPI (`/openapi/ciklik-webhooks.yaml`), webhook `deleted_shippingbox`. ### Quand il part - Suppression via l’API vendors, `DELETE /deliveries/{id}`. - Validation d’une demande de rétractation (action **Valider la rétractation** de la commande), avec l’option **Supprimer les bons de livraison** : seules les expéditions **futures** sont supprimées. - Remboursement d’une transaction (action **Rembourser** de la transaction), avec l’option **Supprimer les bons de livraison** : **toutes** les expéditions de la commande sont supprimées, passées et futures. ### Quand il ne part pas > Des expéditions supprimées sans aucun envoi > > La résiliation d’un abonnement depuis le back-office (action **Résilier l’abonnement**), avec l’option **Supprimer les bons de livraison futurs**, les supprime par une écriture en masse qui ne déclenche pas de webhook. Aucun `deleted_shippingbox` ne part dans ce cas : un intégrateur qui synchronise ses expéditions uniquement par webhook garde en base des expéditions qui n’existent déjà plus chez Ciklik. ### Ce que contient changed Toujours `{"deleted": true}`, quelle que soit l’expédition. ### Effets en cascade Aucun effet en cascade propre à la suppression n’est documenté : elle intervient en fin de parcours (retrait validé ou remboursement), sans autre webhook associé. ### Exemple ```json { "changed": { "deleted": true } } ``` Le reste de la charge utile est identique à celle de `created_shippingbox`. ## Voir aussi [Comprendre un envoi de webhook](https://www.ciklik.academy/fr/webhooks/comprendre-un-envoi-de-webhook/) [Événements : abonnements](https://www.ciklik.academy/fr/webhooks/evenements-abonnements/) [Bonnes pratiques et dépannage](https://www.ciklik.academy/fr/webhooks/bonnes-pratiques-et-depannage/)