Aller au contenu principal

Formule Business · version 1

API publique IA Réceptionniste : documentation

L'API permet à vos outils de piloter votre assistante téléphonique : lire vos appels et vos rendez-vous, réserver un créneau sans risque de double réservation, marquer une demande traitée, tenir à jour vos horaires, vos congés, vos prestations et vos questions fréquentes. Elle sert aussi de base aux scénarios Zapier, Make et n8n et aux assistants IA comme Claude ou ChatGPT.

Démarrer en trois étapes

  1. Dans votre espace, ouvrez Intégrations › API et créez une clé : donnez-lui un nom (« Zapier ») et seulement les droits utiles. Copiez-la : elle ne sera plus affichée.
  2. Vérifiez-la avec la requête ci-dessous : elle renvoie le nom de votre commerce, les droits et les limites de la clé.
  3. Choisissez un point d'accès, ou partez d'un des modèles Zapier, Make ou n8n plus bas.
curl -X GET "https://tpogicoxqrtfeiycvgrt.supabase.co/functions/v1/api-v1/v1/me" \
  -H "Authorization: Bearer $IAR_API_KEY"

Adresse de base : https://tpogicoxqrtfeiycvgrt.supabase.co/functions/v1/api-v1. Toutes les réponses sont en JSON ; les dates suivent le format ISO 8601 avec fuseau.

Clés, droits et sécurité

  • Chaque requête porte l'en-tête Authorization: Bearer <clé> (ou X-Api-Key). La clé est montrée une seule fois, stockée sous forme d'empreinte, révocable à tout moment.
  • Une clé n'agit que sur le compte qui l'a créée. Ce compte vient de la clé, jamais du contenu de la requête.
  • Limites par clé : 60 requêtes par minute et 5 000 par jour. Au-delà, réponse 429 avec l'en-tête Retry-After. Chaque requête est inscrite au journal d'usage de votre espace (sans son contenu).
Droits d'une clé
DomaineLectureÉcriture
Appelscalls:read—
Rendez-vousappointments:readappointments:write (prendre, déplacer, annuler)
Demandesrequests:readrequests:write (marquer traitée)
Questions fréquentesfaq:readfaq:write (modifier)
Horaireshours:readhours:write (modifier)
Congés et fermeturesclosures:readclosures:write (modifier)
Prestationsservices:readservices:write (modifier)

Points d'accès

  • GET /v1/me

    Le compte de la clé : nom du commerce, fuseau, droits, limites.

  • GET /v1/calls

    Derniers appels (motif, résumé court, urgence) ; jamais la transcription. Droit : calls:read.

  • GET /v1/appointments

    Rendez-vous à venir, ou entre deux jours (from, to). Droit : appointments:read.

  • GET /v1/availability?date=AAAA-MM-JJ

    Créneaux libres d'un jour, calculés comme le fait l'assistante. Droit : appointments:read.

  • POST /v1/appointments

    Prendre un rendez-vous (jamais de double réservation). Droit : appointments:write.

  • PATCH /v1/appointments/{id}

    Déplacer un rendez-vous vers un créneau libre. Droit : appointments:write.

  • POST /v1/appointments/{id}/cancel

    Annuler un rendez-vous. Droit : appointments:write.

  • GET /v1/requests

    Demandes à rappeler (status=pending, done ou all). Droit : requests:read.

  • POST /v1/requests/{id}/done

    Marquer une demande traitée. Droit : requests:write.

  • GET /v1/faq

    Questions fréquentes de l'assistante. Droit : faq:read.

  • POST /v1/faq

    Ajouter une question (PUT pour remplacer la liste, DELETE /v1/faq/{position}?question=… pour en retirer une). Droit : faq:write.

  • GET /v1/hours

    Horaires de la semaine. Droit : hours:read.

  • PUT /v1/hours

    Remplacer les horaires (jours absents = fermés). Droit : hours:write.

  • GET /v1/closures

    Congés et créneaux bloqués. Droit : closures:read.

  • POST /v1/closures

    Poser des congés ou bloquer un créneau (DELETE /v1/closures/{position}?start=… pour retirer). Droit : closures:write.

  • GET /v1/services

    Prestations (nom, durée, prix). Droit : services:read.

  • POST /v1/services

    Ajouter une prestation (PUT pour remplacer la liste, DELETE /v1/services/{position}?name=…). Droit : services:write.

Réserver un rendez-vous

Cherchez d'abord un créneau libre, puis réservez-le. La réservation passe par le même moteur que l'assistante : horaires, congés, délai de prévenance, agenda relié et rendez-vous existants sont vérifiés au moment même de l'enregistrement. Si le créneau vient d'être pris, la réponse est 409 slot_taken et rien n'est enregistré. L'en-tête Idempotency-Key protège contre les doublons quand votre outil réessaie. Le client reçoit le SMS de confirmation prévu par vos réglages.

curl -X GET "https://tpogicoxqrtfeiycvgrt.supabase.co/functions/v1/api-v1/v1/availability?date=2026-12-01&service=Coupe" \
  -H "Authorization: Bearer $IAR_API_KEY"
curl -X POST "https://tpogicoxqrtfeiycvgrt.supabase.co/functions/v1/api-v1/v1/appointments" \
  -H "Authorization: Bearer $IAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: formulaire-4521" \
  -d '{"start_at":"2026-12-01T09:00:00+04:00","client_name":"Marie Hoarau","client_phone":"0692123456","service":"Coupe"}'

Horaires, congés, prestations et questions fréquentes

Chaque modification est enregistrée puis transmise à votre assistante téléphonique. La réponse contient assistant_sync : « ok » quand l'assistante l'a reçue, « failed » si la transmission doit être relancée (la modification reste enregistrée). Pour supprimer un élément, indiquez sa position et son texte : si la liste a changé entre-temps, rien n'est supprimé.

curl -X POST "https://tpogicoxqrtfeiycvgrt.supabase.co/functions/v1/api-v1/v1/closures" \
  -H "Authorization: Bearer $IAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-12-24","to":"2026-12-26","reason":"Fêtes"}'

Erreurs

Une erreur renvoie {"error":{"code":"…","message":"…"}} : un code stable pour vos outils et une phrase claire pour les personnes.

  • 401 missing_key, invalid_key, key_revokedClé absente, inconnue ou révoquée.
  • 403 plan_required, insufficient_scopeFormule sans API, ou droit absent de la clé.
  • 404 not_foundÉlément inexistant ou appartenant à un autre compte.
  • 409 slot_taken, changed, duplicate, conflictCréneau déjà pris, élément modifié entre-temps, doublon.
  • 422 invalid, closed, past, too_soon, too_farDonnée invalide, jour fermé, moment passé ou hors délai.
  • 429 rate_limitedLimite d'usage atteinte : attendez Retry-After secondes.

Déclencheurs : les webhooks

Pour réagir à ce qui se passe, ajoutez un point d'arrivée dans Intégrations › Webhooks : un message signé part à chaque événement choisi, avec des données minimales.

  • call.ended · Appel terminé
  • appointment.created · Rendez-vous créé
  • appointment.rescheduled · Rendez-vous déplacé
  • appointment.cancelled · Rendez-vous annulé
  • request.created · Demande créée

Modèles Zapier, Make et n8n

Des scénarios courants, à reproduire dans votre outil. Les étapes ci-dessous sont celles de Zapier ; Make et n8n suivent le même principe (« Webhooks » → « Custom webhook » et « HTTP » → « Make a request » pour Make, nœud « Webhook » (méthode POST) et nœud « HTTP Request » pour n8n).

Chaque rendez-vous dans un tableur

Une ligne par rendez-vous pris par l'assistante ou par vous (date, client, prestation).

  1. Dans Zapier, créez un déclencheur « Webhooks by Zapier » → « Catch Hook » et copiez l'adresse qu'il vous donne.
  2. Dans Intégrations › Webhooks, ajoutez cette adresse et cochez « Rendez-vous créé », puis « Envoyer un test ».
  3. Action : Ajouter une ligne dans votre tableur (Google Sheets, Excel…) avec data.start_at, data.client_name, data.service.

Demande urgente → message sur votre téléphone

Un message (Slack, WhatsApp, e-mail…) dès qu'un appelant signale une urgence.

  1. Dans Zapier, créez un déclencheur « Webhooks by Zapier » → « Catch Hook » et copiez l'adresse qu'il vous donne.
  2. Dans Intégrations › Webhooks, ajoutez cette adresse et cochez « Demande créée », puis « Envoyer un test ».
  3. Ajoutez un filtre : data.urgent = true.
  4. Action : Envoyer un message avec data.caller_name, data.caller_number et data.reason.

Formulaire de votre site → rendez-vous

Un client qui remplit votre formulaire (Typeform, Tally, Google Forms…) obtient un rendez-vous, sans double réservation.

  1. Dans Zapier, déclencheur : Nouvelle réponse à votre formulaire.
  2. Créez une clé d'API dans Intégrations › API avec le droit « appointments:write ».
  3. Action « Webhooks by Zapier » → « Custom Request » : POST sur l'adresse de l'API suivie de /v1/appointments, en-tête Authorization: Bearer <votre clé>, corps JSON comme dans l'exemple.

Chaque soir : les demandes à rappeler

Un e-mail à 18 h avec les demandes encore en attente.

  1. Dans Zapier, déclencheur : Planification quotidienne à 18 h dans votre outil.
  2. Créez une clé d'API dans Intégrations › API avec le droit « requests:read ».
  3. Action « Webhooks by Zapier » → « Custom Request » : GET sur l'adresse de l'API suivie de /v1/requests?status=pending, en-tête Authorization: Bearer <votre clé>.

Appel terminé → fiche dans votre CRM

Chaque appel crée ou complète un contact dans votre CRM, avec le motif et le résumé.

  1. Dans Zapier, créez un déclencheur « Webhooks by Zapier » → « Catch Hook » et copiez l'adresse qu'il vous donne.
  2. Dans Intégrations › Webhooks, ajoutez cette adresse et cochez « Appel terminé », puis « Envoyer un test ».
  3. Action : Créer ou mettre à jour le contact avec data.caller_number, data.caller_name, data.reason, data.summary.

Claude, ChatGPT et assistants compatibles MCP

Votre espace donne l'adresse d'un serveur MCP à ajouter comme connecteur dans votre assistant IA. Après votre autorisation, il agit avec les mêmes garde-fous que l'API : votre compte seulement, mêmes limites, même moteur de réservation. Avant d'annuler un rendez-vous ou de supprimer un réglage, il doit vous demander une confirmation explicite. En lecture, il est disponible sur toutes les formules ; en écriture, avec la formule Business.

Questions fréquentes sur l'API

Les comptes en formule Business. Le gérant crée ses clés dans Intégrations › API (10 clés actives au plus). Un collaborateur invité ne peut pas créer de clé.

Non. Le compte est déterminé par la clé elle-même, jamais par la requête : même en ajoutant l'identifiant d'un autre compte, la clé ne lit et ne modifie que le compte qui l'a créée.

Elle n'est montrée qu'une fois et seule son empreinte est conservée : personne ne peut la relire, pas même nous. Révoquez-la dans Intégrations › API et créez-en une nouvelle ; l'ancienne cesse de fonctionner immédiatement.

Non. L'API utilise exactement le même moteur de réservation que l'assistante téléphonique et le tableau de bord, sous le même verrou : deux réservations simultanées du même créneau ne peuvent pas réussir toutes les deux.

Immédiatement : chaque modification est transmise à l'assistante, et la réponse indique le résultat réel de cette transmission (assistant_sync). Si la transmission échoue, la modification reste enregistrée et la réponse le dit.

Prêt à relier vos outils ?

L'API, les webhooks et les modèles sont inclus dans la formule Business. Les formules et leurs fonctions sont détaillées sur la page des tarifs.