# API y MCP de Calendar # 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. :::note[Gestionado por admin] Las páginas de **claves de API** y **Webhooks** son gestionadas por un **admin de la cuenta**. 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: ```http Authorization: Bearer ``` 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`) | :::warning[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](./event-types), 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](./booking-page), 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](./integrations)). 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](./booking-page#nunca-habrá-reservas-duplicadas) 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: ```http X-Imatic-Signature: t=,v1= ``` Para verificar: toma `t` y el cuerpo crudo de la solicitud, calcula `HMAC-SHA256(secret, ".")` (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. :::tip[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. :::note[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](./integrations) — conecta Google y Outlook para sincronización bidireccional. - [Tipos de evento](./event-types) — el recurso en torno al cual giran la mayoría de tus llamadas a la API. - [Tu página pública de reservas](./booking-page) — el camino sin código que tus automatizaciones reflejan.