Deja que agentes de IA reserven con tu negocio

Servidor MCP

El Model Context Protocol permite a un asistente de IA llamar directamente a las herramientas de Cadenspot: Streamable HTTP y JSON-RPC 2.0 en una sola URL, y cada clave actúa solo para un negocio.

POSThttps://cadenspot.com/api/mcp

Herramientas

Una clave solo ve y usa las herramientas que permiten sus permisos.

Conecta tu asistente

Añade esto a la configuración de tu cliente MCP (Claude Code la lee de .mcp.json) y sustituye YOUR_API_KEY por una clave de Panel → Ajustes → Claves API. Otros clientes necesitan la misma URL y la cabecera Authorization.

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

Referencia completa de la API y del MCP disponible bajo petición [email protected]

API REST v1

Para código que no es un cliente MCP: HTTPS y JSON, con las mismas claves y permisos. Envía la clave como token Bearer.

• GET/api/v1/services

  El negocio y sus servicios reservables, con los precios configurados por el dueño.availability:read

• GET/api/v1/availability

  Horas libres de un servicio, calculadas al momento, hasta 14 días.availability:read

• POST/api/v1/bookings

  Reserva una hora. Envía la cabecera Idempotency-Key para que un reintento nunca reserve dos veces.bookings:write

• GET/api/v1/bookings/:id

  Una reserva y las acciones que aún se permiten.bookings:read

• PATCH/api/v1/bookings/:id

  Cancela (bookings:cancel) o cambia de hora (bookings:write) una reserva.bookings:cancelbookings:write

Los errores vuelven en JSON con un código estable y un mensaje: 401 si la clave no vale, 403 si le falta el permiso, 429 al llegar al límite.

Una primera llamada

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

Referencia completa de la API y del MCP disponible bajo petición [email protected]

Webhooks

Entérate cuando pasa algo. El dueño añade un endpoint en Panel → Ajustes → Webhooks y elige los eventos.

• booking.createdSe confirma una reserva.
• booking.requestedUna reserva espera la aprobación del dueño.
• booking.rescheduledUna reserva cambió de hora.
• booking.cancelledSe canceló una reserva.
• booking.declinedEl dueño rechazó una solicitud, o caducó.
• booking.reminderUnas 24 horas antes de la cita.
• booking.no_showEl dueño marcó que el cliente no vino.
• escalation.createdUn agente pasó una conversación al dueño.
• waitlist.slot_openedSe liberó una hora y se avisó a la lista de espera.
• rebook.dueUn cliente debería reservar su próxima visita.

Envíos firmados

Cada envío lleva x-veyracal-signature (v1= y un HMAC-SHA256 en hexadecimal del timestamp, un punto y el cuerpo sin modificar), x-veyracal-timestamp (segundos Unix), x-veyracal-event y x-veyracal-delivery. Antes de comparar el HMAC, rechaza el envío si falta el timestamp o la firma o tienen un formato incorrecto, o si el timestamp se aleja más de 300 segundos de tu reloj; luego compara en tiempo constante y elimina duplicados con el id de envío. Un envío fallido se intenta hasta 5 veces en total.

Seguro por diseño

• Claves con el mínimo poder

  Cada clave pertenece a un solo negocio y hace solo lo que el dueño marca: ver horas libres, reservar, cancelar o aprobar. Las claves pueden caducar, se pueden revocar y solo se guardan como hash.

• Las reglas del salón en cada petición

  El servidor comprueba el horario, los márgenes, la antelación, los límites diarios y hasta cuándo se puede reservar en cada reserva, bloqueo y cambio de hora. Ninguna herramienta acepta un precio: los precios solo salen de la configuración del dueño. La misma persona nunca puede tener dos reservas a la misma hora.

• Reintentos sin riesgo

  Con una clave de idempotencia, una petición repetida devuelve la misma reserva en vez de crear otra, y una clave nunca devuelve la reserva de otro negocio. Por MCP, si la hora se ocupó mientras tanto, la respuesta trae alternativas cercanas.

• Una persona para lo difícil

  Los reembolsos, las quejas y las urgencias llegan al dueño con escalate_to_owner, e intake los detecta en las palabras del cliente. Cancelar exige confirmed: true, que solo se envía tras el sí del cliente, y aceptar o rechazar una solicitud exige una clave con el permiso bookings:approve.

Preguntas

¿Qué asistentes de IA se pueden conectar?

Cualquier asistente o plataforma de agentes que admita servidores MCP remotos por HTTP, y cualquier código capaz de llamar a una API HTTPS.

¿Cómo consigo una clave API?

El dueño del negocio la crea en Panel → Ajustes → Claves API, elige sus permisos y la copia una sola vez: no se vuelve a mostrar.

¿Puede un agente reservar fuera del horario o cambiar un precio?

No. Cada reserva, bloqueo y cambio de hora se comprueba contra el horario, los márgenes, la antelación y los límites diarios del dueño, y ninguna herramienta acepta un precio: los precios solo salen de su configuración.

¿Y si la misma petición se envía dos veces?

Envía la misma clave de idempotencia (idempotencyKey en MCP, la cabecera Idempotency-Key en REST) y la segunda petición devuelve la primera reserva.

¿Qué pasa si un cliente pide un reembolso o se queja?

El agente llama a escalate_to_owner: el dueño recibe un correo, el caso aparece en su Bandeja y se envía el webhook escalation.created.

¿Hay límites de uso?

Sí. Hoy cada clave tiene 120 peticiones de golpe y luego 2 por segundo, contadas por separado para MCP y REST. Los límites pueden cambiar.