API de boutique en ligne et webhooks : synchroniser stock et commandes avec votre ERP

Votre boutique en ligne ne vit pas seule. Le stock bouge en magasin, la comptabilité attend les commandes, un ERP ou une place de marché doit afficher les bons prix. Pour que ces outils parlent entre eux sans ressaisie, il faut une API et des webhooks. Ce guide explique à quoi ils servent, ce que l'API d'Eazyclick permet, ce qu'elle ne couvre pas encore, et comment synchroniser un stock avec un ERP.

En bref

• Une API e-commerce permet à un autre logiciel de lire et de modifier les produits, le stock et les commandes de votre boutique.
• Un webhook prévient ce logiciel dès qu'un événement se produit, sans qu'il doive interroger la boutique en boucle.
• L'API d'Eazyclick (v1) couvre les produits, le stock et les commandes, avec des clés de lecture ou d'écriture.
• Deux webhooks signés : order.placed (commande passée) et stock.updated (stock modifié).
• Limites publiées : 120 requêtes par minute en lecture et 30 en écriture, par clé.

Qu'est-ce qu'une API e-commerce ?

Une API e-commerce est une porte d'accès technique à votre boutique en ligne. Elle permet à un autre logiciel, comme un ERP ou une place de marché, de lire le catalogue, le stock et les commandes, et parfois de les modifier, sans passer par l'administration. Les échanges se font en JSON, par requêtes HTTP sécurisées par une clé.

Concrètement, une API évite les exports manuels en CSV et les ressaisies. Un développeur ou votre intégrateur écrit une fois la liaison entre les deux logiciels, et les données circulent ensuite toutes seules. C'est ce qu'on appelle souvent une « intégration » ou une « liaison API ».

API ou webhook : quelle différence ?

L'API et le webhook circulent dans deux sens opposés. Avec l'API, votre logiciel pose une question à la boutique quand il en a besoin, par exemple « quel est le stock de ce produit ? ». Avec un webhook, c'est la boutique qui prévient votre logiciel dès qu'un événement se produit, comme une nouvelle commande. Une bonne synchronisation combine les deux.

Ce que permet l'API d'Eazyclick

L'API ouverte d'Eazyclick, en version 1, couvre trois ressources de la boutique : les produits avec leurs variantes, le stock et les commandes. Les produits se lisent, se créent et se modifient. Le stock se lit, se règle et reçoit des mouvements. Les commandes se lisent, y compris par date de modification. Elle fait partie du module E-commerce complet.

Ce que la version 1 ne couvre pas, pour éviter toute mauvaise surprise :

• Les clients, le CRM et les factures ne sont pas exposés par l'API.
• Le stock par magasin : l'API donne le stock de chaque variante tous lieux confondus, sans le détail par magasin.
• Les ventes en caisse arrivent par le webhook order.placed, mais ne se lisent pas par GET /orders.
• Aucun connecteur tout fait n'est fourni pour un ERP précis : l'API et les webhooks permettent de le construire.

Clés de lecture et d'écriture

L'accès à l'API passe par une clé créée dans les réglages de la boutique. Une clé de lecture consulte les données, une clé d'écriture peut aussi créer des produits et régler le stock. La clé n'est affichée qu'une fois, se révoque en un clic et agit au nom du propriétaire du compte, qui retrouve chaque écriture dans le journal.

Quelques règles de bon sens :

• Une clé par intégration : révoquer l'accès d'un prestataire ne coupe alors que lui.
• La plus petite portée suffisante : un comparateur de prix n'a besoin que de la lecture.
• La clé reste sur un serveur, jamais dans une page web ni dans un dépôt de code : elle donne accès aux commandes et aux adresses de vos clients.

Webhooks signés : order.placed et stock.updated

Eazyclick envoie deux événements à l'adresse de votre choix. order.placed part à chaque commande passée, en ligne ou en caisse. stock.updated part dès que le stock d'une variante change, que ce soit par une vente, une écriture par l'API ou une correction dans le back-office. Chaque envoi est signé, pour que votre serveur vérifie qu'il vient bien d'Eazyclick.

• Signature HMAC-SHA256 dans l'en-tête Eazyclick-Signature, calculée sur l'horodatage et le corps brut avec le secret du point de réception. Refusez un horodatage de plus de 5 minutes.
• Identifiant d'événement stable (Eazyclick-Event-Id) : un même événement peut arriver deux fois, dédoublonnez sur cet identifiant.
• Nouvel essai automatique si votre serveur ne répond pas : après 1 minute, 5 minutes, 30 minutes, 2 heures puis 6 heures, soit 6 tentatives sur 8 h 36.
• Journal des envois, rejeu et bouton « Tester » dans le back-office, pour vérifier une intégration sans attendre une vraie commande.

Limites de débit et pagination

L'API applique des limites publiées, par clé et par minute : 120 requêtes en lecture et 30 en écriture, comptées séparément. Au-delà, elle répond 429 rate_limited avec l'en-tête Retry-After, qui indique combien de secondes attendre. Les listes se parcourent par pages de 100 éléments au plus, et tous les montants sont exprimés en centimes entiers.

Ces limites laissent une large marge pour une synchronisation normale. La documentation recommande les webhooks pour le temps réel, un rattrapage des commandes toutes les 5 à 15 minutes, une relecture du catalogue toutes les heures et un rapprochement complet du stock une fois par nuit. Ce rythme tient très largement dans les 120 lectures par minute.

Cas d'usage : synchroniser le stock avec un ERP

Pour synchroniser un ERP ou un logiciel de caisse tiers avec la boutique, Eazyclick reste la source de vérité du stock. L'ERP charge d'abord le catalogue, reçoit ensuite chaque mouvement de stock et chaque commande par webhook, déclare ses propres ventes par l'API, puis vérifie l'ensemble chaque nuit. Une clé de lecture et d'écriture suffit pour tout le scénario.

1. Chargement initial : GET /products, page par page, en rapprochant les variantes par SKU.
2. Stock en temps réel : abonnement à stock.updated, appliqué dès réception.
3. Commandes : order.placed en temps réel, plus GET /orders?updatedAfter=… toutes les 5 à 15 minutes pour rattraper un envoi manqué.
4. Ventes faites hors d'Eazyclick : POST /variants/{variantId}/stock-movements à chaque vente.
5. Rapprochement : GET /stock chaque nuit, comparé à la base de l'ERP.

Si vous hésitez encore sur le choix d'un ERP, notre guide de l'ERP pour PME et notre comparatif Odoo ou Eazyclick détaillent les options. Pour un commerce à plusieurs points de vente, la page Commerce multi-magasins montre comment le stock, la caisse et la boutique travaillent ensemble.

Documentation et spécification OpenAPI

La documentation de l'API est publique, en français et en anglais, et générée depuis le code de l'API : chaque chiffre affiché est celui que l'API applique. Elle contient un guide de démarrage, l'authentification, la pagination et les erreurs, les limites, la fréquence de synchronisation, les webhooks avec des exemples de vérification en Node, PHP et Python, et la référence complète.

• Documentation de l'API en français
• Documentation de l'API en anglais
• Spécification OpenAPI, à importer dans Postman, Insomnia ou un générateur de client.

Les outils déjà reliés aux modules sont listés sur la page Intégrations.

Questions fréquentes

L'API est-elle comprise dans Eazyclick ?

L'API ouverte fait partie du module E-commerce complet : elle s'active avec lui, sans module séparé à ajouter. Les clés se créent dans les réglages de la boutique, et les webhooks se configurent au même endroit. Sans le module E-commerce complet, l'API n'est pas disponible, puisqu'elle porte sur les produits, le stock et les commandes de la boutique.

Existe-t-il un connecteur prêt pour mon ERP ?

Non. Eazyclick ne fournit pas de connecteur tout fait pour un ERP précis. L'API et les webhooks donnent tout ce qu'il faut pour en écrire un : chargement du catalogue, stock en temps réel, commandes et ventes externes. Votre développeur ou l'intégrateur de votre ERP peut s'appuyer sur la documentation et la spécification OpenAPI pour construire la liaison.

Peut-on lire les clients ou les factures par l'API ?

Pas dans la version 1. L'API couvre les produits, les variantes, le stock et les commandes. Les fiches clients, les données du CRM et les factures ne sont pas exposées. Une commande contient toutefois l'adresse e-mail et les informations de livraison utiles à son traitement, ce qui suffit pour la plupart des synchronisations de logistique et de stock.

Que se passe-t-il si mon serveur est indisponible ?

Les webhooks sont renvoyés automatiquement : six tentatives au total, après 1 minute, 5 minutes, 30 minutes, 2 heures puis 6 heures. Après la dernière, l'envoi reste visible dans le journal du back-office et peut être rejoué d'un clic. Pour les commandes en ligne, une lecture régulière avec updatedAfter rattrape aussi un événement manqué.

Le stock est-il donné magasin par magasin ?

Pas encore dans l'API. La version 1 publie, pour chaque variante, le stock total de la boutique, tous lieux de stock confondus : quantité en stock, réservée et disponible. Le back-office, lui, gère déjà un stock par magasin. Si votre projet a besoin de ce détail dans l'API, signalez-le : un tel ajout se fait sans rupture de la version 1.