Referencia

API de Kai Manager

Conectá tus sistemas (tu web, una app, un bot de WhatsApp) con Kai Manager. Por ahora la API cubre Self-management · Reservas: consultar horarios disponibles y crear reservas con las mismas reglas que tu Plataforma. Vamos a ir sumando más módulos.

1. Activar el módulo

La API es un módulo adicional. Cuando está activo aparece Equipo y Permisos → API en el menú (solo para administradores). Si no lo ves, escribinos para habilitarlo.

Para reservas, la cuenta también necesita Self-management y Calendario, y la sección Reservas activa en Self-management → Plataforma. No hace falta que la web de la Plataforma esté publicada.

2. Crear un rol y generar la API key

En Grupos de permisos creá un grupo (por ej. “Integración web”) y tildá API · Reservas: “Consultar” y, si vas a reservar, “Crear reservas”.
En Equipo y Permisos → API tocá Generar API key, ponele un nombre y elegí ese rol.
Copiá la clave: se muestra completa una sola vez. Si la perdés, revocala y generá otra.

Podés tener varias claves (una por sistema) y cambiarles el rol cuando quieras. Una clave sin rol no puede usar ningún endpoint.

3. Autenticación

Mandá la clave en el header X-Api-Key (también se acepta Authorization: Bearer <clave>). Todas las respuestas son JSON.

URL base

https://el-sistema-backend.fly.dev/api/v1/external

Probar la clave

curl https://el-sistema-backend.fly.dev/api/v1/external/me \
  -H "X-Api-Key: kai_live_XXXXXXXXXXXXXXXX"

Respuesta 200

{
  "apiKey": { "id": "3f6c…", "name": "Web del club" },
  "account": { "id": "9b1e…", "name": "Mi Club" }
}

Usala solo desde un servidor. La clave da acceso a tu cuenta con los permisos de su rol: no la pongas en el código de una página web ni de una app móvil, porque cualquiera podría leerla. Los navegadores no pueden llamar a la API directamente.

Límites

120 requests por minuto por clave. Al superarlo recibís 429 con el header Retry-After.
La disponibilidad se consulta de a 31 días como máximo por request.

Errores

Los errores responden { "error": "mensaje", "code": "CODIGO" }. El mensaje está en español y se puede mostrar al usuario final.

HTTP	code	Qué significa
400	INVALID_QUERY / INVALID_BODY	Faltan datos o tienen un formato inválido. `issues` detalla cada campo.
401	API_KEY_MISSING / API_KEY_INVALID	No enviaste la clave, no existe o fue revocada.
403	MODULE_DISABLED	La cuenta no tiene activo el módulo API o el módulo que usa el endpoint (Self-management, Calendario).
403	API_KEY_FORBIDDEN	El rol de la clave no tiene el permiso necesario (o la clave no tiene rol).
404	RESERVATIONS_DISABLED / NOT_FOUND	Las reservas online están apagadas en la Plataforma, o el recurso no existe en tu cuenta.
409	—	El horario ya no está disponible. Volvé a consultar la disponibilidad.
429	RATE_LIMITED	Superaste el límite. Respetá el header Retry-After.
503	MAINTENANCE	Mantenimiento temporal. Reintentá más tarde.

Siguiente: Self-management · Reservas →