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 apprendre

faire 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.

Avant de commencer

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.

Comment Acomba reçoit des heures

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.

cURL

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.

cURL

Réponses 200 (extraits)

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.

cURL

Réponse 200

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.

cURL

Réponse 200 (extrait)

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.

cURL

Réponse 200 (extrait)

Une ligne à corriger ? Modifiez-la en donnant son unique, qui garantit que c'est bien la ligne attendue :

cURL

Réponse 200 (extrait)

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).

La paie se lance ensuite dans Acomba, comme d'habitude.

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é.

Python

JavaScript (Node.js)

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.

Codes d'erreur : voir Codes d'erreur pour savoir quand réessayer.

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.

Pour aller plus loin

Synchronisation CRM : le même principe de correspondances, côté clients.

Bonnes pratiques d'intégration : reprises, idempotence et appels en file.

Comment Acomba reçoit des heures#

Étape 1 : préparer les correspondances#

Étape 2 : trouver la période de paie#

Étape 3 : valider le lot à blanc#

Étape 4 : écrire le lot#

Étape 5 : vérifier avant la paie#

Le script complet#

Bon à savoir#

Et voilà#

Comment Acomba reçoit des heures

Étape 1 : préparer les correspondances

Étape 2 : trouver la période de paie

Étape 3 : valider le lot à blanc

Étape 4 : écrire le lot

Étape 5 : vérifier avant la paie

Le script complet

Bon à savoir

Et voilà