Concepts clés

Cinq objets suffisent à expliquer toute l'API.

Produit

L'élément central du catalogue, géré par Nembol. Il porte toutes les informations commerciales : titre, description (le texte unique que chaque canal publie, HTML autorisé ; short_description n'en est qu'un alias obsolète), marque, category, tags, mpn, vat_rate, weight/dimensions, images[] (jusqu'à 20) et variants[] (chacune avec SKU, prix, msrp (prix barré sur les canaux qui le prennent en charge), quantité, code-barres, grams (poids d'expédition par variante) et images propres à la variante). Les prix sont des chaînes décimales dans la devise de base de la boutique (GET /store → currency).

Les variantes avec des options (par ex. Couleur/Taille) doivent couvrir toutes les combinaisons des valeurs d'option. Les canaux génèrent la matrice complète : les ensembles incomplets sont donc refusés dès le départ au lieu de publier des annonces défectueuses.

Un produit peut exister localement sans être sur aucun canal, même sans images (il reste un brouillon local jusqu'à sa publication).

Annonce

La projection d'un produit sur un compte de canal. C'est une ressource à part entière, avec son propre identifiant (list_…), un status (listed, imported, ongoing, error, delisted), id_on_channel, url_on_channel et issues[], qui contient le message d'erreur du canal lui-même en cas d'échec.

POST   /rest/v1/listings              {product_id, channel_account_id}   # publish
PATCH  /rest/v1/listings/{id}         {}                                 # re-sync
DELETE /rest/v1/listings/{id}                                            # delist

La publication est idempotente par paire (product_id, channel_account_id), et GET /listings?status=error est la requête que votre logique de relance doit exécuter.

Deux comportements côté canal sont bons à connaître : certains vendeurs configurent des règles de prix par canal (un ajustement en pourcentage ou fixe), si bien que le prix sur le canal peut légitimement différer du prix du produit ; et sur WooCommerce, le vendeur peut avoir choisi de créer les produits en brouillon : dans ce cas, une annonce listed existe sur la boutique, mais son URL n'est pas encore publique.

Compte de canal

Un compte connecté sur une plateforme de vente. GET /channel_accounts les liste avec des identifiants stables et opaques (chac_…). Si un vendeur a deux comptes eBay, chacun est un compte de canal distinct, et un identifiant ne pointe jamais vers un autre compte. L'identifiant est conservé quand une connexion expirée est reconnectée (channel_account_id). La déconnexion le supprime : reconnecter ce compte donne un nouvel identifiant, l'ancien répond 404 channel_account_not_found, et les annonces qu'il possédait portent désormais le nouvel identifiant dans channel_account_id (les annonces appartiennent à l'emplacement du compte, pas à l'identifiant). Enregistrez les identifiants et, sur channel_account.connected, relisez GET /channel_accounts et vos annonces. Le champ channel contient la plateforme de base (shopify, amazon, ebay, etsy, woocommerce, tiktok, …). De nouvelles valeurs apparaissent à mesure que Nembol ajoute des intégrations : acceptez donc les valeurs inconnues.

Commande

Une commande normalisée importée depuis n'importe quel canal : currency par commande, status et fulfillment_status normalisés, suivi, lignes de commande et informations sur l'acheteur, y compris l'adresse de livraison complète (derrière le scope orders:read). Avec orders:write, POST /orders/{id}/fulfillment la marque comme expédiée, joint le suivi et (par défaut, quand un suivi est fourni) notifie la marketplace d'origine.

Opération

Le suivi du travail asynchrone sur les canaux. Le point essentiel à comprendre sur les écritures Nembol :

1. L'écriture locale est synchrone. POST/PATCH renvoient immédiatement la ressource mise à jour : ce que vous avez écrit est ce que vous récupérez.
2. La propagation aux canaux est asynchrone. Elle passe par les workers de canal de Nembol, qui respectent les limites de débit propres à chaque canal. Le bloc sync de la réponse vous donne un operation_id ; GET /operations/{id} indique les results[] par canal (succeeded, failed, channel_rate_limited, simulated), et une opération peut se terminer en partial.

Plutôt que d'interroger les opérations, abonnez-vous au webhook operation.completed.

Comportement de la synchronisation

• Les écritures de l'API sont mises en file derrière les mises à jour issues des commandes et les actions du tableau de bord : une intégration ne peut donc jamais bloquer la synchronisation des commandes.
• Quand un canal limite le débit, Nembol ralentit et réessaie ; l'opération affiche channel_rate_limited en attendant.
• Supprimer un produit ne touche jamais les canaux : tant qu'il est encore en ligne sur l'un d'eux, DELETE /products/{id} répond 422 product_still_listed. Retirez donc d'abord chaque annonce (si un retrait est encore en cours, il répond 409 listing_operation_in_progress : attendez la fin, puis supprimez). Un produit supprimé peut être restauré avec POST /products/{id}/restore ; ses photos sont conservées 30 jours, au-delà il revient sans elles. Voir Retirer et faire le ménage.

Dernière mise à jour le 22 octobre 2026