Import de feuilles de temps
Le jeudi, c'est la course : les heures de la semaine sont dans l'application de pointage des chantiers, et il faut les ressaisir une par une dans Acomba avant de lancer la paie. Une ligne oubliée, c'est un employé mal payé ; une ligne saisie deux fois, c'est une paie à corriger.Dans cette recette, nous allons importer ces heures automatiquement : l'export de votre outil de pointage devient des lignes de temps Acomba, vérifiées avant d'être écrites, sans doublon même si l'import est relancé, et prêtes pour la paie.Ce que vous allez apprendrefaire correspondre vos employés, fonctions et chantiers à ceux d'Acomba ;
valider un lot d'heures à blanc, puis l'écrire en une fois, sans jamais créer de doublon ;
vérifier les heures importées avant la paie et corriger une ligne ;
éviter les pièges d'Acomba : la période déduite de la date, les codes de paie, les fiches ouvertes.
une clé API avec accès en écriture ;
le module Paie actif dans votre dossier Acomba ;
un export de votre outil de pointage avec, pour chaque ligne : numéro d'employé Acomba, numéro de fonction, date, heures, chantier et type d'heures ;
idéalement, un dossier de test : les lignes de temps alimentent la vraie paie.
Avant d'importer quoi que ce soit, voyons ce qu'Acomba attend. Il n'y a pas de « feuille » par employé : chaque ligne de temps porte un employé, une de ses fonctions (le métier et le département, qui donnent le taux horaire), un code de paie (régulier, temps et demi…), un chantier facultatif, une date et des heures. Acomba déduit lui-même la période de paie de la date. Les lignes restent « non affectées » jusqu'à ce que la paie les intègre, dans Acomba.| Étape | Dans l'API |
|---|
| Employé et ses fonctions | GET /api/payroll/employees/{code}, puis GET /api/payroll/employees/by-id/{id}/functions |
| Codes de paie | GET /api/payroll/pay-codes?section=income |
| Dates de la période | GET /api/payroll/departments/{code} et GET /api/payroll/calendar?department_code=… |
| Validation et écriture du lot | POST /api/payroll/time-sheets/write-batches |
| Vérification avant la paie | GET /api/payroll/time-sheets?assignment=unassigned |
Étape 1 : préparer les correspondances#
Commençons par traduire votre export dans la langue d'Acomba. Pour chaque employé de l'export, lisez sa fiche par son numéro, puis ses fonctions : function_cp est l'identifiant à donner à chaque ligne, et reference le numéro de fonction affiché dans Acomba.Réponse 200 (extrait des fonctions)
Codes de paie : GET /api/payroll/pay-codes?section=income donne chaque code avec sa description. Dans un dossier standard, 102 = salaire régulier horaire, 103 = temps et demi, 104 = temps double ; vérifiez-le dans le vôtre.
Le taux vient de la fonction : une ligne ne porte que des heures.
Chantier : project_number doit être un projet existant d'Acomba (GET /api/customers/projects?project_type=0).
Étape 2 : trouver la période de paie#
Assurons-nous ensuite que les heures tombent dans la bonne paie. Le département donne la prochaine période, et le calendrier ses dates.La prochaine paie couvre donc du 2 au 8 août. Acomba range chaque ligne dans une période d'après sa date : une ligne datée hors de cet intervalle ira dans une autre paie.
Étape 3 : valider le lot à blanc#
Les correspondances sont prêtes ; vérifions le lot avant d'écrire quoi que ce soit. Avec "dry_run": true, l'API contrôle chaque ligne (employé, fonction, chantier, heures) sans rien écrire.status: "blocked" : au moins une ligne serait refusée. Corrigez l'export (ici, le chantier CH-0099 n'existe pas dans Acomba), puis validez de nouveau.
Un essai à blanc ne consomme pas la clé : vous pouvez le relancer autant de fois que nécessaire.
| Code d'erreur | Cause | Que faire |
|---|
employee_not_found, employee_code_mismatch | Numéro d'employé inconnu ou différent de employee_cp | Relire l'employé (étape 1) |
function_not_owned, function_inactive | Fonction d'un autre employé, ou inactive | Prendre une fonction active de l'employé |
project_not_found | Chantier absent d'Acomba | Créer le projet dans Acomba, ou corriger le numéro |
hours_out_of_range | Plus de 168 heures sur une ligne | Corriger l'export |
Étape 4 : écrire le lot#
Tout est vert ? Écrivons. Envoyez le même corps avec "dry_run": false. La clé d'idempotence identifie cet export : si l'import est interrompu ou relancé, la même clé ne réécrit jamais une ligne déjà écrite.Relancé avec la même clé et le même contenu, le lot répond "mode": "replay" et chaque ligne "already_written" : rien n'est écrit deux fois.
La même clé avec un contenu différent est refusée (409 idempotency_conflict) : un nouvel export prend une nouvelle clé.
Conservez ts_card_pos (l'id de la ligne) et ts_unique : Acomba réutilise les identifiants des lignes supprimées.
500 lignes au plus par lot ; au-delà, découpez l'export en plusieurs lots.
Étape 5 : vérifier avant la paie#
Les heures sont dans Acomba ; vérifions-les avant de lancer la paie. Les lignes importées sont « non affectées » tant que la paie ne les a pas intégrées.Une ligne à corriger ? Modifiez-la en donnant son unique, qui garantit que c'est bien la ligne attendue :409 time_sheet_identity_mismatch : la ligne n'est plus celle attendue ; relisez la liste.
Une ligne déjà intégrée à une paie ou transférée à la comptabilité ne se modifie ni ne se supprime (409 time_sheet_not_modifiable ou time_sheet_not_deletable, avec la raison).
Le script complet#
Assemblons le tout : ce script lit l'export CSV, prépare les correspondances, valide le lot à blanc, puis l'écrit et affiche les heures par employé.Exemple de sortie, au premier import puis à une relance :Lot pointage-2026-S32 (new) : 2 écrites, 0 déjà écrites, 0 en échec
employé 1045 : 10.50 h
Lot pointage-2026-S32 (replay) : 0 écrites, 2 déjà écrites, 0 en échec
employé 1045 : 10.50 h
Bon à savoir#
Une clé par export. Après avoir supprimé des lignes d'un lot, ne relancez pas la même clé : les lignes supprimées ressortent readback_missing et ne sont pas réécrites. Corrigez l'export et prenez une nouvelle clé (pointage-2026-S32-b).
Annuler un import entier : DELETE /api/payroll/time-sheets/write-batches/pointage-2026-S32?live_cards=delete supprime toutes les lignes du lot encore présentes et oublie la clé. Une ligne déjà intégrée à une paie bloque l'annulation.
La période vient de la date. Acomba range chaque ligne d'après sa date ; vérifiez que l'export couvre bien la période de la prochaine paie (étape 2).
Code de paie invalide : Acomba le remplace en silence par le salaire régulier (102). L'API le signale par un avertissement readback_mismatch sur la ligne ; lisez les warnings du lot.
Fiches ouvertes dans Acomba : si quelqu'un a ouvert les feuilles de temps d'un employé dans Acomba, ses lignes sont refusées (reserve_refused). Fermez l'écran, puis relancez la même clé : seules les lignes manquantes sont écrites.
Affichage des heures dans la démo d'Acomba : la version de démonstration arrondit l'affichage (6,5 h s'affiche 6:00). La valeur enregistrée est juste ; vérifiez par l'API.
Un lot à la fois : Acomba traite une écriture à la fois ; n'envoyez pas plusieurs lots en parallèle.
Et voilà#
Vos heures de chantier arrivent maintenant dans Acomba sans ressaisie : validées à blanc, écrites en un lot qu'on peut relancer sans risque, et vérifiées avant la paie. Vous savez faire correspondre employés et fonctions, trouver la période de paie, et corriger une ligne sans toucher à la mauvaise. Modified at 2026-10-11 15:50:15
