Saltar al contenido principal

API REST

Cada producto de imatic incluye una API REST versionada para que puedas automatizarlo desde tu propio código. Las convenciones de esta página — cómo te autenticas, cómo funcionan las claves de API, cómo se firman los webhooks y cómo se comportan la paginación, los límites de tasa y los errores — son las mismas en todos los productos. Lo que difiere son los recursos que cada producto expone, documentados en su página para desarrolladores.

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:

curl https://<product-host>/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). Una solicitud que excede el ámbito de una clave es rechazada.
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í:

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.

import crypto from "node:crypto";

function isValid(rawBody, signatureHeader, signingSecret) {
  // Header shape: "t=<epoch-seconds>,v1=<hex hmac>"
  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);
}
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.

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.

curl "https://<product-host>/v1/bookings?limit=25" \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial"
{
  "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.

{
  "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:

{
  "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.
  • Survey — formularios, respuestas, agregación de respuestas, generación de formularios con IA y webhooks (form.published, response.submitted). Consulta Survey para desarrolladores.
  • Voice Portal — agentes, campañas y contactos, además del registro de herramientas y servidor MCP. Consulta Herramientas y MCP para agentes.

Relacionado​