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:

Campo	Uso
`worked_minutes`	Tiempo efectivo trabajado.
`night_minutes`	Minutos en horario nocturno (pluses).
`overtime_minutes`	Horas extra del período.
`expected_minutes`	Jornada teórica según contrato.
`balance_minutes`	Diferencia trabajado − esperado.
`banked_hours_balance_minutes`	Saldo de la bolsa de horas.
`absences_minutes`	Minutos de ausencia en el período.

Los agregados mensuales pueden servirse desde snapshots consolidados. Si tu cierre depende de datos del día en curso, ten en cuenta una posible latencia de consolidación y cierra sobre períodos ya completos.

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: vacation, sick_leave, o tipos custom de tu empresa) y days_count. Usa siempre la key en tu lógica.

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,
      "pending_days": 2,
      "remaining_days": 11,
      "carry_over_days": 0,
      "carry_over_expires_at": null
    }
  ]
}

Flujo de cierre mensual

Lista los empleados activos del período

GET /v1/employees?status=active (pagina con cursor si tienes más de 100).

Descarga los work-summaries del mes

GET /v1/work-summaries?period=month&from=…&to=….

Cruza las ausencias aprobadas

GET /v1/absences?status=approved&from=…&to=….

(Opcional) Genera el registro horario legal

Para la inspección de trabajo, pide el informe time_registry_monthly (RD-ley 8/2019):


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" } }'

Formatos: csv o xlsx (xlsx solo para check_ins_export). Recibirás 202 { "id": "…", "status": "processing" }. Haz polling a GET /v1/reports/{id} hasta status=completed; entonces la respuesta incluye download_url, una URL firmada temporal (TTL 5 min, un solo uso). La firma es la credencial: descarga el fichero desde esa URL sin cabecera Authorization:


# 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

El scope org:informes:read es obligatorio para solicitar el informe. La download_url es de un solo uso y caduca en 5 minutos: pídela y descárgala en el momento.