> ## Documentation Index
> Fetch the complete documentation index at: https://www.zippendo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API du canal personnalisé
> Créez un canal de vente personnalisé, copiez l'URL de réception et le secret de signature, réglez les interrupteurs Opérations et envoyez une commande signée depuis votre propre boutique en ligne ou ERP.
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](/docs/fr/tutorials/connect-order-channels). La référence complète du payload se trouve dans [Canaux personnalisés](/docs/fr/order-channels/custom-channels).
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**.
## 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.**
| 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](/docs/fr/order-channels/custom-channels).
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/`. 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 :
**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.
```javascript theme={null}
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](/docs/fr/order-channels/custom-channels).
| 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](/docs/fr/how-to/create-an-api-token). 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](/docs/fr/how-to/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.
## 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.
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](/docs/fr/how-to/order-channel-settings).
## 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
Créez le canal depuis le catalogue, puis ouvrez Commandes.
Payload complet, annulation, ping et exemples REST.
La page Canaux de vente, les marques et les canaux orphelins.
Un jeton pour POST /orgs/\{orgId}/orders au lieu des envois signés.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.