# API REST # API REST Los productos de imatic incluyen APIs REST que puedes automatizar desde tu propio código. Las convenciones de esta página — autenticación, claves de API, firma de webhooks, paginación, límites de tasa y errores — son las mismas en todos los productos. Lo que difiere es la forma de la URL y los **recursos** que cada producto expone: Calendar usa rutas versionadas `/v1`, mientras que Survey usa endpoints de estilo verbo `POST`. La página para desarrolladores de cada producto documenta su superficie exacta. :::note[Los ejemplos son ilustrativos] Los fragmentos de solicitud y respuesta a continuación muestran la *forma* de las llamadas — encabezados, autenticación, sobres de error — no un esquema exacto campo por campo. Para los endpoints, parámetros y nombres de campo precisos de un producto, sigue los enlaces a la página para desarrolladores de ese producto. ::: ## Autenticación imatic usa dos tipos de credenciales, para dos llamantes diferentes: - **JWT (token de sesión)** — lo que usa la aplicación web después de iniciar sesión con correo y contraseña. Te representa *a ti* en el navegador y es de corta duración. No lo gestionas directamente; lo hace la app. - **Clave de API con ámbitos** — lo que usa *tu código* para llamar a la API REST `v1`. La creas tú mismo, lleva ámbitos explícitos y no caduca con una sesión de navegador. Para llamadas servidor a servidor, usa siempre una clave de API — nunca tu contraseña ni un token de sesión copiado. ### Enviar una clave de API Pasa la clave como token Bearer en el encabezado `Authorization`: ```bash curl https:///v1/event-types \ -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial" \ -H "Content-Type: application/json" ``` ## Cómo funcionan las claves de API Creas y gestionas las claves de API en el área de desarrolladores de cada producto — por ejemplo, **Desarrolladores → claves de API** de Calendar y **Desarrolladores → claves de API** de Survey. Una clave tiene tres propiedades que conviene entender: - **Formato `prefix.secret`** — una clave tiene un **prefijo** público y una parte secreta, unidos por un punto (por ejemplo `cal_abc123.s3cr3t_keymaterial` — las claves de Calendar usan un prefijo corto `cal_`). El prefijo permite a imatic identificar la clave en listas y registros; el secreto es lo que prueba que es tuya. - **Se muestra una sola vez** — el valor completo de la clave se muestra solo en el momento en que la creas. Después de eso, solo el prefijo es visible. - **Ámbitos** — cada clave está limitada a las acciones que le concedes. Los ámbitos de Calendar son `slots:read`, `bookings:read`, `bookings:write` y `mcp` (el ámbito `mcp` es lo que necesita la clave de un agente de IA — consulta [MCP para agentes de IA](./mcp)). Una solicitud que excede el ámbito de una clave es rechazada. :::danger[Trata las claves de API como contraseñas] El secreto de una clave se muestra solo una vez, al crearla. Cópialo entonces y guárdalo en un gestor de secretos o variable de entorno — nunca en el control de versiones, una captura de pantalla o un documento compartido. Si una clave se expone, **revócala** en el área de desarrolladores y crea un reemplazo. La revocación surte efecto de inmediato. ::: ## Webhooks En lugar de hacer sondeo en busca de cambios, registra una URL de webhook e imatic le hará `POST` de un evento cuando algo ocurra — por ejemplo, se crea una reserva en Calendar o se envía una respuesta en Survey. Gestionas los endpoints de webhook en el área **Desarrolladores → Webhooks** de cada producto, donde también puedes enviar una entrega de prueba. Una entrega se ve aproximadamente así: ```http POST /your/webhook/endpoint HTTP/1.1 Content-Type: application/json X-Imatic-Signature: t=1718900000,v1=9f86d081884c7d659a2feaa0c55ad015... { "event": "booking.created", "data": { "...": "event-specific payload" } } ``` ### Verificar la firma Cada entrega está firmada con **HMAC-SHA256** usando el secreto de firma de tu endpoint, en un encabezado `X-Imatic-Signature` estilo Stripe. El encabezado lleva dos campos: `t`, los **segundos** unix-epoch en el momento del envío, y `v1`, el HMAC en hexadecimal de la cadena `${t}.${body}` (la marca de tiempo, un punto literal y luego el cuerpo crudo exacto de la solicitud). Para verificar, divide el encabezado, recalcula `v1` sobre `t + "." + rawBody` con tu secreto de firma y compara en tiempo constante. Rechaza si no coinciden — y opcionalmente rechaza cuando `t` tenga más de unos minutos para protegerte contra reenvíos. ```js import crypto from "node:crypto"; function isValid(rawBody, signatureHeader, signingSecret) { // Header shape: "t=,v1=" const parts = Object.fromEntries( signatureHeader.split(",").map((kv) => kv.split("=")), ); const { t, v1 } = parts; if (!t || !v1) return false; // Sign the timestamped body: `${t}.${rawBody}` — NOT the raw body alone. const expected = crypto .createHmac("sha256", signingSecret) .update(`${t}.${rawBody}`) .digest("hex"); // Constant-time comparison to avoid timing attacks. const a = Buffer.from(v1); const b = Buffer.from(expected); return a.length === b.length && crypto.timingSafeEqual(a, b); } ``` :::note[Esquema exacto por producto] El esquema `t=…,v1=…` de arriba es el de Calendar. Confirma el nombre del encabezado, los campos y la cadena firmada en la página para desarrolladores de cada producto antes de poner en producción un verificador. ::: :::tip[Responde rápido, procesa después] Devuelve un `2xx` rápidamente para acusar recibo, luego haz cualquier trabajo lento de forma asíncrona. Si tu endpoint es lento o da error, las entregas pueden reintentarse. ::: ## Paginación Los endpoints de listado devuelven resultados en páginas para que una sola llamada nunca tenga que cargar todo. Pasa los parámetros de paginación en la solicitud y lee los metadatos de paginación en la respuesta para obtener la siguiente página. ```bash curl "https:///v1/bookings?limit=25" \ -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial" ``` ```json { "success": true, "data": [ { "...": "one item per result" } ], "pagination": { "page": 1, "limit": 20, "total": 0, "pages": 0 } } ``` Sigue solicitando la siguiente página hasta que no haya más resultados. ## Límite de tasa Las claves de API tienen límite de tasa para mantener la plataforma justa y estable. Si excedes el límite, la API responde con HTTP `429 Too Many Requests`. Reduce el ritmo y reintenta — idealmente con retroceso exponencial y jitter — en lugar de saturar el endpoint. ```json { "success": false, "error": "rate_limited", "message": "Too many requests. Please retry after a short delay." } ``` ## Manejo de errores Los errores usan códigos de estado HTTP estándar con un cuerpo JSON que describe qué salió mal. Los códigos que verás con más frecuencia: - **`400`** — la solicitud estaba mal formada o falló la validación. - **`401`** — clave de API ausente o inválida. - **`403`** — la clave es válida pero carece del ámbito (o del acceso a la org) para esta acción. - **`404`** — el recurso no existe o no es visible para esta clave. - **`409`** — un conflicto, como intentar reservar un espacio que acaba de tomarse. - **`429`** — límite de tasa; reduce el ritmo y reintenta. - **`5xx`** — un error del lado del servidor; reintenta los fallos transitorios. Un sobre de error típico: ```json { "success": false, "error": "validation_failed", "message": "A human-readable explanation of the problem." } ``` ## Recursos por producto Las convenciones de arriba son compartidas, pero cada producto expone sus propios endpoints. Empieza desde la página para desarrolladores del producto para conocer recursos, parámetros y nombres de campo exactos: - **Calendar** — tipos de evento, **espacios** de disponibilidad, reservas (crear, reprogramar, cancelar), calendarios, webhooks, claves de API y enlaces de evento. Los eventos de webhook son `booking.created`, `booking.cancelled`, `booking.rescheduled` y `booking.no_show`. Consulta [Calendar para desarrolladores](/calendar/developers). - **Survey** — formularios, respuestas, agregación de respuestas, generación de formularios con IA y webhooks (`form.published`, `response.submitted`). Consulta [Survey para desarrolladores](/survey/developers). - **Voice Portal** — agentes, campañas y contactos, además del registro de herramientas y servidor MCP. Consulta [Herramientas y MCP para agentes](/voice/agents/tools-mcp). ## Relacionado - [Visión general de la plataforma](./overview) — cuentas, organizaciones y conceptos compartidos. - [MCP para agentes de IA](./mcp) — deja que los asistentes de IA llamen a estos recursos por ti. - [Calendar para desarrolladores](/calendar/developers) — la API REST y los webhooks de Calendar. - [Survey para desarrolladores](/survey/developers) — la API, los webhooks y las herramientas MCP de Survey.