Guía: integrar la API pública de Orkelis

La API pública de Orkelis permite integrar tus horarios, ausencias, usuarios y fichajes con tus herramientas: SIRH, ERP, software de nóminas, herramientas de BI, aplicaciones de negocio, etc. La API sigue los principios REST y usa autenticación por clave API. Esta guía cubre la generación de claves, autenticación, endpoints, paginación, webhooks y buenas prácticas de seguridad.

Requisitos previos

• Plan Pro o Enterprise (la API no está disponible en el plan Esencial).
• Cuenta de administrador para generar claves API.
• Conocimientos básicos de programación y HTTP/REST.
• Herramienta para probar: curl, Postman, Insomnia o un lenguaje de programación.

1. Generar una clave API

Las claves API son el mecanismo de autenticación. Cada clave tiene permisos (scopes) y puede tener fecha de expiración.

1. Inicia sesión como administrador.
2. Ve a Claves API (/dashboard/api-keys).
3. Haz clic en Generar una clave API.
4. Rellena: Nombre, Scopes, Fecha de expiración (opcional pero recomendada).
5. Haz clic en Crear.
6. La clave se muestra una sola vez. Cópiala y guárdala en un lugar seguro.

Seguridad crítica: la clave se muestra una sola vez. Almacénala en un gestor de secretos. Nunca la subas a un repositorio git ni la envíes por correo sin cifrar.

Scopes disponibles

• read:users — Lectura de usuarios.
• write:users — Escritura de usuarios.
• read:plannings — Lectura de horarios.
• write:plannings — Escritura de horarios.
• read:absences — Lectura de ausencias.
• write:absences — Escritura de ausencias.
• read:time-entries — Lectura de fichajes.

2. Autenticación

Incluye el header X-API-Key en cada petición. Error 401 si la clave es inválida o falta.

Ejemplo

curl -H "X-API-Key: sk_live_tu_clave" \
  https://orkelis.app/api/v1/public/users

Códigos de respuesta HTTP

• 200 OK: petición correcta.
• 201 Created: recurso creado.
• 400 Bad Request: datos inválidos.
• 401 Unauthorized: clave faltante o inválida.
• 403 Forbidden: scope insuficiente.
• 404 Not Found: recurso inexistente.
• 422 Unprocessable Entity: datos válidos pero inconsistentes.
• 429 Too Many Requests: límite de tasa alcanzado.
• 500 Internal Server Error: error interno.

3. Endpoints disponibles

Usuarios

• GET /api/v1/public/users — Listar usuarios — scope: read:users
• GET /api/v1/public/users/:id — Detalle — scope: read:users
• POST /api/v1/public/users — Crear — scope: write:users
• PATCH /api/v1/public/users/:id — Modificar — scope: write:users
• DELETE /api/v1/public/users/:id — Desactivar — scope: write:users

Horarios

• GET /api/v1/public/plannings — Listar horarios — scope: read:plannings
• POST /api/v1/public/plannings — Crear asignación — scope: write:plannings
• PATCH /api/v1/public/plannings/:id — Modificar — scope: write:plannings
• DELETE /api/v1/public/plannings/:id — Eliminar — scope: write:plannings

Ausencias

• GET /api/v1/public/absences — Listar — scope: read:absences
• POST /api/v1/public/absences — Crear — scope: write:absences
• PATCH /api/v1/public/absences/:id — Modificar — scope: write:absences
• DELETE /api/v1/public/absences/:id — Cancelar — scope: write:absences

Fichajes

• GET /api/v1/public/time-entries — Listar — scope: read:time-entries
• GET /api/v1/public/time-entries/:id — Detalle — scope: read:time-entries

4. Paginación

Dos modos: por página (offset) y por cursor.

Por página

GET /api/v1/public/users?page=2&limit=50

Por cursor

GET /api/v1/public/users?cursor=eyJpZCI6IjEyMyJ9&limit=50

Cuando nextCursor es null, has llegado a la última página.

5. Rate Limiting

• Plan Pro: 100 peticiones/minuto por clave.
• Plan Enterprise: 1.000 peticiones/minuto por clave.

Error 429 si excedes el límite. Espera el tiempo indicado en Retry-After.

Implementa exponential backoff en tus integraciones para los errores 429 y 5xx.

6. Webhooks

Recibe notificaciones en tiempo real configurando webhooks.

Eventos disponibles

• planning.published, planning.updated
• absence.created, absence.approved, absence.rejected
• user.created, user.updated
• time-entry.created

Verificación de firma

Si configuraste un secreto, verifica el header X-Webhook-Signature (HMAC SHA-256).

7. Gestión de claves

• Rotación: regenera sin eliminar la clave antigua.
• Revocación: elimina una clave comprometida.
• Logs de uso: consulta el historial de cada clave.
• Expiración: configura fechas de expiración. Orkelis envía recordatorio 7 días antes.

Principio de mínimo privilegio: crea una clave por integración con solo los scopes necesarios.

8. Buenas prácticas

• Usa paginación por cursor para sincronizaciones masivas.
• Implementa exponential backoff.
• Almacena claves en un gestor de secretos.
• Verifica firmas de webhooks.
• Registra todos los errores API.
• Prueba en staging antes de producción.

9. Resolución de problemas

• 401: clave faltante, inválida o expirada.
• 403: scope insuficiente.
• 404: recurso inexistente.
• 422: datos inconsistentes.
• 429: límite de tasa excedido.
• Webhook no recibido: verifica URL accesible y logs de entrega.
• Datos faltantes: verifica tus scopes.

Soporte técnico API: contacta [email protected] o consulta la documentación Swagger en orkelis.app/api/docs.