API y MCP de Calendar

Todo lo que haces en imatic Calendar lo puedes automatizar. Usa la API REST para consultar espacios y crear reservas, los webhooks para reaccionar a eventos en tiempo real y el servidor MCP para que un agente de IA reserve en tu nombre. Esta página es para desarrolladores que integran imatic Calendar en sus propias apps y herramientas.

Gestionas las credenciales en Desarrolladores en tu panel.

Gestionado por admin

Las páginas de claves de API y Webhooks son gestionadas por un admin de la cuenta (admin de org o superadmin). Si no las ves en tu panel, pide a un admin de tu cuenta que emita una clave o configure un webhook por ti.

Autenticación y claves de API

Las llamadas a la API se autentican con una clave de API enviada como token bearer:

Authorization: Bearer <your_api_key>

Gestiona las claves en Desarrolladores → claves de API, donde puedes:

• Crear una clave — copia el secreto cuando se muestre; no se vuelve a mostrar.
• Listar tus claves y ver para qué sirve cada una.
• Revocar una clave al instante si se filtra o ya no se necesita.
• Asignar ámbitos — cada clave lleva solo los permisos que concedes, así una clave de solo lectura puede listar reservas pero nunca crearlas ni cancelarlas.

Los ámbitos disponibles son:

Ámbito	Concede
slots:read	Leer los espacios de tiempo disponibles para un tipo de evento
bookings:read	Listar y leer reservas
bookings:write	Crear, cancelar y reprogramar reservas
mcp	Usar el servidor MCP (un paraguas que también cubre slots:read, bookings:read y bookings:write)

Trata las claves como contraseñas

Una clave concede acceso a tu cuenta dentro de sus ámbitos. Guárdala en un gestor de secretos o variable de entorno, nunca en código del lado del cliente ni en un repositorio público. Revoca y rota de inmediato si se expone.

API REST v1

La API REST se sirve bajo la ruta base /v1 y devuelve JSON. Los recursos disponibles son:

• Tipos de evento — listar y leer tus tipos de evento, además de duplicar un tipo de evento (POST /v1/event-types/:code/duplicate). (Crear/editar/eliminar se hace en el panel.)
• Espacios — consulta los espacios de tiempo disponibles para un tipo de evento (las mismas aperturas que se muestran en tu página de reservas, con todos los márgenes, antelación y límites aplicados).
• Reservas — CRUD completo más reprogramación: crear una reserva, listar y leer reservas, cancelar y mover una a una nueva hora. GET /v1/bookings/stats devuelve recuentos agregados de reservas.
• Enlaces de evento — crear, listar y revocar enlaces de reserva de un solo uso vinculados a un tipo de evento (POST/GET /v1/event-types/:code/links, DELETE /v1/event-links/:linkCode).
• Webhooks — gestiona tus suscripciones de webhook mediante programación.
• Users / me — GET /v1/users/me devuelve la identidad de la clave de API (la cuenta autenticada y la org).
• Calendars — trabaja con tus calendarios conectados (consulta Integraciones).

Un flujo de automatización típico: consulta los espacios de un tipo de evento, luego crea una reserva para el espacio que tu usuario eligió — la misma garantía atómica y sin reservas duplicadas que usa la página de reservas también aplica a la API.

Webhooks

Los webhooks envían eventos a tu servidor en el momento en que ocurren, así no tienes que hacer sondeo. Gestiónalos en Desarrolladores → Webhooks.

• Suscribe una URL para recibir eventos de reserva. Los eventos son exactamente: booking.created, booking.cancelled, booking.rescheduled y booking.no_show.
• Cada entrega está firmada con HMAC — verifica el encabezado de firma contra el secreto de tu webhook para confirmar que la solicitud realmente provino de imatic Calendar antes de confiar en la carga útil.
• Usa la acción integrada Test para enviar un evento de muestra a tu endpoint mientras desarrollas, para confirmar que tu manejador funciona antes de salir a producción.

La firma viaja en el encabezado X-Imatic-Signature, en un formato estilo Stripe:

X-Imatic-Signature: t=<unix-epoch-seconds>,v1=<hmac-sha256>

Para verificar: toma t y el cuerpo crudo de la solicitud, calcula HMAC-SHA256(secret, "<t>.<body>") (la marca de tiempo y el cuerpo unidos por un punto literal), codifícalo en hexadecimal y compáralo con v1. Rechaza la solicitud si no coinciden.

Siempre verifica la firma

Rechaza cualquier webhook cuya firma HMAC no coincida. Es la diferencia entre una automatización confiable y una puerta abierta.

Servidor MCP

imatic Calendar incluye un servidor de Model Context Protocol (MCP), para que los agentes y asistentes de IA puedan leer tu disponibilidad y gestionar reservas mediante herramientas bien definidas — usando la misma autenticación por clave de API y los mismos ámbitos que la API REST.

El servidor expone siete herramientas:

Herramienta	Qué hace
list_event_types	Lista tus tipos de evento reservables
list_slots	Obtiene los espacios libres de un tipo de evento
create_booking	Reserva un espacio
cancel_booking	Cancela una reserva
reschedule_booking	Mueve una reserva a una nueva hora
list_bookings	Lista las reservas existentes
get_booking	Lee una sola reserva por su código

Apunta tu cliente compatible con MCP al servidor, autentícate con una clave de API y tu agente podrá responder "¿cuándo está libre Priya el jueves?" y reservar el espacio — todo dentro de los ámbitos que concediste a esa clave.

El propio perfil de la cuenta se lee por REST con GET /v1/users/me, no a través de una herramienta MCP.

Ajusta bien el ámbito de la clave de tu agente

Da a un agente de IA una clave con solo las herramientas que necesita. Si solo necesita leer disponibilidad, no le concedas permisos de cancelación o reprogramación.

Próximos pasos

• Integraciones — conecta Google y Outlook para sincronización bidireccional.
• Tipos de evento — el recurso en torno al cual giran la mayoría de tus llamadas a la API.
• Tu página pública de reservas — el camino sin código que tus automatizaciones reflejan.