Ma Belle Note

Démarrage rapide

Créez une clé, vérifiez la connexion et lisez vos premiers avis en quelques minutes.

Documentation de l'APIGuides · Démarrage rapide

Ce qu'il vous faut

  • Un compte Ma Belle Note au plan Pro, ou en essai gratuit : l'API y est incluse.
  • Le rôle de propriétaire ou d'administrateur du compte : eux seuls créent les clés.
  • Un terminal avec curl, ou tout outil capable d'envoyer une requête HTTPS.

Les opérations de lecture, celles des établissements, des statistiques, des avis, des retours privés et des contacts, sont stables, comme GET /v1/health, GET /v1/openapi.json et GET /v1/me : elles suivent les garanties du guide de versionnage. Le journal d'événements, les webhooks, les écritures et la publication sur Google sont en version bêta : ils peuvent encore évoluer avant d'être déclarés stables.

1. Créer une clé

Dans l'application, ouvrez Réglages › Intégration, API & webhooks, puis Créer une clé. Donnez-lui un nom qui dit où elle servira, par exemple « Tableau de bord du groupe », choisissez le modèle Lecture seule, puis validez.

La clé commence par mbn_live_. Elle ne s'affiche qu'une seule fois : copiez-la et rangez-la dans un gestionnaire de secrets. Si vous la perdez, révoquez-la et créez-en une nouvelle.

Une clé reste côté serveur

L'API sert des échanges de serveur à serveur. Elle n'envoie aucun en-tête CORS, sauf sur GET /v1/openapi.json : ne placez jamais une clé dans une page web, une application mobile ou un dépôt de code.

2. Vérifier que l'API répond

GET /v1/health ne demande pas de clé. Il répond tant que l'API est en service, avec l'heure du serveur.

curl https://api.mabellenote.com/v1/health

{
  "object": "health",
  "status": "ok",
  "apiVersion": "v1",
  "time": "2026-10-24T09:15:02.311Z"
}

3. Faire votre premier appel

Placez la clé dans une variable d'environnement, puis appelez GET /v1/me. Toute clé valide peut l'appeler : la réponse décrit le compte, la clé et sa limite de débit.

export MBN_API_KEY="mbn_live_..."

curl https://api.mabellenote.com/v1/me \
  -H "Authorization: Bearer $MBN_API_KEY"

{
  "object": "me",
  "account": {
    "id": "kd7a1b2c3d4e5f6g7h8j9k0m1n2p3q4r",
    "name": "Le Bistrot",
    "slug": "le-bistrot",
    "plan": "pro",
    "readOnly": false
  },
  "apiKey": {
    "id": "jx9k2m4n6p8q0r1s3t5v7w9y1z3b5c7d",
    "name": "Tableau de bord du groupe",
    "prefix": "mbn_live_AbC1",
    "scopes": [
      "account:read",
      "establishments:read",
      "reviews:read",
      "stats:read",
      "feedbacks:read"
    ],
    "createdAt": "2026-10-24T09:15:02.311Z",
    "expiresAt": null
  },
  "rateLimit": { "limit": 120, "windowSeconds": 60 }
}

Une réponse 401 signale une clé absente, inconnue, révoquée ou expirée : le champ code dit laquelle. Le guide des erreurs les détaille.

4. Lister vos établissements

curl https://api.mabellenote.com/v1/establishments \
  -H "Authorization: Bearer $MBN_API_KEY"

Chaque établissement porte un id, son statut de connexion à Google (connection) et ses compteurs d'avis (reviews). Notez l'id d'un établissement : il sert de filtre aux autres listes.

5. Lire vos avis

curl "https://api.mabellenote.com/v1/reviews?establishmentId=kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p&limit=10" \
  -H "Authorization: Bearer $MBN_API_KEY"

La liste part de l'avis le plus récent. Chaque avis porte sa note, son texte, sa réponse publiée (reply, ou null) et son analyse (analysis). Quand hasMore vaut true, la page suivante s'obtient avec nextCursor.

Le même appel en JavaScript, dans un module Node 18 ou plus :

const response = await fetch("https://api.mabellenote.com/v1/reviews?limit=10", {
  headers: { Authorization: `Bearer ${process.env.MBN_API_KEY}` },
});
const body = await response.json();
if (!response.ok) throw new Error(`${body.status} ${body.code} (${body.requestId})`);
for (const review of body.data) console.log(review.rating, review.comment);

Et ensuite

Mis à jour le 25 octobre 2026