---
title: "Importer des variables de paie"
description: "**Route historique** : pour une nouvelle intégration, créez et modifiez les variables une à une avec `POST /public/v1/payroll-variables` et `PUT /public/v1/payroll-variables/{payrollVariableId}`.\n\nCrée ou met à jour un lot de variables de paie en une seule transaction. Pour les clients qui l’utilisent encore :\n\n- Une variable invalide (collaborateur ou contrat introuvable, contrôle de saisie échoué) est ignorée et listée dans `errors` : **vérifiez `errors`, même avec une réponse `200`**.\n- Un `foreignErpId` présent plusieurs fois dans le lot est refusé à chaque occurrence.\n- Une variable renvoyée à l’identique, justificatif compris, n’est pas réécrite et compte dans `unchangedCount`. Si seul le justificatif change, il est remplacé. Dans les deux cas, ni recalcul ni saisie tardive.\n- Une variable importée garde son contrat : désignée sur un autre, elle est refusée (supprimez-la puis réimportez-la) ; désignée par son collaborateur sans `eventDate`, elle y reste tant qu’il couvre son mois de paie.\n- Jamais remplacées : astreintes, heures d’une feuille de temps, intéressement, prime de vacances ou chèques-vacances de la page Primes, indemnités de fin de contrat du mois du solde de tout compte, variables récurrentes. Un abonnement annuel de transport est refusé : créez-le avec `POST /public/v1/recurring-variables`.\n- `primeType` n’accepte que les primes saisissables : ni indemnité de fin de contrat, ni prime collective (vacances, PPV, intéressement).\n\nJustificatif : envoyez la requête en `multipart/form-data` avec un fichier `variables[i][proofFile]` (pdf, jpg, jpeg, png, webp, heic, txt, csv, xml, json, xlsx, doc, docx, zip). Sans fichier, le justificatif déjà enregistré est retiré."
---

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

> **Deprecated.**

Path: API Puncto › Variables de paie

`POST /public/v1/payroll-variables/actions/import`

**Route historique** : pour une nouvelle intégration, créez et modifiez les variables une à une avec `POST /public/v1/payroll-variables` et `PUT /public/v1/payroll-variables/{payrollVariableId}`.

Crée ou met à jour un lot de variables de paie en une seule transaction. Pour les clients qui l’utilisent encore :

- Une variable invalide (collaborateur ou contrat introuvable, contrôle de saisie échoué) est ignorée et listée dans `errors` : **vérifiez `errors`, même avec une réponse `200`**.
- Un `foreignErpId` présent plusieurs fois dans le lot est refusé à chaque occurrence.
- Une variable renvoyée à l’identique, justificatif compris, n’est pas réécrite et compte dans `unchangedCount`. Si seul le justificatif change, il est remplacé. Dans les deux cas, ni recalcul ni saisie tardive.
- Une variable importée garde son contrat : désignée sur un autre, elle est refusée (supprimez-la puis réimportez-la) ; désignée par son collaborateur sans `eventDate`, elle y reste tant qu’il couvre son mois de paie.
- Jamais remplacées : astreintes, heures d’une feuille de temps, intéressement, prime de vacances ou chèques-vacances de la page Primes, indemnités de fin de contrat du mois du solde de tout compte, variables récurrentes. Un abonnement annuel de transport est refusé : créez-le avec `POST /public/v1/recurring-variables`.
- `primeType` n’accepte que les primes saisissables : ni indemnité de fin de contrat, ni prime collective (vacances, PPV, intéressement).

Justificatif : envoyez la requête en `multipart/form-data` avec un fichier `variables[i][proofFile]` (pdf, jpg, jpeg, png, webp, heic, txt, csv, xml, json, xlsx, doc, docx, zip). Sans fichier, le justificatif déjà enregistré est retiré.

## Authentication

- `bearerAuth`, http, header `Authorization`

## Request body

_Required._

- `variables` (`importPayrollVariables.variables`; array<object>, required)
  - `status` (`importPayrollVariables.variables.status`; string, required) — Seules les variables `VALIDATED` entrent dans le bulletin. - `PENDING` : En attente - `VALIDATED` : Accepté - `REJECTED` : Refusé
    - one of `"PENDING"`, `"VALIDATED"`, `"REJECTED"`
  - `year` (`importPayrollVariables.variables.year`; integer, required) — Année de paie.
    - min 2000; max 2100; example `2026`
  - `month` (`importPayrollVariables.variables.month`; integer, required) — Mois de paie.
    - min 1; max 12; example `10`
  - `contractMatching` (`importPayrollVariables.variables.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` (`importPayrollVariables.variables.contractMatching.type`; string, required) — Clé de correspondance utilisée par `value`. - `BY_COLLABORATOR_FOREIGN_ERP_ID` : `value` est le `foreignErpId` du collaborateur - `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_COLLABORATOR_FOREIGN_ERP_ID"`, `"BY_PUNCTO_COLLABORATOR_ID"`, `"BY_PUNCTO_CONTRACT_ID"`
    - `value` (`importPayrollVariables.variables.contractMatching.value`; string, required) — Identifiant du collaborateur ou du contrat.
    - `eventDate` (`importPayrollVariables.variables.contractMatching.eventDate`; string, optional) — Date de l’événement, pour choisir parmi plusieurs contrats du mois. Ignorée avec `BY_PUNCTO_CONTRACT_ID`.
      - format `date`; example `"2026-10-05"`
  - `data` (`importPayrollVariables.variables.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` (`importPayrollVariables.variables.foreignErpId`; string, optional) — Identifiant de l’élément dans votre système. Réimporter le même `foreignErpId` met à jour l’élément existant.
  - `createdAt` (`importPayrollVariables.variables.createdAt`; string, optional) — Date de création. Par défaut, maintenant ; une variable mise à jour garde la sienne.
    - format `date-time`
  - `businessMealParticipants` (`importPayrollVariables.variables.businessMealParticipants`; array<object>, optional) — Participants d’un repas d’affaires (`expenseType` `MEALS`), désignés comme `contractMatching`. Les titres restaurant du mois de chacun sont réduits ; son contrat doit être en vigueur à la date de la dépense. La réduction s’applique dès l’enregistrement, **quel que soit le statut de la note** : envoyez les participants avec une note `VALIDATED` et retirez-les d’une note refusée. Sur un mois clôturé, c’est une saisie tardive sur la paie de chaque participant. Absent, les participants enregistrés sont conservés ; une liste vide les retire. Si la note change de mois de paie, ils la suivent avec leur réduction.
    - `type` (`importPayrollVariables.variables.businessMealParticipants.type`; string, required) — - `BY_COLLABORATOR_FOREIGN_ERP_ID` : `value` est le `foreignErpId` du collaborateur - `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_COLLABORATOR_FOREIGN_ERP_ID"`, `"BY_PUNCTO_COLLABORATOR_ID"`, `"BY_PUNCTO_CONTRACT_ID"`
    - `value` (`importPayrollVariables.variables.businessMealParticipants.value`; string, required) — Identifiant du participant ou de son contrat.
- `disableIdempotency` (`importPayrollVariables.disableIdempotency`; boolean, optional) — Rend `foreignErpId` facultatif : chaque élément est alors créé, même s’il a déjà été importé.
  - default `false`

## Example request

```json
{
  "variables": [
    {
      "foreignErpId": "prime-2026-10-salarie-123",
      "status": "VALIDATED",
      "year": 2026,
      "month": 10,
      "contractMatching": {
        "type": "BY_COLLABORATOR_FOREIGN_ERP_ID",
        "value": "salarie-123"
      },
      "data": {
        "type": "PRIME",
        "name": "Prime sur objectifs",
        "amount": 500,
        "primeType": "BUSINESS_BONUS",
        "isAbsenceSensitive": false
      }
    },
    {
      "foreignErpId": "teletravail-2026-10-salarie-123",
      "status": "VALIDATED",
      "year": 2026,
      "month": 10,
      "contractMatching": {
        "type": "BY_COLLABORATOR_FOREIGN_ERP_ID",
        "value": "salarie-123"
      },
      "data": {
        "type": "REMOTE_WORK_DAY",
        "name": "Jours de télétravail",
        "days": 8
      }
    }
  ]
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://api.puncto.fr/public/v1/payroll-variables/actions/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "variables": [
    {
      "foreignErpId": "prime-2026-10-salarie-123",
      "status": "VALIDATED",
      "year": 2026,
      "month": 10,
      "contractMatching": {
        "type": "BY_COLLABORATOR_FOREIGN_ERP_ID",
        "value": "salarie-123"
      },
      "data": {
        "type": "PRIME",
        "name": "Prime sur objectifs",
        "amount": 500,
        "primeType": "BUSINESS_BONUS",
        "isAbsenceSensitive": false
      }
    },
    {
      "foreignErpId": "teletravail-2026-10-salarie-123",
      "status": "VALIDATED",
      "year": 2026,
      "month": 10,
      "contractMatching": {
        "type": "BY_COLLABORATOR_FOREIGN_ERP_ID",
        "value": "salarie-123"
      },
      "data": {
        "type": "REMOTE_WORK_DAY",
        "name": "Jours de télétravail",
        "days": 8
      }
    }
  ]
}
'
```

### TypeScript

```typescript
const url = 'https://api.puncto.fr/public/v1/payroll-variables/actions/import';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    variables: [
      {
        foreignErpId: 'prime-2026-10-salarie-123',
        status: 'VALIDATED',
        year: 2026,
        month: 10,
        contractMatching: {type: 'BY_COLLABORATOR_FOREIGN_ERP_ID', value: 'salarie-123'},
        data: {
          type: 'PRIME',
          name: 'Prime sur objectifs',
          amount: 500,
          primeType: 'BUSINESS_BONUS',
          isAbsenceSensitive: false
        }
      },
      {
        foreignErpId: 'teletravail-2026-10-salarie-123',
        status: 'VALIDATED',
        year: 2026,
        month: 10,
        contractMatching: {type: 'BY_COLLABORATOR_FOREIGN_ERP_ID', value: 'salarie-123'},
        data: {type: 'REMOTE_WORK_DAY', name: 'Jours de télétravail', days: 8}
      }
    ]
  })
};

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/actions/import"

payload = { "variables": [
        {
            "foreignErpId": "prime-2026-10-salarie-123",
            "status": "VALIDATED",
            "year": 2026,
            "month": 10,
            "contractMatching": {
                "type": "BY_COLLABORATOR_FOREIGN_ERP_ID",
                "value": "salarie-123"
            },
            "data": {
                "type": "PRIME",
                "name": "Prime sur objectifs",
                "amount": 500,
                "primeType": "BUSINESS_BONUS",
                "isAbsenceSensitive": False
            }
        },
        {
            "foreignErpId": "teletravail-2026-10-salarie-123",
            "status": "VALIDATED",
            "year": 2026,
            "month": 10,
            "contractMatching": {
                "type": "BY_COLLABORATOR_FOREIGN_ERP_ID",
                "value": "salarie-123"
            },
            "data": {
                "type": "REMOTE_WORK_DAY",
                "name": "Jours de télétravail",
                "days": 8
            }
        }
    ] }
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

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

print(response.text)
```

## Responses

### 200

Bilan de l’import

#### Example

```json
{
  "createdCount": 0,
  "modifiedCount": 1,
  "unchangedCount": 12,
  "errors": [
    "Le collaborateur avec l’identifiant salarie-456 (matching par BY_COLLABORATOR_FOREIGN_ERP_ID) n’a pas été trouvé pour la variable de paie prime-2026-10-salarie-456 avec le type PRIME, le nom Prime sur objectifs"
  ]
}
```

- `createdCount` (`importPayrollVariables.response.200.createdCount`; integer, required) — Éléments créés.
- `modifiedCount` (`importPayrollVariables.response.200.modifiedCount`; integer, required) — Éléments existants mis à jour.
- `errors` (`importPayrollVariables.response.200.errors`; array<string>, required) — Un message par élément ignoré ; les autres sont importés.
- `unchangedCount` (`importPayrollVariables.response.200.unchangedCount`; integer, required) — Variables renvoyées à l’identique, laissées telles quelles.

### 400

`foreignErpId` manquant sans `disableIdempotency`, ou import annulé

#### Example

```json
{
  "error": "Une erreur est survenue lors de l’importation des variables de paie (aucune donnée importée)"
}
```

- `error` (`importPayrollVariables.response.400.error`; string, required) — Message lisible, en français.
- `errorCode` (`importPayrollVariables.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` (`importPayrollVariables.response.401.error`; string, required) — Message lisible, en français.
- `errorCode` (`importPayrollVariables.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` (`importPayrollVariables.response.403.error`; string, required) — Message lisible, en français.
- `errorCode` (`importPayrollVariables.response.403.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 409

Conflit avec un autre import, rien n’est importé : renvoyez le lot. Un autre import de variables de paie de l’entreprise est en cours, ou un `foreignErpId` du lot vient d’être importé par un autre appel.

#### Example

```json
{
  "error": "Un autre import de variables de paie est en cours pour cette entreprise : réessayez dans quelques instants."
}
```

- `error` (`importPayrollVariables.response.409.error`; string, required) — Message lisible, en français.
- `errorCode` (`importPayrollVariables.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` (`importPayrollVariables.response.422.errors`; array<object>, required)
  - `message` (`importPayrollVariables.response.422.errors.message`; string, required)
  - `rule` (`importPayrollVariables.response.422.errors.rule`; string, required) — Règle de validation en échec.
  - `field` (`importPayrollVariables.response.422.errors.field`; string, required) — Chemin du champ, par exemple `absences.0.type`.


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