---
title: "Astreintes et variables récurrentes"
description: "Saisir les périodes d’astreinte et les éléments de paie versés chaque mois."
---

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

# Astreintes et variables récurrentes

Deux familles de routes complètent les [variables de paie](/developpeurs/guides/imports) :

- **astreintes** : [lire le barème](/reference/on-call-types/list),
  [lister](/reference/on-call-periods/list),
  [créer](/reference/on-call-periods/create),
  [modifier](/reference/on-call-periods/update),
  [supprimer](/reference/on-call-periods/delete) ;
- **variables récurrentes**, versées chaque mois sans saisie mensuelle :
  [lister](/reference/recurring-variables/list),
  [créer](/reference/recurring-variables/create),
  [valider, refuser ou arrêter](/reference/recurring-variables/update),
  [supprimer](/reference/recurring-variables/delete).

Les variables de paie, les périodes d’astreinte et les variables récurrentes partagent les mêmes
`foreignErpId` dans l’entreprise. Un identifiant déjà pris par un élément d’une autre nature est
refusé. Pour le réutiliser, supprimez d’abord l’ancien élément.

## Astreintes

Le module des astreintes doit être activé pour l’entreprise, sinon le barème et les écritures
renvoient `400`. Les périodes déjà saisies restent lisibles.

### Lire le barème

Le barème se gère dans Puncto, sur la page **Équipe › Astreintes**. Chaque type a sa contrepartie,
un montant brut par période (`PERIOD`, par exemple une nuit ou un week-end) ou par heure d’astreinte
(`HOUR`).

```bash
curl https://api.puncto.fr/public/v1/on-call-types \
  -H "Authorization: Bearer $PUNCTO_TOKEN"
```

```json
{
  "data": [
    {
      "onCallTypeId": "octy_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "label": "Week-end",
      "compensation": { "mode": "FIXED_PER_UNIT", "unit": "PERIOD", "amount": 150 },
      "isActive": true,
      "isUsed": true
    }
  ],
  "meta": { "total": 1, "page": 1, "perPage": 50, "currentPage": 1, "firstPage": 1, "lastPage": 1 }
}
```

### Créer une période

Les dates sont en heure légale de Paris, sans fuseau, au format `YYYY-MM-DDTHH:mm`. `interventions`
est obligatoire. Envoyez un tableau vide s’il n’y en a aucune.

```bash
curl https://api.puncto.fr/public/v1/on-call-periods \
  -H "Authorization: Bearer $PUNCTO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "foreignErpId": "astreinte-2026-11-13-salarie-123",
    "contractMatching": { "type": "BY_PUNCTO_COLLABORATOR_ID", "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY" },
    "onCallTypeId": "octy_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
    "start": "2026-11-13T18:00",
    "end": "2026-11-16T08:00",
    "interventions": [
      { "start": "2026-11-14T10:00", "end": "2026-11-14T12:00", "location": "REMOTE" }
    ]
  }'
```

La période devient une variable de paie `ON_CALL` validée, rattachée au **mois de paie de son
début**.
Son libellé et sa contrepartie sont copiés du type au moment de l’écriture.

- **Unités** : `periodCount` (1 par défaut) pour un type à la période ; la durée de la période,
  changements d’heure compris, pour un type à l’heure.
- **Contrat** : celui du collaborateur en vigueur au début de la période (ou à `eventDate`). Avec
  `BY_PUNCTO_CONTRACT_ID`, `value` est l’identifiant du contrat.
- **Interventions** : sur un contrat en heures, ce sont des heures supplémentaires et le contrat
  doit être à temps plein. Elles sont payées, ou compensées en repos avec `compensationMode: "REST"` :
  leurs heures, majoration comprise, sont alors créditées au compteur de repos compensateur de
  remplacement (RCR). Au forfait jours, `dayCount` crédite des JNT. Par défaut, une
  intervention un jour de repos ou d’absence validée crédite une demi-journée, et une intervention un
  jour travaillé ne crédite rien.

La période est refusée en `400` quand :

- elle sort des dates du contrat, ou concerne un stagiaire ou un mandataire social ;
- elle chevauche une autre période du contrat ;
- une intervention sort de la période, ou ne finit pas le jour où elle commence (une intervention
  de nuit se saisit en deux, de part et d’autre de minuit) ;
- un même jour décompterait plus d’une journée de JNT, toutes périodes confondues ;
- son type est introuvable ou désactivé.

### Modifier ou supprimer une période

`PUT /public/v1/on-call-periods/{onCallPeriodId}` remplace la période entière. Renvoyez donc
`onCallTypeId`, `start`, `end` et `interventions`. `PUT` et `DELETE` prennent l’identifiant Puncto
de la période. Pour le retrouver à partir de votre `foreignErpId`, appelez `GET` avec
`?matchingBy=BY_FOREIGN_ERP_ID`.

- Le contrat et le statut ne changent pas. Pour changer de contrat, supprimez la période, puis
  recréez-la.
- La contrepartie est reprise du **barème actuel** à chaque modification, même si rien d’autre ne
  change.

> **Caution**
>
> Sur un mois de paie clôturé, créer, modifier ou supprimer une période compte comme une saisie
> tardive. Elle est régularisée sur la paie suivante, et le salarié reçoit un récapitulatif
> d’astreintes rectificatif. Ne renvoyez donc une période passée que si elle a réellement changé.

Une période se lit et se supprime avec `GET` et `DELETE /public/v1/on-call-periods/{onCallPeriodId}`.
Elle figure aussi dans `GET /public/v1/payroll-variables` (type `ON_CALL`), sous le même
identifiant.

## Variables récurrentes

Une variable récurrente est versée sur chaque bulletin, de son premier à son dernier mois.

| `data` | Exemple | Montant |
| --- | --- | --- |
| `PRIME`, `primeType` `HOME_OCCUPATION_ALLOWANCE` ou `OTHER` | indemnité d’occupation du domicile | `amount`, chaque mois |
| `IN_KIND_BENEFIT`, `benefitType` autre que `VEHICLE` | logement, repas | `amount`, chaque mois |
| `IN_KIND_BENEFIT`, `benefitType` `VEHICLE` et `vehicle` | véhicule de fonction | calculé par Puncto |
| `TAX_FREE_INDEMNITY`, `indemnityType` `PUBLIC_TRANSPORT`, `periodicity` `ANNUAL` | abonnement annuel de transport | un douzième de `amountReimbursed`, chaque mois |

Un véhicule de fonction est évalué au forfait chaque mois, participation du salarié déduite. S’il
est évalué aux dépenses réelles, saisissez-le mois par mois en variable de paie.

### Créer une variable

```bash
curl https://api.puncto.fr/public/v1/recurring-variables \
  -H "Authorization: Bearer $PUNCTO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "foreignErpId": "teletravail-salarie-123",
    "contractMatching": { "type": "BY_PUNCTO_COLLABORATOR_ID", "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY" },
    "data": {
      "type": "PRIME",
      "name": "Indemnité d’occupation du domicile",
      "amount": 30,
      "primeType": "HOME_OCCUPATION_ALLOWANCE",
      "isAbsenceSensitive": false
    },
    "frequency": "MONTHLY",
    "startYear": 2026,
    "startMonth": 12
  }'
```

Un véhicule de fonction se décrit par `vehicle`, sans montant :

```json
{
  "foreignErpId": "voiture-salarie-123",
  "contractMatching": { "type": "BY_PUNCTO_COLLABORATOR_ID", "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY" },
  "data": {
    "type": "IN_KIND_BENEFIT",
    "name": "Véhicule de fonction",
    "benefitType": "VEHICLE",
    "vehicle": {
      "assignedOn": "2026-12-01",
      "ownership": "LEASED",
      "isElectric": false,
      "employerPaysFuel": false,
      "annualCost": 7200,
      "employeeMonthlyContribution": 0,
      "retainedDuringLeave": true,
      "retainedDuringAbsence": true
    }
  },
  "frequency": "MONTHLY",
  "startYear": 2026,
  "startMonth": 12
}
```

Un abonnement annuel de transport tire sa période de `data.startMonth`. N’envoyez donc ni
`frequency`, ni `startYear`, ni `startMonth`. Un contrat ne rembourse qu’un abonnement annuel à la
fois.

```json
{
  "foreignErpId": "navigo-2026-salarie-123",
  "contractMatching": { "type": "BY_PUNCTO_COLLABORATOR_ID", "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY" },
  "data": {
    "type": "TAX_FREE_INDEMNITY",
    "name": "Navigo annuel",
    "amountTotal": 1000,
    "amountReimbursed": 500,
    "indemnityType": "PUBLIC_TRANSPORT",
    "periodicity": "ANNUAL",
    "startMonth": "2026-09"
  }
}
```

Bon à savoir :

- Sans `status`, la variable est validée et versée. Avec `PENDING`, elle attend qu’un
  administrateur la valide ou la refuse dans Puncto. Vous pouvez aussi la valider avec `PUT` et
  `{ "status": "VALIDATED" }`.
- Puncto retient le contrat actif à la fin du premier mois de versement, ou à défaut celui actif au
  début de ce mois. Si ce mois couvre deux contrats, précisez `eventDate` ou utilisez
  `BY_PUNCTO_CONTRACT_ID`.
- Un `foreignErpId` déjà utilisé est refusé en `409`.

### Changer, arrêter ou supprimer une variable

Une variable récurrente ne modifie jamais un mois verrouillé (paie clôturée ou bulletin validé).
Elle se crée donc sur des mois ouverts, et **son montant ne peut pas être modifié**. Pour changer le
montant :

1. supprimez-la si aucun mois verrouillé ne l’a versée, sinon arrêtez-la à son dernier mois de
   versement ;
2. créez la nouvelle sous un autre `foreignErpId`.

`lockedThrough` indique le dernier mois verrouillé sur lequel elle a été versée. `PUT` et `DELETE`
prennent l’identifiant Puncto de la variable. Pour le retrouver à partir de votre `foreignErpId`,
appelez `GET` avec `?matchingBy=BY_FOREIGN_ERP_ID` :

```bash
curl -X PUT https://api.puncto.fr/public/v1/recurring-variables/rvar_01JB7Q6ZC8V3K9N2M4R5T7W8XY \
  -H "Authorization: Bearer $PUNCTO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "endYear": 2027, "endMonth": 6 }'

curl -X DELETE https://api.puncto.fr/public/v1/recurring-variables/rvar_01JB7Q6ZC8V3K9N2M4R5T7W8XZ \
  -H "Authorization: Bearer $PUNCTO_TOKEN"
```

Le dernier mois doit suivre le premier, et l’arrêt ne doit changer aucun mois verrouillé. Une
variable validée déjà versée sur un mois verrouillé ne peut plus être supprimée. Arrêtez-la à la
place.

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