Lön och lönebyrå

Mål: mata ditt lönesystem med arbetade timmar, frånvaro och semestersaldon för en period, utan manuella exporter.

Scopes som krävs: org:fichajes:read, org:ausencias:read, org:saldos:read.

De tre nyckelresurserna:

GET /v1/work-summaries — löneresursen: stängda aggregat av arbetstid per medarbetare och period.
GET /v1/absences — sjukfrånvaro, semester och avdrag under perioden.
GET /v1/vacation-balances — semestersaldon för avslutet.

Work summaries: timmar för perioden

work-summaries returnerar en rad per medarbetare × period med aggregaten färdigberäknade (inte stämplingshändelser). Filtrera med period=day|month och ett intervall from/to (≤ 1 år).


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

Fält som är relevanta för lön:

Fält	Användning
`worked_minutes`	Faktiskt arbetad tid.
`night_minutes`	Minuter under nattarbete (OB-tillägg).
`overtime_minutes`	Övertid under perioden.
`expected_minutes`	Förväntad arbetstid enligt avtal.
`balance_minutes`	Differensen arbetat − förväntat.
`banked_hours_balance_minutes`	Saldo i timbanken.
`absences_minutes`	Frånvarominuter under perioden.

Månadsaggregat kan serveras från konsoliderade snapshots. Om ditt avslut beror på data från innevarande dag, räkna med en möjlig konsolideringsfördröjning och stäng mot redan kompletta perioder.

Frånvaro under perioden

Stäm av den godkända frånvaro som överlappar löneperioden för att tillämpa sjukfrånvaro och avdrag:


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

Varje frånvaro har type som { key, label } (key är stabil: vacation, sick_leave, eller ditt företags anpassade typer) och days_count. Använd alltid key i din logik.

Semestersaldon

För årsavslutet eller för avsättningar, hämta saldon per medarbetare och år:


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

Flöde för månadsavslut

Lista periodens aktiva medarbetare

GET /v1/employees?status=active (paginera med cursor om ni är fler än 100).

Hämta månadens work-summaries

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

Stäm av den godkända frånvaron

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

(Valfritt) Generera den lagstadgade tidregistreringen

För arbetsmiljöinspektionen, begär rapporten 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" } }'

Format: csv eller xlsx (xlsx endast för check_ins_export). Du får 202 { "id": "…", "status": "processing" }. Polla GET /v1/reports/{id} tills status=completed; då innehåller svaret download_url, en temporär signerad URL (TTL 5 min, engångsbruk). Signaturen är credentialen: ladda ner filen från den URL:en utan Authorization-header:


# 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

Scopet org:informes:read är obligatoriskt för att begära rapporten. download_url är för engångsbruk och går ut efter 5 minuter: begär den och ladda ner direkt.