Laissez des agents IA réserver chez vous

Serveur MCP

Le Model Context Protocol permet à un assistant IA d’appeler directement les outils de Cadenspot : Streamable HTTP et JSON-RPC 2.0 sur une seule URL, et chaque clé n’agit que pour un seul établissement.

POSThttps://cadenspot.com/api/mcp

Outils

Une clé ne voit et n’appelle que les outils permis par ses permissions.

Connecter votre assistant

Ajoutez ceci à la configuration de votre client MCP (Claude Code la lit dans .mcp.json) et remplacez YOUR_API_KEY par une clé créée dans Tableau de bord → Paramètres → Clés API. Les autres clients ont besoin de la même URL et de l’en-tête Authorization.

{
  "mcpServers": {
    "cadenspot": {
      "type": "http",
      "url": "https://cadenspot.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Référence complète de l’API et du MCP disponible sur demande [email protected]

API REST v1

Pour le code qui n’est pas un client MCP : HTTPS et JSON, avec les mêmes clés et permissions. Envoyez la clé comme jeton Bearer.

• GET/api/v1/services

  L’établissement et ses prestations réservables, avec les prix fixés par le propriétaire.availability:read

• GET/api/v1/availability

  Les créneaux libres d’une prestation, calculés en direct, sur 14 jours au plus.availability:read

• POST/api/v1/bookings

  Réserve un créneau. Envoyez l’en-tête Idempotency-Key pour qu’une nouvelle tentative ne réserve jamais deux fois.bookings:write

• GET/api/v1/bookings/:id

  Une réservation et les actions encore permises.bookings:read

• PATCH/api/v1/bookings/:id

  Annule (bookings:cancel) ou déplace (bookings:write) une réservation.bookings:cancelbookings:write

Les erreurs reviennent en JSON avec un code stable et un message : 401 pour une clé invalide, 403 s’il manque la permission, 429 à la limite de débit.

Un premier appel

curl https://cadenspot.com/api/v1/services \
  -H "Authorization: Bearer YOUR_API_KEY"

Référence complète de l’API et du MCP disponible sur demande [email protected]

Webhooks

Soyez prévenu quand il se passe quelque chose. Le propriétaire ajoute un endpoint dans Tableau de bord → Paramètres → Webhooks et choisit les événements.

• booking.createdUne réservation est confirmée.
• booking.requestedUne réservation attend l’accord du propriétaire.
• booking.rescheduledUne réservation a été déplacée.
• booking.cancelledUne réservation a été annulée.
• booking.declinedLe propriétaire a refusé une demande, ou elle a expiré.
• booking.reminderEnviron 24 heures avant le rendez-vous.
• booking.no_showLe propriétaire a noté le client absent.
• escalation.createdUn agent a transmis une conversation au propriétaire.
• waitlist.slot_openedUn créneau s’est libéré et la liste d’attente a été prévenue.
• rebook.dueUn client devrait réserver sa prochaine visite.

Envois signés

Chaque envoi porte x-veyracal-signature (v1= puis un HMAC-SHA256 en hexadécimal du timestamp, d’un point et du corps brut), x-veyracal-timestamp (secondes Unix), x-veyracal-event et x-veyracal-delivery. Avant de comparer le HMAC, refusez l’envoi si le timestamp ou la signature manque ou est mal formé, ou si le timestamp s’écarte de plus de 300 secondes de votre horloge ; comparez ensuite en temps constant et dédoublonnez sur l’id d’envoi. Un envoi échoué est tenté jusqu’à 5 fois au total.

Sûr par conception

• Des clés au pouvoir minimal

  Chaque clé appartient à un seul établissement et ne fait que ce que le propriétaire coche : voir les créneaux, réserver, annuler ou approuver. Les clés peuvent expirer, être révoquées, et ne sont stockées que sous forme de hash.

• Les règles du salon à chaque requête

  Horaires, battements, délai de prévenance, limites par jour et horizon de réservation sont vérifiés par le serveur à chaque réservation, blocage et déplacement. Aucun outil n’accepte de prix : les prix viennent uniquement des paramètres du propriétaire. Une même personne ne peut jamais être réservée deux fois sur le même créneau.

• Réessayer sans risque

  Avec une clé d’idempotence, une requête répétée renvoie la même réservation au lieu d’en créer une deuxième, et une clé ne renvoie jamais la réservation d’un autre établissement. Via MCP, un créneau pris entre-temps revient avec des alternatives proches.

• Un humain pour les cas délicats

  Remboursements, plaintes et urgences vont au propriétaire via escalate_to_owner, et intake les repère dans les mots du client. Une annulation exige confirmed: true, envoyé seulement après le oui du client, et accepter ou refuser une demande exige une clé avec la permission bookings:approve.

Questions

Quels assistants IA peuvent se connecter ?

Tout assistant ou plateforme d’agents qui gère les serveurs MCP distants en HTTP, et tout code capable d’appeler une API HTTPS.

Comment obtenir une clé API ?

Le propriétaire la crée dans Tableau de bord → Paramètres → Clés API, choisit ses permissions et la copie une seule fois : elle n’est plus jamais affichée.

Un agent peut-il réserver hors des horaires ou changer un prix ?

Non. Chaque réservation, blocage et déplacement est vérifié contre les horaires, battements, délais et limites par jour du propriétaire, et aucun outil n’accepte de prix : les prix viennent uniquement de ses paramètres.

Et si la même requête est envoyée deux fois ?

Envoyez la même clé d’idempotence (idempotencyKey en MCP, l’en-tête Idempotency-Key en REST) : la deuxième requête renvoie la première réservation.

Que se passe-t-il si un client demande un remboursement ou se plaint ?

L’agent appelle escalate_to_owner : le propriétaire reçoit un e-mail, la demande apparaît dans sa boîte de réception et le webhook escalation.created est envoyé.

Y a-t-il des limites de débit ?

Oui. Aujourd’hui, chaque clé a droit à 120 requêtes d’un coup, puis 2 par seconde, comptées séparément pour MCP et REST. Ces limites peuvent évoluer.