API de Turnaly

Fechas y horas

• Las fechas de calendario van como AAAA-MM-DD: el día de trabajo, la vigencia de un contrato, el rango de un reporte.
• Las marcas de tiempo van en ISO 8601 y en UTC, terminadas en Z, por ejemplo 2026-09-17T15:04:05.123Z.
• Los cálculos están hechos en hora de Colombia, America/Bogota. Un reporte del 1 al 30 de septiembre cubre esos días en hora colombiana, aunque los tiempos se entreguen en UTC. Si tu sistema muestra horas, conviértelas a la zona de Colombia o mostrará cinco horas de más.

Cuántos datos vienen

El listado de personas es el único que se pagina, con limit (hasta 200, por defecto 50) y offset; su respuesta trae total para saber cuántas quedan. Los reportes y los catálogos devuelven el periodo completo de una vez. El historial de pagos y el de envíos a nómina devuelven las últimas cincuenta líneas.

Errores

Los errores llegan con el código HTTP que corresponde y un cuerpo con un message escrito en español para que se pueda mostrar tal cual a una persona. Cuando el problema es un parámetro mal escrito, viene además un arreglo issues que dice qué campo falla.

{
  "message": "Validación fallida",
  "issues": [ { "path": "from", "message": "Escribe la fecha como AAAA-MM-DD" } ]
}

Las horas extra del mes pasado

curl -s "https://api.turnaly.co/v1/reports/overtime?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer $TURNALY_LLAVE"

Devuelve periodo, una lista personas donde cada una trae sus lineas por tipo de hora, y totales con el gran total de horas y de dinero.

Todas las personas activas, página por página

# Primera página; sigue subiendo el offset mientras offset + limit < total.
curl -s "https://api.turnaly.co/v1/employees?status=ACTIVE&limit=200&offset=0" \
  -H "Authorization: Bearer $TURNALY_LLAVE"

Un reporte que se arma solo cada lunes

#!/usr/bin/env bash
# Asistencia de la semana pasada, guardada como JSON con la fecha en el nombre.
set -euo pipefail
desde=$(date -d 'last monday -7 days' +%F)
hasta=$(date -d 'last sunday' +%F)
curl -sf "https://api.turnaly.co/v1/reports/attendance?from=$desde&to=$hasta" \
  -H "Authorization: Bearer $TURNALY_LLAVE" \
  -o "asistencia-$desde.json"

La llave se lee de una variable de entorno; no se escribe dentro del archivo. Con -f, curl falla si la API responde con un error, así que el proceso no guarda un archivo con un mensaje de error dentro.

Nómina, sin programar nada

Si usas Aleluya o Alegra, no necesitas la API: se conectan desde el panel, en Nómina → Conexión, con la cuenta de tu empresa en ese sistema. Turnaly manda las novedades del periodo y guarda el historial de cada envío.

Para los demás sistemas de nómina hay plantillas de archivo en Integraciones: se descarga el archivo del periodo y se sube en el importador de tu sistema, con los códigos que espera la nómina electrónica.

Cargar personas de una vez

Para crear muchas personas se usa el Importador del panel, que recibe una hoja de cálculo, muestra qué va a pasar antes de aplicarlo y señala las filas con problemas. Es la vía de escritura masiva del producto, y es a propósito que pase por una revisión humana.

Marcar desde una tableta en la entrada

El modo kiosco deja marcar a todo un turno desde una tableta fija en la sede, sin que cada persona use su celular. Se configura en Kioscos y la tableta se empareja con un código. Quien registró su rostro puede marcar con él en lugar del PIN (POST /v1/kiosk/punch sin pin, con faceVector, faceModel y challenges: ['BLINK']; si el servidor no lo reconoce responde 401 con codigo: 'USA_PIN'). Está explicado en el manual del panel.

Una tableta con proposito: 'REGISTRO' registra rostros con POST /v1/kiosk/enroll/start, …/consent, …/upload-urls y POST /v1/kiosk/enroll, atadas a un registroToken de diez minutos.