---
title: "Créer une variable de paie"
description: "Crée une variable de paie et recalcule les bulletins en brouillon concernés. Sur un mois de paie clôturé ou dont le bulletin est validé, c’est une saisie tardive, régularisée par la prochaine paie ouverte.\n\n`primeType` n’accepte que les primes saisissables : ni indemnité de fin de contrat, ni prime collective (vacances, PPV, intéressement).\n\nJustificatifs : envoyez la requête en `multipart/form-data` avec des fichiers `proofFiles[i]` (pdf, jpg, jpeg, png, webp, heic, txt, csv, xml, json, xlsx, doc, docx, zip). Ils sont requis pour une indemnité non soumise, sauf une note de frais ou un transport public."
---

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

Path: API Puncto › Variables de paie

`POST /public/v1/payroll-variables`

Crée une variable de paie et recalcule les bulletins en brouillon concernés. Sur un mois de paie clôturé ou dont le bulletin est validé, c’est une saisie tardive, régularisée par la prochaine paie ouverte.

`primeType` n’accepte que les primes saisissables : ni indemnité de fin de contrat, ni prime collective (vacances, PPV, intéressement).

Justificatifs : envoyez la requête en `multipart/form-data` avec des fichiers `proofFiles[i]` (pdf, jpg, jpeg, png, webp, heic, txt, csv, xml, json, xlsx, doc, docx, zip). Ils sont requis pour une indemnité non soumise, sauf une note de frais ou un transport public.

## Authentication

- `bearerAuth`, http, header `Authorization`

## Request body

_Required._

- `contractMatching` (`createPayrollVariable.contractMatching`; object, required) — Contrat qui porte la variable : celui du collaborateur actif à `eventDate`, à défaut sur le mois de paie, ou le contrat lui-même avec `BY_PUNCTO_CONTRACT_ID` (utile quand le collaborateur a deux contrats dans le mois).
  - `type` (`createPayrollVariable.contractMatching.type`; string, required) — Clé de correspondance utilisée par `value`. - `BY_PUNCTO_COLLABORATOR_ID` : `value` est l’identifiant Puncto du collaborateur - `BY_PUNCTO_CONTRACT_ID` : `value` est l’identifiant Puncto du contrat (`GET /public/v1/contracts`), `eventDate` est ignorée
    - one of `"BY_PUNCTO_COLLABORATOR_ID"`, `"BY_PUNCTO_CONTRACT_ID"`
  - `value` (`createPayrollVariable.contractMatching.value`; string, required) — Identifiant Puncto du collaborateur, ou du contrat avec `BY_PUNCTO_CONTRACT_ID`. Depuis votre `foreignErpId`, retrouvez-le avec `GET /public/v1/collaborators?collaboratorForeignErpId=…`.
    - minLength 1
  - `eventDate` (`createPayrollVariable.contractMatching.eventDate`; string, optional) — Date de l’événement, pour choisir le contrat quand le collaborateur en a plusieurs sur le mois.
    - format `date`; example `"2026-10-05"`
- `data` (`createPayrollVariable.data`; one of, required) — Contenu de la variable. La forme dépend de `type`, et pour `TAX_FREE_INDEMNITY` de `indemnityType`.
  - one of: `Prime`, `Heures supplémentaires`, `Jours de télétravail`, `Ajustement des primes de panier`, `Ajustement des titres restaurant`, `Acompte sur salaire`, `Retenue sur salaire`, `Avantage en nature`, `Note de frais`, `Transport personnel`, `Autre indemnité non soumise`
- `foreignErpId` (`createPayrollVariable.foreignErpId`; string, optional) — Identifiant de l’élément dans votre système. Réimporter le même `foreignErpId` met à jour l’élément existant.
- `status` (`createPayrollVariable.status`; string, optional) — Par défaut `VALIDATED`. Seules les variables `VALIDATED` entrent dans le bulletin. - `PENDING` : En attente - `VALIDATED` : Accepté - `REJECTED` : Refusé
  - one of `"PENDING"`, `"VALIDATED"`, `"REJECTED"`
- `year` (`createPayrollVariable.year`; integer, optional) — Année de paie. Absente, la variable va au prochain mois de paie ouvert.
  - min 2000; max 2100; example `2026`
- `month` (`createPayrollVariable.month`; integer, optional) — Mois de paie, requis avec `year`.
  - min 1; max 12; example `10`
- `businessMealParticipants` (`createPayrollVariable.businessMealParticipants`; array<object>, optional) — Participants d’un repas d’affaires (`expenseType` `MEALS`), requis, désignés comme `contractMatching`. Une liste vide les retire. Les titres restaurant du mois de chacun sont réduits dès l’enregistrement, **quel que soit le statut de la note** ; son contrat doit être en vigueur à la date de la dépense.
  - `type` (`createPayrollVariable.businessMealParticipants.type`; string, required) — - `BY_PUNCTO_COLLABORATOR_ID` : `value` est l’identifiant Puncto du collaborateur - `BY_PUNCTO_CONTRACT_ID` : `value` est l’identifiant Puncto du contrat
    - one of `"BY_PUNCTO_COLLABORATOR_ID"`, `"BY_PUNCTO_CONTRACT_ID"`
  - `value` (`createPayrollVariable.businessMealParticipants.value`; string, required) — Identifiant Puncto du participant ou de son contrat.

## Example request

```json
{
  "foreignErpId": "prime-2026-10-salarie-123",
  "year": 2026,
  "month": 10,
  "contractMatching": {
    "type": "BY_PUNCTO_COLLABORATOR_ID",
    "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
  },
  "data": {
    "type": "PRIME",
    "name": "Prime sur objectifs",
    "amount": 500,
    "primeType": "BUSINESS_BONUS",
    "isAbsenceSensitive": false
  }
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://api.puncto.fr/public/v1/payroll-variables \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "foreignErpId": "prime-2026-10-salarie-123",
  "year": 2026,
  "month": 10,
  "contractMatching": {
    "type": "BY_PUNCTO_COLLABORATOR_ID",
    "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
  },
  "data": {
    "type": "PRIME",
    "name": "Prime sur objectifs",
    "amount": 500,
    "primeType": "BUSINESS_BONUS",
    "isAbsenceSensitive": false
  }
}
'
```

### TypeScript

```typescript
const url = 'https://api.puncto.fr/public/v1/payroll-variables';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    foreignErpId: 'prime-2026-10-salarie-123',
    year: 2026,
    month: 10,
    contractMatching: {type: 'BY_PUNCTO_COLLABORATOR_ID', value: 'coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY'},
    data: {
      type: 'PRIME',
      name: 'Prime sur objectifs',
      amount: 500,
      primeType: 'BUSINESS_BONUS',
      isAbsenceSensitive: false
    }
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.puncto.fr/public/v1/payroll-variables"

payload = {
    "foreignErpId": "prime-2026-10-salarie-123",
    "year": 2026,
    "month": 10,
    "contractMatching": {
        "type": "BY_PUNCTO_COLLABORATOR_ID",
        "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
    },
    "data": {
        "type": "PRIME",
        "name": "Prime sur objectifs",
        "amount": 500,
        "primeType": "BUSINESS_BONUS",
        "isAbsenceSensitive": False
    }
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 201

Variable de paie créée

#### Example

```json
{
  "payrollVariableId": "pvar_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "foreignErpId": "string",
  "contractId": "cont_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "collaboratorForeignErpId": "string",
  "year": 0,
  "month": 0,
  "status": "PENDING",
  "data": {
    "type": "PRIME",
    "name": "string",
    "amount": 0,
    "base": 0,
    "primeType": "HOLIDAY_BONUS",
    "isAbsenceSensitive": true,
    "attachmentPeriod": {
      "startDate": "2019-08-24",
      "endDate": "2019-08-24"
    }
  },
  "proofFiles": [
    {
      "documentId": "cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "displayFileName": "string",
      "fileType": "PAYSLIP",
      "mimeType": "image/jpeg",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ],
  "businessMealParticipantContractIds": [
    "cont_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
  ],
  "origin": "ENTRY",
  "isLocked": true,
  "lockState": {
    "state": "OPEN"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
```

- `payrollVariableId` (`createPayrollVariable.response.201.payrollVariableId`; string, required) — Identifiant Puncto de la variable de paie
- `foreignErpId` (`createPayrollVariable.response.201.foreignErpId`; string | null, required) — Identifiant de la variable dans votre système, null si elle n'en a pas
- `contractId` (`createPayrollVariable.response.201.contractId`; string, required) — Contrat qui porte la variable
- `collaboratorId` (`createPayrollVariable.response.201.collaboratorId`; string, required) — Collaborateur titulaire du contrat
- `collaboratorForeignErpId` (`createPayrollVariable.response.201.collaboratorForeignErpId`; string | null, required) — Identifiant du collaborateur dans votre système, null s'il n'a pas été renseigné
- `year` (`createPayrollVariable.response.201.year`; number, required) — Année du mois de paie
- `month` (`createPayrollVariable.response.201.month`; number, required) — Mois de paie, de 1 (janvier) à 12
- `status` (`createPayrollVariable.response.201.status`; string, required) — Seules les variables `VALIDATED` entrent dans le bulletin
  - one of `"PENDING"`, `"VALIDATED"`, `"REJECTED"`
- `data` (`createPayrollVariable.response.201.data`; any of, required) — Contenu de la variable
  - any of: `PublicApiPayrollVariablePrimeData`, `PublicApiPayrollVariableSalaryDeductionData`, `PublicApiPayrollVariableInKindBenefitData`, `PublicApiPayrollVariableOvertimeData`, `PublicApiPayrollVariableMonthlyOvertimeData`, `PublicApiPayrollVariableRemoteWorkDayData`, `PublicApiPayrollVariableMealAllowanceAdjustmentData`, `PublicApiPayrollVariableMealVoucherAdjustmentData`, `PublicApiPayrollVariableSalaryAdvanceData`, `PublicApiPayrollVariableProfitSharingData`, `PublicApiPayrollVariableHolidayVoucherData`, `PublicApiPayrollVariablePrevoyanceIjData`, `PublicApiPayrollVariableOnCallData`, `PublicApiPayrollVariableExpenseNoteData`, `PublicApiPayrollVariablePersonalTransportData`, `PublicApiPayrollVariableOtherTaxFreeIndemnityData`
- `proofFiles` (`createPayrollVariable.response.201.proofFiles`; array<object>, required) — Justificatifs, dans leur ordre d'ajout
  - `documentId` (`createPayrollVariable.response.201.proofFiles.documentId`; string, required) — Identifiant Puncto du document
  - `displayFileName` (`createPayrollVariable.response.201.proofFiles.displayFileName`; string, required) — Nom du document affiché dans Puncto
  - `fileType` (`createPayrollVariable.response.201.proofFiles.fileType`; string, required) — Type de document
    - one of `"PAYSLIP"`, `"PAYSLIP_ARCHIVED"`, `"DSN_MONTHLY"`, `"DSN_WORK_STOPPAGE"`, `"DSN_WORK_STOPPAGE_RESUMPTION"`, `"DSN_FCTU"`, `"DSN_SADV"`, `"CRM"`, `"EXPENSE_BILL"`, `"MEAL_VOUCHER_EXPORT"`, `"SEPA_PAYROLL"`, `"SEPA_SDTC"`, `"ABSENCE_PROOF"`, `"DPAE"`, `"DPAE_RETURN"`, `"ACCOUNTING_PAYROLL_OD"`, `"ACCOUNTING_PAYROLL_DSN_RECAP"`, `"ACCOUNTING_CONTRIBUTIONS_DETAIL"`, `"ACCOUNTING_CONTRIBUTIONS_RECAP"`, `"ACCOUNTING_PAYBOOK"`, `"ACCOUNTING_PAYROLL_LOG"`, `"ACCOUNTING_REST_RECAP"`, `"IDENTITY"`, `"VITALE"`, `"RIB"`, `"CONTRACT"`, `"INTERNSHIP_AGREEMENT"`, `"INTERNSHIP_CERTIFICATE"`, `"INTERNSHIP_CERTIFICATE_SIGNED"`, `"WORK_CERTIFICATE"`, `"WORK_CERTIFICATE_SIGNED"`, `"FINAL_SETTLEMENT_RECEIPT"`, `"FINAL_SETTLEMENT_RECEIPT_SIGNED"`, `"PROFIT_SHARING_STATEMENT"`, `"ON_CALL_STATEMENT"`, `"PROFIT_SHARING_AGREEMENT_RECEIPT"`, `"BILLING_INVOICE"`, `"COMPANY_SETUP_CHECKLIST"`, `"FCTU_AER"`, `"EXPORT"`, `"ABSENCE_BATCH"`, `"VARIABLE_BATCH"`, `"OC_FICHE"`, `"BPIJ"`, `"SIGNATURE_AUDIT_TRAIL"`, `"OTHER"`
  - `mimeType` (`createPayrollVariable.response.201.proofFiles.mimeType`; any of, required) — Type MIME du fichier
    - any of: `ImageMimeType`, `OtherMimeType`
  - `createdAt` (`createPayrollVariable.response.201.proofFiles.createdAt`; string, required) — Date d'enregistrement du document dans Puncto
    - format `date-time`
- `businessMealParticipantContractIds` (`createPayrollVariable.response.201.businessMealParticipantContractIds`; array<string>, required) — Note de frais de repas d'affaires : contrats des participants, dont les titres restaurant du mois sont réduits dès l'enregistrement de la note, quel que soit son statut
- `origin` (`createPayrollVariable.response.201.origin`; string, required) — Parcours de Puncto qui a créé la variable : - `ENTRY` : saisie dans Puncto ou importée par l'API ; aussi les indemnités générées par la clôture d'un contrat (celles du mois du solde de tout compte se modifient depuis la clôture) et le report d'un net négatif, généré à la clôture du mois sur le mois suivant (retenue `LAST_MONTH_NEGATIVE_PAY_ADVANCE`) ; - `VARIABLE_BATCH` : import d'un fichier de variables dans Puncto, modifiable comme une saisie ; - `TIMESHEET` : heures supplémentaires payées d'une feuille de temps validée, modifiables seulement depuis la feuille ; - `ON_CALL_PERIOD` : période d'astreinte, modifiable par l'import des périodes d'astreinte ; - `PROFIT_SHARING` : versement d'intéressement, modifiable seulement depuis ce versement ; - `HOLIDAY_BONUS`, `HOLIDAY_VOUCHER_ATTRIBUTION` : prime de vacances ou chèques-vacances de la page Primes, modifiables seulement depuis cette page ; - `VALUE_SHARING_BONUS` : versement de prime de partage de la valeur (PPV) de la page Primes ; comme dans l'application, la variable peut changer de statut ou être supprimée ; - `PREVOYANCE_IJ_SLIP` : part d'un bordereau de paiement prévoyance, modifiable seulement depuis ce bordereau.
  - one of `"ENTRY"`, `"VARIABLE_BATCH"`, `"TIMESHEET"`, `"ON_CALL_PERIOD"`, `"PROFIT_SHARING"`, `"HOLIDAY_BONUS"`, `"HOLIDAY_VOUCHER_ATTRIBUTION"`, `"VALUE_SHARING_BONUS"`, `"PREVOYANCE_IJ_SLIP"`
- `isLocked` (`createPayrollVariable.response.201.isLocked`; boolean, required) — Plus aucune modification n'est possible : le mois de paie est clôturé et aucune paie ouverte ne peut porter la régularisation (`lockState.state` vaut `BLOCKED`)
- `lockState` (`createPayrollVariable.response.201.lockState`; any of, required) — Effet d'une modification de la variable : sur la paie du mois, ou en saisie tardive régularisée par une paie ultérieure
  - any of: `object`, `object`, `object`
- `createdAt` (`createPayrollVariable.response.201.createdAt`; string, required) — Date de création de la variable
  - format `date-time`
- `updatedAt` (`createPayrollVariable.response.201.updatedAt`; string, required) — Date de dernière modification de la variable
  - format `date-time`

### 400

Saisie invalide, ou mois clôturé qu’aucune paie ouverte ne peut régulariser

#### Example

```json
{
  "error": "Le fichier justificatif est requis"
}
```

- `error` (`createPayrollVariable.response.400.error`; string, required) — Message lisible, en français.
- `errorCode` (`createPayrollVariable.response.400.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 401

Clé d’API absente, invalide ou révoquée

#### Example

```json
{
  "error": "Les endpoints de l’API publique sont réservés aux comptes application."
}
```

- `error` (`createPayrollVariable.response.401.error`; string, required) — Message lisible, en français.
- `errorCode` (`createPayrollVariable.response.401.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 403

Opération hors de l’accès de la clé d’API

#### Example

```json
{
  "error": "Opération interdite"
}
```

- `error` (`createPayrollVariable.response.403.error`; string, required) — Message lisible, en français.
- `errorCode` (`createPayrollVariable.response.403.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 404

Collaborateur ou contrat introuvable

#### Example

```json
{
  "error": "Aucun contrat trouvé pour ce collaborateur sur cette période"
}
```

- `error` (`createPayrollVariable.response.404.error`; string, required) — Message lisible, en français.
- `errorCode` (`createPayrollVariable.response.404.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 409

`foreignErpId` déjà utilisé par une variable de paie ou récurrente

#### Example

```json
{
  "error": "Une variable existe déjà avec le foreignErpId prime-2026-10-salarie-123 : GET /public/v1/payroll-variables/prime-2026-10-salarie-123?matchingBy=BY_FOREIGN_ERP_ID donne son identifiant Puncto, avec lequel la modifier."
}
```

- `error` (`createPayrollVariable.response.409.error`; string, required) — Message lisible, en français.
- `errorCode` (`createPayrollVariable.response.409.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 422

Paramètres invalides

#### Example

```json
{
  "errors": [
    {
      "message": "Le champ statut de l’absence doit être une valeur autorisée",
      "rule": "enum",
      "field": "status"
    }
  ]
}
```

- `errors` (`createPayrollVariable.response.422.errors`; array<object>, required)
  - `message` (`createPayrollVariable.response.422.errors.message`; string, required)
  - `rule` (`createPayrollVariable.response.422.errors.rule`; string, required) — Règle de validation en échec.
  - `field` (`createPayrollVariable.response.422.errors.field`; string, required) — Chemin du champ, par exemple `absences.0.type`.


Source: https://docs.puncto.fr/reference/payroll-variables/create/index.md
