Skip to content

Astreintes et variables récurrentes

Saisir les périodes d’astreinte et les éléments de paie versés chaque mois.

Deux familles de routes complètent les variables de paie :

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

curl https://api.puncto.fr/public/v1/on-call-types \
  -H "Authorization: Bearer $PUNCTO_TOKEN"
{
  "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.

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.

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

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 :

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

{
  "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 :

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.

Type to search…

↑↓ navigate↵ selectEsc close