Créez chaque absence et chaque variable de paie avec POST, et modifiez-la avec PUT. Si un élément
est refusé, la réponse l’indique immédiatement, avec le motif du refus.
- Absences : lister, consulter, créer, modifier, accepter, refuser ou annuler.
- Variables de paie : lister, consulter, créer, modifier ou changer le statut, supprimer.
Les imports en lot sont des routes historiques.
Créer une absence
curl https://api.puncto.fr/public/v1/absences \
-H "Authorization: Bearer $PUNCTO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"foreignErpId": "absence-123",
"contractMatching": { "type": "BY_PUNCTO_COLLABORATOR_ID", "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY" },
"type": "RTT",
"startDate": "2026-10-05",
"endDate": "2026-10-05",
"onlyHalfDayAtStart": false,
"onlyHalfDayAtEnd": false
}'La route renvoie 201 avec l’absence, qui est validée directement. En cas d’erreur, elle
renvoie :
400si l’absence est refusée (chevauchement avec une autre absence, solde insuffisant, durée légale d’un événement familial dépassée) ;404si le collaborateur ou le contrat est introuvable ;409si leforeignErpIdest déjà utilisé.
Bon à savoir :
contractMatchingdésigne le collaborateur (voir Identifier un collaborateur). Puncto retient son contrat actif àeventDate, à défaut àstartDate.- Un congé payé est réparti entre
PTO_N,PTO_N-1etPTO_N-2selon les soldes. S’il est réparti sur plusieurs compteurs, il donne plusieurs absences, et la réponse ne renvoie que la première. - Les arrêts de travail et les congés parentaux se saisissent dans Puncto.
- Pour joindre un justificatif, envoyez la requête en
multipart/form-dataavec un fichierproofFile.
Modifier ou annuler une absence
PUT /public/v1/absences/{absenceId} prend soit status (par exemple
{ "status": "canceled" }), soit tous les détails de l’absence. Des détails partiels sont
refusés.
- Les transitions possibles sont
pendingversvalidatedourejected, etvalidatedverscanceled. - Une absence ne peut pas être supprimée, seulement annulée.
- Un congé payé réparti sur plusieurs compteurs se modifie absence par absence.
- Pour un arrêt de travail ou un congé parental, seul le statut peut être modifié.
Créer une variable de paie
curl https://api.puncto.fr/public/v1/payroll-variables \
-H "Authorization: Bearer $PUNCTO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"foreignErpId": "teletravail-2026-10-salarie-123",
"year": 2026,
"month": 10,
"contractMatching": { "type": "BY_PUNCTO_COLLABORATOR_ID", "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY" },
"data": { "type": "REMOTE_WORK_DAY", "name": "Jours de télétravail", "days": 8.5 }
}'La route renvoie 201 avec la variable. Si status est absent, elle est VALIDATED. Si year et
month sont absents, elle est rattachée au prochain mois de paie ouvert.
| Code | Cause |
|---|---|
400 |
Variable refusée par une règle de saisie (voir plus bas), ou mois clôturé qu’aucune paie ouverte ne peut régulariser |
404 |
Collaborateur ou contrat introuvable |
409 |
foreignErpId déjà utilisé par une variable de paie ou une variable récurrente |
Types de variables
data.type |
Contenu |
|---|---|
PRIME |
prime brute, avec son primeType : cooptation, business, autre prime brute ou indemnité d’occupation du domicile |
OVERTIME |
heures supplémentaires, avec le jour où elles ont été faites |
SALARY_DEDUCTION |
retenue sur le net ou sur le brut |
IN_KIND_BENEFIT |
avantage en nature ponctuel |
TAX_FREE_INDEMNITY |
note de frais, transport public ou personnel, abonnement sport, autre |
REMOTE_WORK_DAY |
jours de télétravail indemnisés du mois |
MEAL_ALLOWANCE_ADJUSTMENT |
repas à ajouter ou retirer aux primes de panier |
MEAL_VOUCHER_ADJUSTMENT |
titres restaurant à ajouter ou retirer |
SALARY_ADVANCE |
acompte versé pendant le mois, déduit du virement |
Les quatre derniers types ont un libellé fixe, à envoyer tel quel dans data.name :
Jours de télétravail, Ajustement paniers, Ajustement titres restaurant et
Acompte sur salaire. Le format de chaque type est détaillé dans la
référence.
Les indemnités de fin de contrat (clôture du contrat), les primes collectives (page Primes) et les abonnements annuels de transport (variables récurrentes) ne se créent pas ici.
Désigner le contrat
contractMatching désigne le collaborateur, ou directement le contrat quand le collaborateur en a
deux dans le mois :
{
"contractMatching": { "type": "BY_PUNCTO_CONTRACT_ID", "value": "cont_01JB7Q6ZC8V3K9N2M4R5T7W8XY" }
}Une variable ne peut pas changer de contrat. Pour la rattacher à un autre contrat, supprimez-la puis recréez-la.
Variables refusées
Une variable est refusée (400) quand :
- le mois de paie est hors du contrat ;
- des heures supplémentaires visent un contrat au forfait jours ou à temps partiel ;
- l’établissement ne verse pas l’indemnité concernée (télétravail par jour, type de panier, titres restaurant, transport personnel), ou l’entreprise ne prend pas en charge les abonnements sport ;
- un décompte de jours de télétravail existe déjà pour ce contrat et ce mois ;
- un acompte n’est pas
VALIDATED, est versé hors du mois de paie, ou tombe sur un mois clôturé ; - un justificatif manque pour une indemnité non soumise autre qu’une note de frais ou un transport public.
Repas d’affaires
Une note de frais de repas (expenseType MEALS) doit indiquer ses participants, dont les titres
restaurant du mois sont réduits. Désignez-les avec le même format que contractMatching. Leur contrat
doit être en vigueur à la date de la dépense.
{
"businessMealParticipants": [
{ "type": "BY_PUNCTO_COLLABORATOR_ID", "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XZ" },
{ "type": "BY_PUNCTO_COLLABORATOR_ID", "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8Y0" }
]
}Lors d’une modification, si businessMealParticipants est absent, les participants sont conservés
et suivent la note si elle change de mois. Sur un mois clôturé, la réduction devient une saisie
tardive sur la paie de chaque participant.
Indemnités kilométriques
Envoyez le trajet dans data.kilometric. amountTotal et amountReimbursed doivent correspondre au
montant du barème fiscal de l’année de la dépense pour ce trajet.
{
"type": "TAX_FREE_INDEMNITY",
"indemnityType": "EXPENSE_NOTE",
"expenseType": "KILOMETRIC_INDEMNITIES",
"name": "Déplacement client",
"expenseDate": "2026-10-06",
"amountTotal": 52.9,
"amountReimbursed": 52.9,
"vatAmounts": { "vatAmount2_1": 0, "vatAmount5_5": 0, "vatAmount10": 0, "vatAmount20": 0 },
"kilometric": {
"vehicleCategory": "CAR",
"energyType": "THERMIC_HYDROGEN_HYBRID",
"fiscalPower": 3,
"departureAddress": "Paris",
"arrivalAddress": "Orléans",
"distance": 100,
"isRoundTrip": false
}
}Joindre des justificatifs
Envoyez la requête en multipart/form-data, avec les fichiers dans proofFiles[i] :
curl https://api.puncto.fr/public/v1/payroll-variables \
-H "Authorization: Bearer $PUNCTO_TOKEN" \
-F "foreignErpId=ndf-2026-10-001" \
-F "year=2026" \
-F "month=10" \
-F "contractMatching[type]=BY_PUNCTO_COLLABORATOR_ID" \
-F "contractMatching[value]=coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY" \
-F "businessMealParticipants[0][type]=BY_PUNCTO_COLLABORATOR_ID" \
-F "businessMealParticipants[0][value]=coll_01JB7Q6ZC8V3K9N2M4R5T7W8XZ" \
-F "data[type]=TAX_FREE_INDEMNITY" \
-F "data[indemnityType]=EXPENSE_NOTE" \
-F "data[name]=Déjeuner client" \
-F "data[amountTotal]=48" \
-F "data[amountReimbursed]=48" \
-F "data[expenseDate]=2026-10-03" \
-F "data[expenseType]=MEALS" \
-F "data[vatAmounts][vatAmount2_1]=0" \
-F "data[vatAmounts][vatAmount5_5]=0" \
-F "data[vatAmounts][vatAmount10]=4.36" \
-F "data[vatAmounts][vatAmount20]=0" \
-F "proofFiles[0]=@facture.pdf"Lors d’une modification, les nouveaux fichiers s’ajoutent à ceux déjà enregistrés (10 au plus).
Indiquez dans proofFileIdsToDelete ceux à supprimer.
Relire et corriger les variables de paie
La liste renvoie toutes les variables, y compris celles saisies dans Puncto (origin), avec leurs
justificatifs. Vous pouvez filtrer par mois, type, statut, contrat, collaborateur ou foreignErpId.
curl "https://api.puncto.fr/public/v1/payroll-variables?year=2026&month=10&status[]=PENDING" \
-H "Authorization: Bearer $PUNCTO_TOKEN"PUT et DELETE prennent l’identifiant Puncto de la variable. Si vous n’avez que votre
foreignErpId, retrouvez-le avec GET /public/v1/payroll-variables/ndf-2026-10-001?matchingBy=BY_FOREIGN_ERP_ID.
PUT prend soit data, qui remplace le contenu et le mois de paie, soit status seul. Pour
valider une note de frais en attente :
curl -X PUT https://api.puncto.fr/public/v1/payroll-variables/pvar_01JB7Q6ZC8V3K9N2M4R5T7W8XY \
-H "Authorization: Bearer $PUNCTO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "status": "VALIDATED" }'Pour supprimer une variable retirée de votre système (204) :
curl -X DELETE https://api.puncto.fr/public/v1/payroll-variables/pvar_01JB7Q6ZC8V3K9N2M4R5T7W8XY \
-H "Authorization: Bearer $PUNCTO_TOKEN"Bon à savoir (refus en 400) :
- Les heures d’une feuille de temps, l’intéressement, la prime de vacances et les chèques-vacances de la page Primes ne se modifient pas, ne se suppriment pas et ne changent pas de statut. La PPV de la page Primes n’est pas concernée par cette restriction.
- L’indemnité de fin de contrat du mois du solde de tout compte se corrige depuis la clôture du contrat.
- Une astreinte se modifie avec
PUT /public/v1/on-call-periods/{onCallPeriodId}. - Le statut d’un acompte ne peut pas changer, et un acompte d’un mois clôturé ne peut pas être supprimé.
- Les variables récurrentes ne figurent pas dans cette liste, car elles ont leurs propres routes.
Effets sur la paie
- Seules les absences
validatedet les variablesVALIDATEDentrent dans les bulletins. Les bulletins en brouillon concernés sont recalculés. - Sur un mois de paie clôturé, ou dont le bulletin est validé, l’écriture est une saisie
tardive, régularisée sur la prochaine paie ouverte. Elle est refusée si aucune paie ouverte ne
peut la porter. Le champ
lockStated’une variable permet de le savoir avant d’écrire.
Imports en lot (routes historiques)
- Idempotence : un
foreignErpIdexistant met l’élément à jour, sinon il est créé. Avec"disableIdempotency": true, il devient facultatif et chaque élément est créé. - Bilan :
200aveccreatedCount,modifiedCount,errors(etunchangedCountpour les variables). Un élément introuvable ou refusé est ignoré et listé danserrors: vérifiez toujourserrors. - Transaction : en cas d’erreur inattendue, la route renvoie
400et rien n’est enregistré. - Absences : ni chevauchement, ni solde, ni durée légale ne sont vérifiés, et aucun arrêt de travail n’est créé pour la DSN.
- Variables : une variable renvoyée à l’identique n’est pas réécrite ; un
foreignErpIden double dans le lot est refusé. Le justificatif s’envoie dansvariables[i][proofFile], et sans fichier, le justificatif déjà enregistré est retiré. Les abonnements annuels de transport, les variables récurrentes et les variables gérées ailleurs (astreintes, feuilles de temps, page Primes, fin de contrat) sont refusés.