L’API, les webhooks et le serveur MCP

Ce que ça change

Ce que l’écran fait sur les fiches et les tâches, un programme peut le faire : Zapier, Make, n8n, votre propre code ou un assistant d’IA. Il passe par les mêmes contrôles que l’écran, les mêmes droits et les mêmes automatismes : une fiche créée par l’API reçoit son score, sa relance et sa place dans le journal, comme les autres.

Les clés

Une clé se crée dans le CRM, menu Connecteurs, par le propriétaire ou un administrateur. Elle agit au nom de la personne qui l’a créée, avec son rôle, et jamais au-delà de sa portée : lecture lit les fiches et les tâches ; écriture les crée et les modifie aussi. Aucune clé ne touche au modèle du CRM, à l’équipe, à l’abonnement ni à la suppression.

La clé ne s’affiche qu’une fois. Elle s’envoie dans l’en-tête Authorization. Une clé révoquée, ou celle d’une personne retirée de l’espace, n’ouvre plus rien. Deux cent quarante requêtes par minute et par clé.

curl https://bondossier.com/api/v1/me \
  -H "Authorization: Bearer bdk_…"

Les routes

La description complète, au format OpenAPI 3.1, est publique : /api/v1/openapi.json. Les objets, les champs et les étapes se désignent par identifiant ou par libellé, sans tenir compte des accents ni des majuscules.

GET /api/v1/me : l’espace et la clé.
GET /api/v1/objects : les objets, leurs champs, leurs étapes.
GET /api/v1/records : les fiches, les plus récentes d’abord ; filtres object, stage, q, updated_since, limit, offset.
POST /api/v1/records : créer une fiche.
GET, PATCH /api/v1/records/{id} : lire, modifier, changer d’étape.
POST /api/v1/records/{id}/notes : ajouter une note datée.
POST /api/v1/records/{id}/tasks, GET /api/v1/tasks, PATCH /api/v1/tasks/{id} : les tâches.
GET /api/v1/today : la journée.
GET, POST /api/v1/webhooks, DELETE /api/v1/webhooks/{id} : les abonnements.

curl -X POST https://bondossier.com/api/v1/records \
  -H "Authorization: Bearer bdk_…" \
  -H "Content-Type: application/json" \
  -d '{"object": "Demande", "values": {"Nom": "Julie Martin", "Email": "julie@exemple.fr"}, "stage": "À rappeler"}'

Une erreur répond avec un statut HTTP et un objet {"error": "…"} qui dit ce qui est attendu, par exemple la liste des champs de l’objet.

S’abonner aux événements

Quatre événements : record.created, record.stage_changed, record.updated, record.archived. Un abonnement se prend dans l’écran Connecteurs, ou par l’API, à la manière des REST hooks : c’est ce que Zapier attend.

Chaque envoi est un POST JSON avec la fiche complète. Un échec est repris après une minute, cinq, quinze, une heure, trois, six et douze. Un abonnement pris par l’API qui répond 410 est retiré. Après vingt envois perdus de suite, l’abonnement s’arrête, et l’écran dit pourquoi.

POST /api/v1/webhooks
{"url": "https://exemple.fr/crochet", "events": ["record.created", "record.stage_changed"], "object": "Demande"}

Corps envoyé :
{
  "id": "evt_…",
  "event": "record.stage_changed",
  "occurredAt": "2026-09-24T09:00:00.000Z",
  "workspace": {"id": "…", "name": "Plomberie Martin", "url": "https://plomberie-martin.bondossier.com"},
  "object": {"id": "demande", "label": "Demande"},
  "record": {"id": "…", "title": "Julie Martin", "stage": {"id": "…", "label": "Devis envoyé"},
             "values": {…}, "fields": {"Email": "julie@exemple.fr", …}, "url": "…/app/fiche/…"},
  "change": {"from": {"label": "À rappeler"}, "to": {"label": "Devis envoyé"}},
  "by": "Martin"
}

Vérifier la signature

Chaque envoi JSON porte l’en-tête X-BonDossier-Signature: t=…,v1=… : v1 est le HMAC SHA-256, en hexadécimal, de l’horodatage, d’un point et du corps brut, avec la clé de signature de l’abonnement. Refusez un envoi dont l’horodatage a plus de cinq minutes.

import {createHmac, timingSafeEqual} from 'node:crypto';

function verifier(entete, corpsBrut, cleDeSignature) {
  const {t, v1} = Object.fromEntries(entete.split(',').map(x => x.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const attendu = createHmac('sha256', cleDeSignature).update(`${t}.${corpsBrut}`).digest('hex');
  return attendu.length === v1.length && timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));
}

Les messages vers Slack, Teams, Discord et Google Chat ne sont pas signés : ces outils ne vérifient pas de signature.

Le serveur MCP

Adresse : https://bondossier.com/mcp. Un assistant qui parle OAuth s’y branche seul, selon la spécification d’autorisation du MCP : un 401 désigne /.well-known/oauth-protected-resource, puis le serveur d’autorisation (/.well-known/oauth-authorization-server) ; le client s’inscrit sans compte (/oauth/inscription), obtient l’accord de la personne avec PKCE, et reçoit une clé d’usage MCP, visible et révocable dans Connecteurs. Sinon, la clé va dans l’en-tête Authorization, ou dans l’adresse https://bondossier.com/mcp/bdk_…. Transport « Streamable HTTP » sans état : chaque POST porte un message JSON-RPC, ou une liste, et reçoit sa réponse en JSON. Versions du protocole prises en charge : 2025-11-25, 2025-06-18, 2025-03-26 et 2024-11-05.

Dix outils : describe_crm, search_records, get_record, list_tasks, today en lecture ; create_record, update_record, add_note, add_task, complete_task en écriture. Une clé en lecture seule ne voit que les cinq premiers.

claude mcp add --transport http bondossier https://bondossier.com/mcp/bdk_…

Recevoir des fiches sans clé

Pour un formulaire ou un outil qui envoie des demandes, pas besoin de clé : une entrée publique, avec son propre jeton, reçoit du JSON ou un formulaire HTML. Voir Recevoir un prospect depuis votre site.

Si ça ne passe pas

401 : la clé manque, a été recopiée en partie, ou a été révoquée. Une clé ne se relit pas : créez-en une autre.
403 : la clé est en lecture seule, ou son auteur n’a pas le droit de ce geste dans l’espace.
422 : une valeur est refusée. Le message dit laquelle et donne la liste des champs, des objets ou des étapes possibles.
429 : plus de deux cent quarante requêtes en une minute pour cette clé. Attendez la minute suivante.
La signature ne correspond pas : calculez-la sur le corps brut reçu, avant tout décodage, et vérifiez l’heure de votre serveur.
Votre assistant ne voit que cinq outils : son adresse est en lecture seule. Créez-en une en lecture et écriture.
Bloqué ? Écrivez à contact@raviolelabs.com avec la route, le statut et le message reçus.