Para desarrolladores

Conecta tu software con Kuadrai

API REST con claves por negocio y webhooks firmados. Pensada para lo típico: volcar fichajes en la nómina, pintar los turnos en otra pantalla o enterarte al momento de lo que pasa vía Zapier, Make o tu propio ERP.

Autenticación

Cada negocio tiene sus propias claves (se piden al equipo de Kuadrai y se ven una sola vez). Van en la cabecera Authorization y solo dan acceso a los datos de ese negocio. Hay dos permisos: read (consultas) y write (crear turnos y fichajes). Límite: 60 peticiones por minuto por clave (con 429 y cabecera Retry-After si te pasas).

curl https://kuadrai.com/api/v1/empleados \
  -H "Authorization: Bearer kd_abc123_su_secreto_completo"

Endpoints

Método	Ruta	Permiso	Qué hace
GET	/api/v1/empleados	read	Empleados del negocio (nombre, usuario, departamento, estado).
GET	/api/v1/turnos?desde=&hasta=	read	Turnos asignados, filtrables por rango de fechas.
GET	/api/v1/fichajes?desde=&hasta=	read	Fichajes con las horas ya calculadas (para nóminas o ERP).
POST	/api/v1/turnos	write	Crea una asignación de turno para un empleado.
POST	/api/v1/fichajes	write	Ficha la entrada o la salida de un empleado.

Crear un turno

curl -X POST https://kuadrai.com/api/v1/turnos \
  -H "Authorization: Bearer kd_abc123_su_secreto_completo" \
  -H "Content-Type: application/json" \
  -d '{
    "empleadoId": "cmc123abc...",
    "fecha": "2026-07-20",
    "horario": "Tarde 16:30–22:00"
  }'

Fichar entrada / salida

curl -X POST https://kuadrai.com/api/v1/fichajes \
  -H "Authorization: Bearer kd_abc123_su_secreto_completo" \
  -H "Content-Type: application/json" \
  -d '{ "empleadoId": "cmc123abc...", "accion": "entrada" }'

Webhooks

Registra una URL https y te mandamos un POST con cada evento al que te suscribas. Si tu servidor falla, reintentamos automáticamente (hasta 3 intentos en total, con espera creciente entre uno y otro); un endpoint que encadena fallos se desactiva solo.

shift.assigned

Se asigna un turno a un empleado

shift.modified

Se modifica o retira un turno

week.opened

El manager abre una semana

swap.proposed

Un empleado propone un cambio de turno

swap.approved

El manager aprueba un cambio

timeclock.in

Un empleado ficha la entrada

timeclock.out

Un empleado ficha la salida

employee.joined

Un empleado nuevo se une al negocio

Formato del envío

POST https://tu-servidor.com/webhook
X-Kuadrai-Event: shift.assigned
X-Kuadrai-Signature: t=1789300000,v1=5f8a2b...

{
  "event": "shift.assigned",
  "createdAt": "2026-07-13T18:30:00.000Z",
  "data": { "userId": "cmc123abc...", "title": "Turno asignado", "message": "..." }
}

Verificar la firma

Cada webhook va firmado con el secreto de tu endpoint (mismo esquema que Stripe): la cabecera trae el timestamp t y la firma v1 = HMAC-SHA256 del texto `${t}.${cuerpo}`. Comprueba también que t es reciente (±5 min) para evitar replays.

// Node.js
const crypto = require('crypto');

function verificarFirma(cabecera, cuerpo, secreto) {
  const partes = Object.fromEntries(cabecera.split(',').map((p) => p.split('=')));
  const esperada = crypto
    .createHmac('sha256', secreto)
    .update(`${partes.t}.${cuerpo}`)
    .digest('hex');
  const reciente = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300;
  return reciente && crypto.timingSafeEqual(
    Buffer.from(partes.v1, 'hex'),
    Buffer.from(esperada, 'hex')
  );
}

¿Necesitas una clave de API?

La API y los webhooks se activan por negocio. Escríbenos desde el formulario de contacto y te lo dejamos listo.

Hablar con nosotros