Paie et gestion sociale

Objectif : alimenter votre logiciel de paie avec les heures effectives, les absences et les soldes de congés d’une période, sans export manuel.

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

Les trois ressources clés :

• GET /v1/work-summaries — la ressource paie : agrégats consolidés de temps de travail par salarié et par période.
• GET /v1/absences — arrêts, congés et déductions de la période.
• GET /v1/vacation-balances — soldes de congés pour la clôture.

Work summaries : les heures de la période

work-summaries renvoie une ligne par salarié × période avec les agrégats déjà calculés (pas les événements de pointage). Filtrez par period=day|month et une plage from/to (≤ 1 an).

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

Champs utiles pour la paie :

Absences de la période

Croisez les absences approuvées qui chevauchent la période de paie pour appliquer les arrêts et les déductions :

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

Chaque absence porte un type sous la forme { key, label } (la key est stable : vacation, sick_leave, ou des types personnalisés propres à votre entreprise) et un days_count. Utilisez toujours la key dans votre logique.

Soldes de congés

Pour la clôture annuelle ou les provisions, consultez les soldes par salarié et par année :

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

Flux de clôture mensuelle

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