API et webhooks de la boutique

L'onglet Développeurs de la rubrique Boutique permet à un autre logiciel (gestion de stock, caisse, comptabilité, site sur mesure) de lire et de mettre à jour votre boutique, et de recevoir en temps réel les événements importants : commande passée, stock modifié, retour demandé. Pour consulter l'écran, il suffit de pouvoir lire la boutique ; pour créer, modifier ou révoquer, il faut pouvoir la modifier. Voir aussi la boutique en ligne.

Tâches courantes

Créer une clé d'API

1. Ouvrez Boutique, onglet Développeurs, rubrique Clés d'API, puis Nouvelle clé.
2. Donnez un nom qui dit à quoi sert la clé (par exemple « Logiciel de caisse »).
3. Cochez les droits nécessaires, ou utilisez les préréglages Lecture seule et Lecture et écriture. Ne cochez que le strict nécessaire.
4. Réglez au besoin la limite de débit (120 requêtes par minute par défaut, de 10 à 1 200) et une date d'expiration (au plus un an).
5. Cliquez sur Créer la clé.

La clé complète, qui commence par shk_, s'affiche une seule fois, dans un encadré à part. Copiez-la tout de suite avec le bouton Copier et rangez-la dans le coffre de mots de passe de l'outil qui l'utilisera. Une fois l'encadré fermé, SheepOS ne peut plus la montrer : seul son début reste visible dans la liste. Si vous l'avez perdue, révoquez-la et créez-en une autre.

Les droits d'une clé

Chaque droit concerne une ressource, en lecture ou en écriture : produits, stock, commandes, clients. Un droit d'écriture donne aussi la lecture de la même ressource. Par exemple, une clé qui ne fait que synchroniser le stock n'a besoin que de Lire le stock et Modifier le stock : même si elle fuit, elle ne donne accès ni aux commandes ni aux clients. Les droits d'une clé se modifient après coup, sans changer la clé.

Bonnes pratiques de sécurité

• Créez une clé par intégration : vous saurez laquelle utilise quoi (colonne Dernière utilisation) et vous pourrez en révoquer une sans toucher aux autres.
• Révoquez immédiatement une clé qui a fuité, ou dont l'outil n'est plus utilisé. La révocation est instantanée et irréversible.
• Ne mettez jamais une clé dans un site web, une page ou une application mobile : tout visiteur pourrait la lire. Elle ne doit vivre que sur un serveur à vous.
• Ne l'envoyez pas par e-mail ni par messagerie, ne la placez pas dans l'adresse d'une requête, et ne la commitez pas dans un dépôt de code.
• Donnez une date d'expiration aux clés temporaires (prestataire, essai).
• Surveillez le Journal d'accès : des refus 401 ou 403 répétés, ou des requêtes à des heures inhabituelles, sont un signal.

Faire un premier appel

L'API est à l'adresse de base https://VOTRE-SERVEUR/api/v1/shop, affichée dans la rubrique Documentation. Chaque requête porte la clé dans l'en-tête Authorization.

Pour vérifier que la clé fonctionne : curl "https://VOTRE-SERVEUR/api/v1/shop" -H "Authorization: Bearer shk_VOTRE_CLE"

Pour lister les produits (droit Lire les produits) : curl "https://VOTRE-SERVEUR/api/v1/shop/products?limit=50" -H "Authorization: Bearer shk_VOTRE_CLE"

Pour fixer le stock d'un produit (droit Modifier le stock) : curl -X PUT "https://VOTRE-SERVEUR/api/v1/shop/stock/ID_PRODUIT" -H "Authorization: Bearer shk_VOTRE_CLE" -H "Content-Type: application/json" -d '{"quantity": 12}'

Les montants sont des entiers en centimes. Les prix des produits sont hors taxes, les totaux de commande toutes taxes comprises. Les listes sont paginées : passez la valeur nextCursor de la page reçue dans le paramètre cursor pour obtenir la suivante, et updatedSince pour ne récupérer que ce qui a changé. La rubrique Documentation de l'écran liste toutes les routes, leurs paramètres, leur corps et un exemple curl.

Créer un webhook

1. Rubrique Webhooks, puis Nouvelle adresse.
2. Saisissez l'adresse de votre serveur, qui doit commencer par https://, et une description.
3. Choisissez les événements reçus, ou tous.
4. Cliquez sur Créer l'adresse et copiez le secret whsec_… : comme une clé d'API, il n'est montré qu'une seule fois.
5. Cliquez sur Tester : SheepOS envoie un événement d'essai et affiche le statut HTTP, la durée et l'erreur éventuelle.

Le bouton Nouveau secret remplace le secret, après confirmation : l'ancien cesse de fonctionner tout de suite, mettez donc à jour votre serveur aussitôt. Supprimer retire l'adresse et son journal de livraison.

Vérifier la signature d'un webhook

Chaque envoi porte l'en-tête SheepOS-Signature: t=SECONDES,v1=HEX. Vérifiez-le avant d'agir, sinon n'importe qui pourrait envoyer de faux événements à votre serveur :

1. Lisez le corps brut de la requête, avant tout traitement JSON.
2. Extrayez t et v1 de l'en-tête.
3. Calculez le HMAC-SHA256 du texte formé de t, d'un point, puis du corps brut, avec votre secret whsec_…, en hexadécimal.
4. Comparez le résultat à v1 en temps constant (et non avec une simple égalité).
5. Refusez l'événement si t s'écarte de plus de 300 secondes de l'heure actuelle : c'est ce qui empêche le rejeu d'un ancien envoi.
6. Dédoublonnez sur l'id de l'événement : il est identique à chaque re-essai, un même événement peut donc vous parvenir deux fois.

Des extraits prêts à copier en Node.js, PHP et Python sont dans la rubrique Documentation, section Vérifier la signature. Répondez par un code 2xx le plus vite possible (dans les 10 secondes) et traitez l'événement ensuite.

Re-essais, désactivation et renvoi

Une réponse qui n'est pas en 2xx, un délai dépassé ou une erreur réseau compte comme un échec. SheepOS réessaie jusqu'à six fois après le premier envoi, à 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures puis 24 heures. Une livraison qui échoue partout passe à l'état Abandonnée.

Après 15 échecs de suite, l'adresse est désactivée automatiquement : un message rouge en donne la raison dans la liste. Corrigez votre serveur, puis cliquez sur Activer : le compteur d'échecs repart à zéro. Dans le Journal de livraison, filtrez par adresse ou par état, et utilisez Renvoyer sur une livraison en échec ou abandonnée.

Consulter le journal d'accès

La rubrique Journal d'accès liste les requêtes reçues par l'API : clé, méthode, route, statut, durée et date, avec un filtre par clé et par statut. Le journal est conservé 30 jours.

Limites

• 20 clés au maximum par boutique, 10 adresses de webhooks.
• 120 requêtes par minute et par clé par défaut, réglable de 10 à 1 200. Au-delà, l'API répond 429 avec l'en-tête Retry-After : attendez ce nombre de secondes.
• 100 éléments au plus par page.
• Le paiement, le remboursement et les litiges ne se pilotent pas par l'API : ils restent dans le back-office.
• Les journaux d'accès et de livraison sont conservés 30 jours.

Questions fréquentes

J'ai perdu ma clé ou mon secret, comment le retrouver ?

Vous ne le pouvez pas : SheepOS ne le garde pas en clair. Pour une clé, révoquez-la et créez-en une autre. Pour un webhook, utilisez Nouveau secret.

Mon outil reçoit une erreur 401

La clé est absente, mal recopiée, expirée ou révoquée. Vérifiez son état dans la liste des clés.

Mon outil reçoit une erreur 403

La clé n'a pas le droit exigé par la route. Modifiez les droits de la clé dans l'écran, ou utilisez une autre clé.

Je ne reçois plus d'événements

Regardez d'abord si l'adresse est désactivée (message rouge dans la liste), puis le Journal de livraison : le code et l'erreur indiquent ce que votre serveur a répondu.