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 :

Champ	Usage
`worked_minutes`	Temps de travail effectif.
`night_minutes`	Minutes en horaire de nuit (majorations).
`overtime_minutes`	Heures supplémentaires de la période.
`expected_minutes`	Durée théorique selon le contrat.
`balance_minutes`	Écart travaillé − attendu.
`banked_hours_balance_minutes`	Solde du compteur d’heures.
`absences_minutes`	Minutes d’absence sur la période.

work-summaries et vacation-balances ignorent updated_since (accepté par compatibilité, obsolète, retrait le 27/08/2027) : pour rafraîchir une clôture, redemandez la plage (from/to, year) au lieu de tenter un delta.

Les agrégats mensuels peuvent être servis depuis des snapshots consolidés. Si votre clôture dépend des données du jour en cours, tenez compte d’une possible latence de consolidation et clôturez sur des périodes déjà complètes.

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

Listez les salariés actifs de la période

GET /v1/employees?status=active (paginez avec cursor au-delà de 100).

Si votre intégration crée aussi des salariés, POST /v1/employees peut répondre 402 billing_required : l’abonnement est actif mais le plan n’a plus de siège disponible. Faites évoluer le plan depuis le dashboard ; réessayer sans rien changer renvoie le même 402. L’e-mail du salarié est unique par entreprise, pas globalement.

Téléchargez les work-summaries du mois

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

Croisez les absences approuvées

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

(Optionnel) Générez le registre légal du temps de travail

Pour l’inspection du travail, demandez le rapport 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" } }'

Formats : csv ou xlsx (xlsx uniquement pour check_ins_export). Vous recevez 202 { "id": "…", "status": "processing" }. Faites du polling sur GET /v1/reports/{id} jusqu’à status=completed ; la réponse inclut alors download_url, une URL signée temporaire (TTL 5 min, usage unique). La signature fait office d’identifiant : téléchargez le fichier depuis cette URL sans 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

Le scope org:informes:read est obligatoire pour demander le rapport. La download_url est à usage unique et expire au bout de 5 minutes : demandez-la et téléchargez le fichier dans la foulée.