Publier une réponse sur Google

Ce que fait l'opération

POST /v1/reviews/{reviewId}/reply publie une réponse à un avis sur la fiche Google de l'établissement, par le même chemin qu'une publication faite dans l'application, puis renvoie l'avis répondu. Elle est en version bêta.

La publication passe par la connexion à Google Business Profile que l'établissement a autorisée dans Ma Belle Note. Ma Belle Note n'est pas affilié à Google, et cette fonction ne relève d'aucun partenariat avec Google. La page Usage de l'API Google décrit l'usage que nous faisons de cette connexion. Aucune autre action sur Google, comme la modification de la fiche, des photos ou des publications, n'est possible par l'API.

Trois conditions

1. Le droit replies:publish sur la clé, présenté dans l'application sous le nom « Publier des réponses sur Google ».
2. L'autorisation de l'établissement. Elle est désactivée par défaut et ne s'active que dans l'application, établissement par établissement : Réglages › Intégration, API & webhooks, onglet Publication Google. Seuls les propriétaires et les administrateurs peuvent la donner ou la retirer. Elle est horodatée, et son retrait s'applique dès l'appel suivant. Le champ apiReplyPublishing.enabled de GET /v1/establishments indique son état.
3. L'en-tête Idempotency-Key, obligatoire : un appel rejoué ne publie jamais deux fois. Sans lui, l'API répond 400 invalid_request.

Le droit seul ne suffit pas : une clé qui porte replies:publish reçoit 403 google_publishing_not_authorized pour tout établissement qui n'a pas donné son autorisation.

Publier une réponse

curl https://api.mabellenote.com/v1/reviews/jd7f3k2m9x8w1q4z6c5v3b2n1m0l9k8j/reply \
  -H "Authorization: Bearer $MBN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-jd7f3k2m9x8w1q4z6c5v3b2n1m0l9k8j" \
  -d '{ "content": "Bonjour Jean, merci pour votre retour. Nous en avons parlé à l’équipe du soir." }'

La réponse est l'avis (Review), avec sa réponse dans reply. La publication produit aussi un événement review.reply_published d'origine api, livré à vos webhooks.

Les mêmes contrôles que l'application

• Réponse sensible : quand l'avis ou la réponse est jugé sensible, la publication est refusée en 422 unprocessable tant que acknowledgedSensitivity n'est pas à true. Faites relire la réponse par une personne avant de confirmer.
• Rythme d'envoi à Google : les écritures vers Google d'un établissement sont limitées, quel que soit leur canal. Au-delà, l'API répond 429 rate_limited avec Retry-After.
• Avis déjà répondu : un avis qui a déjà une réponse publiée par Ma Belle Note répond 409 conflict.
• Traçabilité : chaque publication reste visible dans l'application, comme toute réponse.

Quand la publication est coupée

La publication par l'API peut être suspendue pour tous les comptes, sans toucher au reste de l'API. Elle répond alors 503 google_publishing_disabled, et rien n'est publié. Les lectures, les brouillons et les webhooks continuent de fonctionner.

Prévoyez ce cas dans votre intégration : déposez la réponse en brouillon avec PUT /v1/reviews/{reviewId}/reply-draft (droit replies:write), pour qu'elle soit publiée depuis l'application, ou retentez plus tard avec la même Idempotency-Key.

Erreurs à traiter

Le guide des erreurs décrit le format commun de ces réponses.