v1
Documentation de l'API
L'API REST de Ma Belle Note lit les établissements, avis, statistiques, retours privés et base clients d'un compte, y dépose contacts, passages et brouillons de réponse, et envoie chaque événement à vos outils par webhook. Une clé API suffit.
Documentation de l'APIVue d'ensemble
Adresse de base
Toutes les opérations partent de cette adresse, en HTTPS, avec la clé du compte dans l'en-tête Authorization.
https://api.mabellenote.com/v1
Les opérations de lecture sont stables : elles suivent la politique de compatibilité décrite dans le guide de versionnage. Une opération marquée « Bêta », comme les écritures, les webhooks ou le journal d'événements, peut encore évoluer avant d'être déclarée stable.
Guides
- Démarrage rapideCréez une clé, vérifiez la connexion et lisez vos premiers avis en quelques minutes.
- Authentification et droitsComment une clé API s'envoie, ce qu'elle couvre, les droits qu'elle porte et ce que le plan du compte change.
- Pagination et synchronisationParcourir une liste page par page avec un curseur, puis ne récupérer que les nouveautés à chaque passage.
- WebhooksRecevoir sur votre serveur chaque nouvel avis, retour privé ou client, vérifier la signature Standard Webhooks, puis gérer relances, désactivation et rejeu.
- IdempotenceRenvoyer une écriture après une coupure réseau sans risquer de doublon, avec l'en-tête Idempotency-Key.
- ÉcrituresAlimenter la base clients depuis une caisse ou un CRM, enregistrer des passages, valider des codes promo et déposer des brouillons de réponse.
- Publication GooglePublier depuis votre outil la réponse à un avis Google, pour les établissements qui l'ont autorisé, avec les mêmes contrôles que dans l'application.
- ErreursLe format des erreurs de l'API, la façon de les traiter et la liste complète des codes, chacun avec son ancre.
- LimitesLe débit autorisé par clé, les en-têtes qui l'annoncent, la conduite à tenir en cas de dépassement et les autres limites de l'API.
- VersionnageCe qui peut évoluer dans la version v1, ce qui n'y change jamais, le statut bêta et la façon dont une version est dépréciée.
- Référence de l'APIChaque opération, chaque paramètre, chaque champ et chaque erreur, générés depuis l'API elle-même.Ouvrir la référence
- Journal des changementsChaque évolution du contrat de l'API, datée, la plus récente en tête.
Recettes sans code
Des pas-à-pas pour brancher l'API sur Make, Zapier ou n8n avec leurs modules HTTP et webhooks génériques, ou sur un assistant IA, sans écrire de serveur.
- Google Sheets avec MakeChaque nuit, une ligne par établissement dans Google Sheets : nombre d'avis, note moyenne, réponses et répartition des notes. Un scénario Make, sans code.
- Slack avec ZapierUn message dans le canal de votre équipe dès qu'un avis de 2 étoiles ou moins arrive, avec un webhook, Webhooks by Zapier et Slack, sans code.
- Tickets avec n8nUn workflow n8n qui lit le journal d'événements toutes les 5 minutes et ouvre un ticket pour chaque avis ou retour privé de 2 étoiles ou moins.
- Assistant IA (MCP)Branchez Claude, ChatGPT, Le Chat ou Claude Code sur vos avis, statistiques et retours privés via le MCP de l'API : une adresse à coller, aucune clé à copier.
Opérations disponibles
Liste tirée de la description OpenAPI de la version en cours.
| Opération | Rôle | Droit requis | Stabilité |
|---|---|---|---|
GET /v1/health | Vérifier la disponibilité de l'API | Sans clé | Stable |
GET /v1/openapi.json | Obtenir la description OpenAPI | Sans clé | Stable |
GET /v1/me | Identifier la clé API | account:read | Stable |
GET /v1/establishments | Lister les établissements | establishments:read | Stable |
GET /v1/establishments/{establishmentId} | Obtenir un établissement | establishments:read | Stable |
GET /v1/establishments/{establishmentId}/stats | Obtenir les statistiques d'un établissement | stats:read | Stable |
GET /v1/reviews | Lister les avis | reviews:read | Stable |
GET /v1/reviews/{reviewId} | Obtenir un avis | reviews:read | Stable |
GET /v1/feedbacks | Lister les retours privés | feedbacks:read | Stable |
GET /v1/feedbacks/{feedbackId} | Obtenir un retour privé | feedbacks:read | Stable |
GET /v1/contacts | Lister les contacts | contacts:read | Stable |
POST /v1/contacts | Créer ou mettre à jour un contact | contacts:write | Bêta |
GET /v1/contacts/{contactId} | Obtenir un contact | contacts:read | Stable |
PATCH /v1/contacts/{contactId} | Modifier un contact | contacts:write | Bêta |
POST /v1/visits | Enregistrer un passage | visits:write | Bêta |
POST /v1/promo-codes/redeem | Valider un code promo | promo_codes:redeem | Bêta |
POST /v1/reviews/{reviewId}/reply-drafts | Générer un brouillon par l'IA | ai:generate | Bêta |
PUT /v1/reviews/{reviewId}/reply-draft | Déposer un brouillon rédigé | replies:write | Bêta |
POST /v1/reviews/{reviewId}/reply | Publier une réponse sur Google | replies:publish | Bêta |
GET /v1/events | Lister les événements | events:read | Bêta |
GET /v1/events/{eventId} | Obtenir un événement | events:read | Bêta |
GET /v1/webhook-endpoints | Lister les points de réception | webhooks:manage | Bêta |
POST /v1/webhook-endpoints | Créer un point de réception | webhooks:manage | Bêta |
DELETE /v1/webhook-endpoints/{endpointId} | Supprimer un point de réception | webhooks:manage | Bêta |
POST /v1/webhook-endpoints/{endpointId}/test | Envoyer un événement de test | webhooks:manage | Bêta |