Documentation

API REST et MCP (Claude)

Authentification JWT, routes, RBAC, temps réel et connexion de Claude par MCP.

API REST

Chaque table du schéma est exposée sous /api/v1/<Table> avec authentification JWT. Les mêmes routes sans le préfixe /api/v1/ servent l’interface web avec une session par témoin.

POST /api/v1/Authy/auth
Content-Type: application/json
{ "u": "vous", "p": "secret" }

→ { "status": "success", "token": "eyJhbGciOi…", "expires": 1735776000 }

GET /api/v1/Contact?filter[type]=Client&order[name]=asc&limit=50
Authorization: Bearer eyJhbGciOi…

Liste GET /api/v1/<Table> — filtre, tri, sélection et pagination dans la requête.
Lecture GET /api/v1/<Table>/<id>; création POST; mise à jour PUT /<id>; suppression DELETE /<id>.
Les réponses utilisent une seule enveloppe : { status, data, error, meta }. Les erreurs de validation listent les champs fautifs.
Les droits sur les fiches et le RBAC par route s’appliquent exactement comme dans l’interface (voir Utilisateurs, groupes et sécurité). Chaque appel est écrit au journal d’API.
Les actions personnalisées (envoyer une soumission, convertir en facture, numériser un reçu…) sont des routes ordinaires sous la table, p. ex. POST /api/v1/Quote/<id>/convert.

La référence complète générée — en-têtes, enveloppe, constantes, chaque ressource — se trouve dans .admin/docs/API.md de votre installation.

Serveur MCP pour Claude

BillBoy expose un point Model Context Protocol avec OAuth 2.1 (enregistrement dynamique, PKCE, jetons de rafraîchissement), pour que Claude utilise votre CRM comme un ensemble d’outils typés dans les limites de vos droits.

Quoi	URL
Point MCP (JSON-RPC sur HTTP)	`https://VOTRE-HOTE/api/v1/mcp`
Métadonnées du serveur d’autorisation OAuth	`https://VOTRE-HOTE/.well-known/oauth-authorization-server`
Métadonnées de la ressource protégée OAuth	`https://VOTRE-HOTE/.well-known/oauth-protected-resource`

Connexion depuis Claude (web ou bureau)

Claude → Paramètres → Connecteurs → Ajouter un connecteur personnalisé.
Collez l’URL du point MCP et cliquez Connecter. Claude découvre le serveur OAuth et s’enregistre — aucun identifiant client à copier.
Connectez-vous avec vos identifiants BillBoy et approuvez les portées (crm:read, crm:write, offline_access).

Connexion depuis Claude Code

claude mcp add --transport http billboy https://VOTRE-HOTE/api/v1/mcp
# puis dans Claude Code : /mcp → Authenticate

Outils

Outil	Portée	Rôle
`crm_describe`	lecture	Entités et champs (type, requis, modifiable, énumération, relations)
`crm_list` / `crm_get`	lecture	Recherche avec filtre/tri/pagination; lecture d’une ligne
`crm_create` / `crm_update` / `crm_delete`	écriture	Écriture de lignes; création et suppression exigent `confirm: true`
`crmx_find`	lecture	Recherche floue dans contacts, entreprises, soumissions, factures, produits, activités
`crmx_create_quote`, `crmx_create_invoice`, `crmx_convert_quote_to_invoice`	écriture	Flux de vente avec questions de détail
`crmx_record_payment`, `crmx_scan_receipt`	écriture	Paiements et numérisation de reçus par IA
`crmx_my_day`, `crmx_pipeline_summary`, `crmx_distance`, `crmx_log_activity`, `crmx_email_document`, `crmx_drive_list`	mixte	Briefings, rapports, distance, journalisation d’activité, envoi de documents, Drive
`gc_pdf_preview`, `gc_regenerate_pdf`	lecture / écriture	Aperçu HTML d’un document; régénération de son PDF

Les outils n’inventent jamais de valeurs : une création avec des champs requis manquants renvoie la liste de ce qui manque. Les écritures ne s’exécutent qu’avec une confirmation explicite, et les droits de l’utilisateur s’appliquent toujours.

Temps réel

Un sidecar OpenSwoole optionnel pousse des trames {op:"change", t:"<table>"} par WebSocket dès qu’une table change; les listes ouvertes se rechargent. Activez avec GC_RT_ENABLED="1" et une règle de proxy WebSocket dans votre vhost; l’application fonctionne inchangée quand le sidecar est arrêté.

Application mobile

Le répertoire mobile/ contient une application Expo (React Native) qui parle à la même API avec un JWT et enregistre l’appareil pour les notifications push (Paramètres → Appareils push).