Prise en main de l’API
Créer une clé bbv_, lire le manifeste, appeler un outil et interpréter les réponses et les erreurs.
L’API permet à un logiciel de travailler dans votre espace sans navigateur : lire et modifier le stock, suivre les commandes et les retraits, consulter les devis. Cette rubrique s’adresse à une personne à l’aise avec ce type d’outil. Pour relier Claude sans clé à copier, voir Claude.
Créer une clé
L’écran Clés d’API est réservé au propriétaire du compte. Les autres membres doivent s’adresser à lui.
- Donnez un nom qui dit à quoi sert la clé, de 2 à 80 caractères. Il apparaîtra dans le journal.
- Choisissez l’entreprise, si vous en gérez plusieurs.
- Choisissez le périmètre : lecture seule, ou lecture et écriture.
- Choisissez la durée. Une clé expire toujours, au bout d’un an au plus.
- Copiez la clé, qui commence par
bbv_.
La clé n’est affichée qu’une fois. Rangez-la comme un mot de passe, dans le gestionnaire de secrets de votre logiciel, jamais dans un document partagé.
- Une clé ne voit qu’une entreprise.
- Une entreprise a au plus dix clés actives créées depuis cet écran.
- Une clé cesse de fonctionner si elle expire, si vous la révoquez, ou si la personne qui l’a créée quitte l’équipe.
- Une clé ne se modifie pas : pour changer son nom ou son périmètre, révoquez-la et créez-en une autre.
Lire le manifeste
Chaque appel porte l’en tête Authorization: Bearer <clé>. Le manifeste décrit tous les outils et leurs paramètres. C’est le premier appel à faire.
export BOUDBOIS_VENDOR_API_KEY="<votre clé bbv_>"
curl -s https://vendeurs.boudbois.fr/api/agent/manifest \
-H "Authorization: Bearer $BOUDBOIS_VENDOR_API_KEY"{
"version": 2,
"tools": [
{
"name": "vendor_stock_list",
"description": "…",
"scope": "read",
"inputSchema": { "type": "object", "properties": {} }
}
],
"missing": [],
"key": { "name": "Script atelier", "scope": "write" },
"entity": { "name": "Scierie Exemple", "publicRef": null }
}Le manifeste liste tous les outils, quel que soit le périmètre de la clé. key.scope donne le périmètre effectif.
Appeler un outil
Un outil s’appelle par POST /api/agent/tools/<nom>, avec un corps JSON. Commencez par vendor_context_get : il donne votre entreprise, vos points de retrait et les essences saisissables.
curl -s -X POST https://vendeurs.boudbois.fr/api/agent/tools/vendor_stock_list \
-H "Authorization: Bearer $BOUDBOIS_VENDOR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"limit": 20}'Les listes se paginent avec limit et offset.
Les réponses
Un succès répond avec le statut 200 :
{ "ok": true, "tool": "vendor_stock_list", "result": {} }Un échec répond avec un statut 4xx ou 5xx et un champ error.
| Statut | error | Signification |
|---|---|---|
| 400 | invalid_json | Le corps est illisible. Un corps vide vaut {} |
| 400 | invalid_input | Paramètres refusés, détail dans issues |
| 400 | unknown_action | vendor_action_call : action inconnue ou non exposée |
| 400 | too_many_args | vendor_action_call : trop d’arguments |
| 401 | unauthorized | Clé absente, inconnue, révoquée ou expirée, ou créateur qui n’a plus l’accès |
| 403 | forbidden | Clé en lecture seule sur un outil qui modifie |
| 403 | mcp_disabled | Clé créée par Claude alors que l’accès Claude est fermé |
| 404 | unknown_tool | Outil inconnu |
| 429 | rate_limited | Quota de la minute atteint, voir l’en tête Retry-After |
| 500 | tool_failed | Erreur de notre côté. Réessayez, puis écrivez-nous si elle dure |
Un refus métier d’une action répond avec le statut 200. Il se lit dans result, par exemple { "ok": false, "error": "…" }.
Quotas
Une clé fait au plus 60 lectures et 20 écritures par minute. Un seul compteur est tenu par clé : au delà de 20 appels dans la minute, une écriture est refusée, et une lecture l’est au delà de 60. La lecture du manifeste compte comme une lecture.
Les outils
| Page | Contenu |
|---|---|
| Stock | Contexte, liste, fiche, création, modification, publication, photos, pièces approchantes |
| Commandes et devis | Commandes, retraits du jour, clôture d’un retrait, devis |
| Actions génériques | vendor_actions_list et vendor_action_call |
Les actions de l’espace sont décrites dans la partie « Actions » du menu. vendor_action_call les appelle avec les mêmes contrôles qu’un clic dans l’espace. Avec une clé, un contrôle « propriétaire » s’applique à la personne qui l’a créée.
Ce que l’API ne permet pas
- Gérer les clés d’API et approuver Claude.
- Gérer l’équipe et les invitations.
- Changer le téléphone, le mot de passe ou les sessions d’un compte.
- Connecter un agenda.
Journal
Chaque écriture s’inscrit dans l’activité de l’équipe, sous le nom de la clé.