Nómina y asesoría laboral

Objetivo: alimentar tu software de nómina con horas efectivas, ausencias y saldos de vacaciones de un período, sin exportar manualmente.

Scopes necesarios: org:fichajes:read, org:ausencias:read, org:saldos:read.

Los tres recursos clave:

• GET /v1/work-summaries — el recurso de nómina: agregados cerrados de jornada por empleado y período.
• GET /v1/absences — bajas, vacaciones y deducciones del período.
• GET /v1/vacation-balances — saldos de vacaciones para el cierre.

Work summaries: horas del período

work-summaries devuelve una fila por empleado × período con los agregados ya calculados (no eventos de fichaje). Filtra por period=day|month y un rango from/to (≤ 1 año).

curl -s "$KINMU_BASE_URL/work-summaries?period=month&from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer $KINMU_API_KEY"

{
  "data": [
    {
      "employee_id": "a1b2…",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "worked_minutes": 9600,
      "break_minutes": 1200,
      "night_minutes": 300,
      "overtime_minutes": 240,
      "expected_minutes": 9600,
      "balance_minutes": 0,
      "banked_hours_balance_minutes": 120,
      "absences_minutes": 480,
      "source_days": 21
    }
  ],
  "meta": { "next_cursor": null, "has_more": false }
}

Campos relevantes para nómina:

Ausencias del período

Cruza las ausencias aprobadas que solapan el período de nómina para aplicar bajas y deducciones:

curl -s "$KINMU_BASE_URL/absences?status=approved&from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer $KINMU_API_KEY"

Cada ausencia trae type como { key, label } (la key es estable: holidays, sick-leave, o tipos custom de tu empresa) y days_count. Usa siempre la key en tu lógica.

Las claves disponibles en tu empresa salen de GET /v1/absence-types (scope org:ausencias:read). Mapea tus conceptos de nómina contra esa lista una vez y vuelve a consultarla si tu empresa crea tipos nuevos. vacation y sick_leave se aceptan como alias de holidays y sick-leave. Al crear una ausencia con un tipo que no está en el catálogo recibirás 422 validation_failed con las claves válidas.

curl -s "$KINMU_BASE_URL/absence-types?limit=100" \
  -H "Authorization: Bearer $KINMU_API_KEY"

Si importas ausencias que ya están aprobadas en tu sistema, usa status_on_create=approved: Kinmu descuenta el saldo y retira los turnos afectados igual que si las aprobara un responsable. Para empleados dados de baja puedes importar el histórico hasta su termination_date; lo posterior devuelve 422 validation_failed.

Saldos de vacaciones

Para el cierre anual o para provisiones, consulta los saldos por empleado y año:

curl -s "$KINMU_BASE_URL/vacation-balances?year=2026" \
  -H "Authorization: Bearer $KINMU_API_KEY"

{
  "data": [
    {
      "employee_id": "a1b2…",
      "year": 2026,
      "entitled_days": 23,
      "used_days": 10.5,
      "pending_days": 2,
      "remaining_days": 10.5,
      "carry_over_days": 0,
      "carry_over_expires_at": null
    }
  ]
}

Los días admiten medias jornadas (10.5); trátalos como número decimal aunque muchos valores sean enteros. carry_over_expires_at es el último día para disfrutar los días arrastrados del año anterior, o null si tu empresa no tiene arrastre o no le ha puesto plazo.

Flujo de cierre mensual

curl -s -X POST "$KINMU_BASE_URL/reports" \
  -H "Authorization: Bearer $KINMU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "type": "time_registry_monthly", "format": "csv", "params": { "month": "2026-06" } }'

# 1) obtener la download_url (solo aparece cuando status=completed)
DL=$(curl -s "$KINMU_BASE_URL/reports/<id>" \
  -H "Authorization: Bearer $KINMU_API_KEY" | jq -r '.download_url')
 
# 2) descargar el fichero desde la URL firmada (sin Bearer; un solo uso, 5 min)
curl -s -L "$DL" -o registro-horario-2026-06.csv

En los CSV, las celdas de texto que empiezan por =, +, - o @ llevan un apóstrofo delante para que la hoja de cálculo no las ejecute como fórmula; los números salen tal cual. La URL de descarga deja de valer si se revoca la key que pidió el informe o la cuenta pierde el servicio: pide el informe de nuevo con una key válida.