---
title: "Absences et variables de paie"
description: "Créer, modifier et relire les absences et les variables de paie une à une."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.puncto.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Absences et variables de paie

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](/reference/absences/list),
  [consulter](/reference/absences/retrieve), [créer](/reference/absences/create),
  [modifier, accepter, refuser ou annuler](/reference/absences/update).
- Variables de paie : [lister](/reference/payroll-variables/list),
  [consulter](/reference/payroll-variables/retrieve),
  [créer](/reference/payroll-variables/create),
  [modifier ou changer le statut](/reference/payroll-variables/update),
  [supprimer](/reference/payroll-variables/delete).

Les imports en lot sont des [routes historiques](#imports-en-lot-routes-historiques).

## Créer une absence

```bash
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](/developpeurs/guides/correspondance)). 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

```bash
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](/reference/payroll-variables/create).

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](/developpeurs/guides/astreintes#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 :

```json
{
  "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.

```json
{
  "businessMealParticipants": [
    { "type": "BY_PUNCTO_COLLABORATOR_ID", "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XZ" },
    { "type": "BY_PUNCTO_COLLABORATOR_ID", "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8Y0" }
  ]
}
```

> **Caution**
>
> La réduction s’applique dès que les participants sont enregistrés, **quel que soit le statut de
> la note**, y compris en attente ou refusée. Envoyez-les avec une note `VALIDATED`, et retirez-les
> (`"businessMealParticipants": []`) d’une note que vous refusez. Si vous supprimez la note, ils sont
> aussi retirés.

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.

```json
{
  "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]` :

```bash
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`.

```bash
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 :

```bash
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`) :

```bash
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}`](/reference/on-call-periods/update).
- 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](/developpeurs/guides/astreintes#variables-récurrentes).

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

> **Caution**
>
> [Importer des absences](/reference/absences/import) et
> [importer des variables de paie](/reference/payroll-variables/import) restent
> ouvertes aux intégrations existantes. Ne les utilisez pas pour une nouvelle intégration.

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

Source: https://docs.puncto.fr/developpeurs/guides/imports/index.mdx
