Payroll e consulenza del lavoro

Obiettivo: alimentare il tuo software payroll con ore effettive, assenze e saldi ferie di un periodo, senza export manuali.

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

Le tre risorse chiave:

GET /v1/work-summaries — la risorsa per il payroll: aggregati chiusi di giornata per dipendente e periodo.
GET /v1/absences — malattie, ferie e trattenute del periodo.
GET /v1/vacation-balances — saldi ferie per la chiusura.

Work summaries: le ore del periodo

work-summaries restituisce una riga per dipendente × periodo con gli aggregati già calcolati (non eventi di timbratura). Filtra per period=day|month e un intervallo from/to (≤ 1 anno).


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

Campi rilevanti per il payroll:

Campo	Uso
`worked_minutes`	Tempo effettivo lavorato.
`night_minutes`	Minuti in orario notturno (maggiorazioni).
`overtime_minutes`	Straordinari del periodo.
`expected_minutes`	Orario teorico da contratto.
`balance_minutes`	Differenza lavorato − previsto.
`banked_hours_balance_minutes`	Saldo della banca ore.
`absences_minutes`	Minuti di assenza nel periodo.

work-summaries e vacation-balances ignorano updated_since (accettato per compatibilità; obsoleto, rimozione il 27-08-2027): per aggiornare una chiusura, richiedi di nuovo l’intervallo (from/to, year) invece di provare un delta.

Gli aggregati mensili possono essere serviti da snapshot consolidati. Se la tua chiusura dipende dai dati del giorno in corso, considera una possibile latenza di consolidamento e chiudi su periodi già completi.

Assenze del periodo

Incrocia le assenze approvate che si sovrappongono al periodo payroll per applicare malattie e trattenute:


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

Ogni assenza porta type come { key, label } (la key è stabile: vacation, sick_leave, o tipi custom della tua azienda) e days_count. Nella tua logica usa sempre la key.

Saldi ferie

Per la chiusura annuale o per gli accantonamenti, consulta i saldi per dipendente e anno:


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
    }
  ]
}

Flusso di chiusura mensile

Elenca i dipendenti attivi del periodo

GET /v1/employees?status=active (pagina con cursor se ne hai più di 100).

Se la tua integrazione crea anche dipendenti, POST /v1/employees può rispondere 402 billing_required: l’abbonamento è attivo ma il piano è rimasto senza posti. Amplia il piano dalla dashboard; riprovare senza cambiare nulla restituisce lo stesso 402. L’email del dipendente è unica per azienda, non globale.

Scarica i work-summaries del mese

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

Incrocia le assenze approvate

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

(Opzionale) Genera il registro orario legale

Per l’ispezione del lavoro, richiedi il report time_registry_monthly (RD-ley 8/2019, normativa spagnola):


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

Formati: csv o xlsx (xlsx solo per check_ins_export). Riceverai 202 { "id": "…", "status": "processing" }. Fai polling su GET /v1/reports/{id} fino a status=completed; a quel punto la risposta include download_url, una URL firmata temporanea (TTL 5 min, monouso). La firma è la credenziale: scarica il file da quella URL senza header 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

Lo scope org:informes:read è obbligatorio per richiedere il report. La download_url è monouso e scade in 5 minuti: richiedila e scarica il file subito.