Introducción
Documentación completa de los endpoints públicos de Praesenti.
Autenticación Requerida
Todos los endpoints requieren autenticación. Las credenciales se generan desde Configuración > API Keys (ver API Keys): cada credencial tiene un nombre, una clave (key), un secreto (secret), una lista de permisos y, opcionalmente, una vigencia en días (hasta 365; si no se indica, no vence).
El secreto se muestra una sola vez, al crear la credencial o al regenerarlo. Praesenti solo guarda un hash, así que si lo perdés tenés que regenerarlo.
Las credenciales se envían con autenticación HTTP Basic: el header Authorization debe contener Basic seguido de key:secret codificado en Base64.
curl https://api.praesenti.app/api/v1/public/employees \
-u "TU_KEY:TU_SECRET"O armando el header a mano:
Authorization: Basic base64(key:secret)Si falta el header o las credenciales son inválidas o están vencidas, la API responde 401. Si el header no usa el esquema Basic o no se puede decodificar, responde 400.
Permisos
Cada credencial solo puede usar los endpoints para los que tiene permiso. Si le falta un permiso, la API responde 403 con el código missing_permissions. Los endpoints de escritura (POST, PUT, DELETE) requieren también el permiso de lectura del mismo recurso.
| Recurso | Lectura | Escritura |
|---|---|---|
Empleados (/employees) | EMPLOYEES:READ | EMPLOYEES:WRITE |
Áreas (/areas) | AREAS:READ | AREAS:WRITE |
Fichadas (/clockio, /employees/:id/clockio) | CLOCK:READ | CLOCK:WRITE |
Terminales (/terminals) | TERMINALS:READ | - |
Avisos (/notifications) | EMPLOYEE_NOTIFICATIONS:READ | EMPLOYEE_NOTIFICATIONS:WRITE |
Análisis (/analysis) | ANALYSIS:READ | - |
Turnos, rotativos y asignaciones (/shifts, /rotation-shifts, /shift-assignments) | SHIFTS:READ | SHIFTS:WRITE |
Formato de errores
Los errores de la API devuelven un objeto JSON con un código y un mensaje (en español). Algunos errores incluyen además un campo debug con información adicional.
{
"code": "id_not_found",
"message": "El ID proporcionado no existe"
}Los errores del header de autenticación devuelven solo message (por ejemplo, "Missing Authorization Header").
Paginación
Los endpoints de listado no están paginados: devuelven todos los resultados en una sola respuesta. La excepción es GET /clockio, que limita la cantidad de registros cuando no se indica un rango de fechas (ver Registros de fichada).
Base URL
https://api.praesenti.app/api/v1/public