API du canal personnalisé

Un canal personnalisé permet à votre propre boutique en ligne, ERP ou système d’entrepôt d’envoyer des commandes directement dans Zippendo, lorsqu’il n’existe pas de connexion prête à l’emploi. Cette page décrit chaque commande de la fenêtre de création et des paramètres du canal, et la façon dont un développeur envoie une commande. Le parcours en clics est décrit dans Connecter des canaux de vente. La référence complète du payload se trouve dans Canaux personnalisés. Cliquez sur Canaux de vente dans la barre latérale, puis sur l’onglet Catalogue. La carte Canal personnalisé indique Connectez votre propre boutique en ligne ou votre ERP. Son bouton est Créer un canal.

Catalogue des canaux de vente avec la carte Canal personnalisé et le bouton Créer un canal — La carte Canal personnalisé dans le catalogue

Créer le canal

Cliquez sur Créer un canal. La fenêtre Créer un canal personnalisé s’ouvre : Un canal de vente pour votre propre boutique en ligne ou votre ERP.

Fenêtre Créer un canal personnalisé avec Nom du canal renseigné à Ma boutique, Créer un canal et Annuler — Créer un canal personnalisé : saisissez un Nom du canal

Champ	Obligatoire	Ce qu’il faut saisir
Nom du canal	Oui	Un nom que vous reconnaissez, par exemple « Ma boutique ». Créer un canal reste inactif tant que vous n’en saisissez pas un.
Marque	Non	Affiché uniquement lorsque votre organisation a des marques. Les commandes de ce canal appartiennent à cette marque.

Cliquez sur Créer un canal (le bouton affiche Création…). Vous voyez Canal de vente créé, et Zippendo ouvre les paramètres du nouveau canal. Si vous voyez Impossible de créer le canal de vente, réessayez. Annuler ferme la fenêtre.

Réception des commandes

La page de paramètres a pour titre le nom du canal et Votre propre intégration : envoyez les commandes à l’URL de réception ou utilisez l’API et les SDK. Voir la documentation ouvre la référence Canaux personnalisés.

La carte Réception des commandes : Votre système envoie des commandes signées à l’URL de réception ci-dessous. Signez le corps brut de chaque requête avec HMAC-SHA256, à l’aide du secret de signature.

Commande	Ce qu’elle fait
URL de réception	L’adresse à laquelle votre système envoie les commandes, sous la forme `https://api.zippendo.com/webhooks/order-channels/<channel id>`. Copiez-la depuis votre propre canal. Copier affiche Copié dans le presse-papiers., ou Impossible de copier dans le presse-papiers.
Générer un secret	Crée le secret de signature. Affiche Génération…, puis Secret de signature généré. ou Impossible de générer le secret de signature.
Remplacer le secret	Remplace un secret existant. Zippendo vous demande de confirmer : votre système est rejeté tant qu’il ne signe pas avec le nouveau secret.
Révoquer	Désactive le secret. Toutes les commandes envoyées par votre système sont rejetées tant que vous n’avez pas généré un nouveau secret. Affiche Secret de signature révoqué. ou Impossible de révoquer le secret de signature.
Secret de signature actif créé le	Suivi de la date et de l’heure de création du secret actuel.

Le canal n’accepte les commandes qu’une fois qu’un secret de signature existe. Il n’y a pas d’interrupteur distinct pour activer la réception. Après Générer un secret ou Remplacer le secret, le secret s’affiche une seule fois :

Réception des commandes avec le secret de signature à affichage unique, Copier, Révoquer et Remplacer le secret — Copiez le secret de signature maintenant. Il ne s'affiche qu'une seule fois

Copiez le secret maintenant. Il ne s’affiche qu’une seule fois. Si vous le remplacez plus tard, le secret actuel cesse immédiatement de fonctionner. Le secret commence par zwhs_. Conservez-le dans la configuration de votre système.

Envoyer une commande

Faites un POST vers l’URL de réception avec deux en-têtes :

En-tête	Valeur
`X-Zippendo-Topic`	`order.created`, `order.updated`, `order.cancelled` ou `ping`
`X-Zippendo-Signature`	HMAC-SHA256 du corps brut de la requête, encodé en hexadécimal, avec le secret de signature comme clé

order.created et order.updated créent ou mettent à jour tous deux la commande selon son externalId. Le corps de order.cancelled est { "externalId": "…" }. ping renvoie 200 { "received": true } sans rien modifier.

import crypto from "node:crypto"

const body = JSON.stringify(order)
const signature = crypto.createHmac("sha256", process.env.ZIPPENDO_WEBHOOK_SECRET)
  .update(body)
  .digest("hex")

await fetch(webhookUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Zippendo-Topic": "order.created",
    "X-Zippendo-Signature": signature
  },
  body
})

Champs obligatoires du payload : externalId, orderNumber et orderLines (au moins une ligne avec name et quantity). Facultatifs : customerName, customerEmail, shippingAddress, subtotalAmount, totalAmount, currency, notes, shippingMethodTitle et serviceCode. Tableau complet des champs : Canaux personnalisés.

Statut	Signification
`200`	Acceptée et traitée
`400`	Topic manquant ou inconnu, payload qui a échoué à la validation, ou Canal activé est désactivé
`401`	Échec de la vérification de la signature : mauvais secret, en-tête manquant, ou aucun secret généré pour l’instant
`404`	Canal inconnu
`429`	Trop de commandes à la fois. Réessayez après le délai `Retry-After`
`5xx`	Échec du traitement. Réessayez : renvoyer la même commande est sans risque

Vous préférez requête et réponse ? Créez des commandes avec POST /orgs/{orgId}/orders, en indiquant orderChannelId, et un jeton d’API. Une seconde commande avec le même externalId sur le même canal renvoie 409 ORDER_EXISTS. Pour récupérer les numéros de suivi et les changements de statut, abonnez-vous aux webhooks de votre organisation (shipment.dispatched, tracking.updated). Un canal personnalisé n’a pas de rappel de suivi propre, ni d’écran de correspondance des modes de livraison. Une commande que vous envoyez apparaît sous Commandes. Son statut peut être Erreur lorsque Zippendo a importé la commande mais n’a pas pu créer une expédition prête à envoyer, par exemple parce qu’aucune règle d’expédition ne correspondait ou que l’adresse est incomplète. La commande appartient toujours au canal.

Liste des commandes avec une commande arrivée par un canal personnalisé — Une commande envoyée par votre système sur la page Commandes

Opérations

Paramètre	Enregistrement	Ce qu’il fait
Canal activé	Immédiat	Active ou désactive le canal. Lorsqu’il est désactivé, Zippendo refuse toutes les commandes envoyées à ce canal.
Envoyer les expéditions automatiquement	Avec Enregistrer les modifications	Envoie automatiquement l’expédition au transporteur lorsqu’une commande entrante correspond à une règle d’expédition. Désactivé par défaut.
Marque	Immédiat	Les commandes de ce canal appartiennent à cette marque. La liste n’apparaît que si votre organisation a des marques.
Adresse de l’expéditeur par défaut	Avec Enregistrer les modifications	L’expéditeur des expéditions lorsqu’aucune règle d’expédition ne correspond à la commande. Tant qu’aucune n’est enregistrée, la liste indique Aucune adresse pour le moment.
Dernière commande reçue	Lecture seule	La date de la dernière commande reçue par le canal, ou Jamais.

Enregistrer les modifications (Enregistrement…) enregistre Envoyer les expéditions automatiquement et Adresse de l’expéditeur par défaut. Vous voyez Canal de vente mis à jour, ou Impossible de mettre à jour le canal de vente.

Désactiver un canal

Désactivez Canal activé. Dans l’onglet Connecté, la ligne du canal dans la carte Canal personnalisé indique alors Désactivée. Les canaux personnalisés restent toujours dans l’onglet Connecté et ne deviennent jamais des canaux orphelins.

Page Canaux de vente avec un canal personnalisé marqué Désactivée — Un canal personnalisé désactivé

Les canaux Shopify ou WooCommerce orphelins, marqués Aucune connexion active et Déconnecté, sont un autre cas. Voir Paramètres du canal de vente.

Supprimer

Sous Zone de danger, repérez Supprimer le canal : Supprimez ce canal personnalisé. Votre intégration ne pourra plus lui envoyer de commandes.

Cliquez sur Supprimer et confirmez : Supprimer ce canal personnalisé ? Son URL de réception cesse immédiatement d’accepter des commandes. Vous voyez Canal de vente supprimé, ou Impossible de supprimer le canal de vente.

Voir aussi

Connecter des canaux de vente

Créez le canal depuis le catalogue, puis ouvrez Commandes.

Référence des canaux personnalisés

Payload complet, annulation, ping et exemples REST.

Paramètres du canal de vente

La page Canaux de vente, les marques et les canaux orphelins.

Créer un jeton d'API

Un jeton pour POST /orgs/{orgId}/orders au lieu des envois signés.

Vue d'ensemble

Expéditions

Commandes et canaux de vente

Transporteurs

Connecter un transporteur

Connecter une intégration

Impression

Automatisation

Compte

Recherche et tableau de bord

API et événements

API du canal personnalisé

Créer le canal

Réception des commandes

Envoyer une commande

Opérations

Désactiver un canal

Supprimer

Voir aussi

Connecter des canaux de vente

Référence des canaux personnalisés

Paramètres du canal de vente

Créer un jeton d'API

​Créer le canal

​Réception des commandes

​Envoyer une commande

​Opérations

​Désactiver un canal

​Supprimer

​Voir aussi

Connecter des canaux de vente

Référence des canaux personnalisés

Paramètres du canal de vente

Créer un jeton d'API

Créer le canal

Réception des commandes

Envoyer une commande

Opérations

Désactiver un canal

Supprimer

Voir aussi