Skip to content

Absences et variables de paie

Créer, modifier et relire les absences et les variables de paie une à une.

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.

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 :

  • 400 si l’absence est refusée (chevauchement avec une autre absence, solde insuffisant, durée légale d’un événement familial dépassée) ;
  • 404 si le collaborateur ou le contrat est introuvable ;
  • 409 si le foreignErpId est déjà utilisé.

Bon à savoir :

  • contractMatching dé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-1 et PTO_N-2 selon 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-data avec un fichier proofFile.

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 pending vers validated ou rejected, et validated vers canceled.
  • 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 validated et les variables VALIDATED entrent 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 lockState d’une variable permet de le savoir avant d’écrire.

Imports en lot (routes historiques)

  • Idempotence : un foreignErpId existant met l’élément à jour, sinon il est créé. Avec "disableIdempotency": true, il devient facultatif et chaque élément est créé.
  • Bilan : 200 avec createdCount, modifiedCount, errors (et unchangedCount pour les variables). Un élément introuvable ou refusé est ignoré et listé dans errors : vérifiez toujours errors.
  • Transaction : en cas d’erreur inattendue, la route renvoie 400 et 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 foreignErpId en double dans le lot est refusé. Le justificatif s’envoie dans variables[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.

Type to search…

↑↓ navigate↵ selectEsc close