Vacances et banques d’heures en libre-service

« Combien me reste-t-il de vacances ? » « Est-ce que j'ai encore des heures en banque ? » Ces questions arrivent au bureau chaque semaine, par téléphone ou texto, et chacune demande d'ouvrir Acomba, de trouver l'employé et de lire ses banques. Les demandes de congé, elles, passent par un papier ou un courriel, et quelqu'un les ressaisit.

Dans cette recette, nous allons donner ces réponses en libre-service : un portail (ou un robot de messagerie) qui affiche à chaque employé ses soldes de banques RH, et qui enregistre sa demande de congé directement dans Acomba, après avoir vérifié que le solde le permet.

Ce que vous allez apprendre

ce que sont les banques RH d'Acomba et comment se calcule leur solde ;

lire les soldes d'un employé, banque par banque ;

enregistrer une demande de congé comme un déboursé dans la banque ;

laisser l'API refuser une demande qui rendrait le solde négatif.

Avant de commencer

une clé API en lecture pour les soldes, en écriture pour les demandes de congé ;

le module Paie actif, et vos banques RH configurées dans Acomba (vacances, congés, heures accumulées) ;

l'identification de l'employé dans votre portail, reliée à son numéro d'employé d'Acomba ;

un dossier de test pour le premier essai.

Les banques RH d'Acomba

Avant de lire les soldes, voyons ce qu'ils représentent. Une banque RH est un compteur : vacances, congés de maladie, heures accumulées, montant de primes. Chaque banque a une unité (heures, jours, montant ou quantité), s'applique à l'employé ou à chacune de ses fonctions, et peut interdire le solde négatif.

Le solde se construit avec des mouvements, enregistrés comme des lignes de temps : la provision (entrée), le déboursé (sortie) et l'ajustement. Le solde, c'est le total des entrées moins le total des sorties.

Étape 1 : afficher les soldes de l'employé

Commençons par la question la plus fréquente. Les soldes d'un employé se lisent en un appel, une ligne par banque (et par fonction, pour une banque qui s'applique aux fonctions).

cURL

Réponse 200 (extrait)

totals.balance : le solde à afficher, dans l'unité de la banque (format_label).

credits et debits : le total acquis et le total utilisé, pour expliquer le solde.

function : la fonction concernée quand la banque s'applique aux fonctions (applicable_to: 2) ; sinon, id vaut 0.

La liste des banques et leurs règles (unité, solde négatif permis, cumul par lot, expiration) se lit avec GET /api/payroll/hr-banks?brief=false.

Étape 2 : enregistrer une demande de congé

L'employé a 4,5 heures de vacances et en demande 4 pour vendredi. Une demande approuvée devient un déboursé dans la banque, écrit par le lot de lignes de temps. Validons-la d'abord à blanc.

cURL

Réponse 200 (extrait)

Le lot est valide : renvoyez-le sans dry_run pour l'écrire. La clé d'idempotence (idempotency_key) protège contre le double clic : un lot déjà écrit avec la même clé est rejoué sans être écrit une seconde fois, et sa validation à blanc l'annonce ("mode": "replay", lignes already_written) plutôt que de la revalider. La valeur est toujours positive ; c'est le mouvement (disbursement) qui en fait une sortie.

Étape 3 : laisser l'API refuser un solde négatif

Une semaine plus tard, il ne reste que 0,5 heure, et l'employé demande 2 heures. Si la banque interdit le solde négatif, la validation à blanc répond par un refus explicite :

{
  "dry_run": true, "status": "blocked",
  "lines": [ { "ok": false, "errors": [
    { "code": "negative_balance_not_allowed", "field": "value",
      "message": "La banque RH 10 interdit un solde négatif : solde 0.5 − 2.0 = -1.5",
      "balance_before": 0.5, "balance_after": -1.5 } ] } ]
}

Le contrôle vient de l'API : Acomba lui-même ne l'applique pas aux mouvements écrits par le SDK. Votre portail peut afficher le message tel quel, ou proposer de réduire la demande.

Le script complet

Assemblons le service : ce script affiche les soldes d'un employé, enregistre une demande de congé après validation à blanc, puis réaffiche les soldes.

Python

JavaScript (Node.js)

Exemple de sortie :

Soldes de Lavoie Benoît :
  Vacances — Plâtrier 3e : 4.5 heure(s) (acquis 8, utilisés 3.5)
  Allocation d'outils : 100 montant(s) (acquis 100, utilisés 0)
Demande enregistrée (completed, 1 ligne)
Soldes de Lavoie Benoît :
  Vacances — Plâtrier 3e : 0.5 heure(s) (acquis 8, utilisés 7.5)
  Allocation d'outils : 100 montant(s) (acquis 100, utilisés 0)

Bon à savoir

Approuver avant d'écrire. Le script écrit la demande dès qu'elle est valide ; dans un vrai portail, faites-la approuver par un responsable avant l'écriture, et gardez la validation à blanc pour informer l'employé tout de suite.

Un congé annulé. Supprimez la ligne de temps du déboursé (DELETE /api/payroll/time-sheets/by-id/{id}) tant qu'elle n'est pas intégrée à une paie : le solde se recalcule.

Données personnelles. Un employé ne doit voir que ses propres soldes : votre portail fait le lien entre l'utilisateur connecté et son numéro d'employé, jamais l'inverse.

Les provisions automatiques (cumul par lot, expiration) sont faites par Acomba selon la configuration de la banque ; votre portail n'a qu'à les lire.

Codes d'erreur : voir Codes d'erreur.

Et voilà

Vos employés ont maintenant leurs réponses sans appeler le bureau : leurs soldes de vacances et de banques d'heures affichés en libre-service, leurs demandes de congé enregistrées directement dans Acomba, et celles qui dépasseraient le solde refusées avec une explication claire. Vous savez aussi comment Acomba calcule un solde, et pourquoi le contrôle du solde négatif se fait dans l'API.

Pour aller plus loin

Import de feuilles de temps : les heures travaillées dans le même lot que les mouvements de banque.

Vérifier une paie avant de la fermer : les congés payés dans la paie de la semaine.

Embaucher un travailleur de la construction : ouvrir ses banques dès l'embauche.

Vacances et banques d’heures en libre-service

Les banques RH d'Acomba#

Étape 1 : afficher les soldes de l'employé#

Étape 2 : enregistrer une demande de congé#

Étape 3 : laisser l'API refuser un solde négatif#

Le script complet#

Bon à savoir#