---
title: "Conventions"
description: "Les formats, la pagination et les erreurs communs à toutes les routes."
---

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

# Conventions

## Formats

| Donnée | Format |
| --- | --- |
| Requêtes et réponses | JSON (`Content-Type: application/json`) |
| Dates | `YYYY-MM-DD` (`2026-10-05`) |
| Horodatages | ISO 8601 (`2026-10-05T09:30:00.000Z`) |
| Montants | euros, nombre décimal (`1250.5`) |
| Identifiants Puncto | chaîne préfixée par la ressource : `coll_…` collaborateur, `cont_…` contrat, `came_…` avenant, `abse_…` absence, `pvar_…` variable de paie, `rvar_…` variable récurrente, `cfil_…` document, `esta_…` établissement |

L’envoi d’un document (`POST /public/v1/documents`) fait exception et utilise
`multipart/form-data`. Le téléchargement d’un document ou du PDF d’un bulletin renvoie le fichier
brut.

## Pagination

Les listes acceptent `page` (à partir de `1`) et `perPage` (`50` par défaut) :

```json
{
  "data": [],
  "meta": {
    "total": 128,
    "page": 1,
    "perPage": 50,
    "currentPage": 1,
    "firstPage": 1,
    "lastPage": 3
  }
}
```

`perPage` vaut `200` au plus, `50` pour les soldes de congés. Le maximum de chaque route figure dans
la référence.

## Statuts de succès

| Statut | Signification |
| --- | --- |
| `200` | Lecture, modification ou action réussie, bilan d’un import |
| `201` | Ressource créée : collaborateur, contrat, document |
| `204` | Ressource supprimée, sans corps de réponse |

Un import renvoie `200` même quand des éléments sont ignorés. **Vérifiez donc toujours `errors`**
(voir [Importer absences et variables](/developpeurs/guides/imports)).

## Erreurs

Une erreur renvoie un statut HTTP et un message en français :

```json
{ "error": "Collaborateur non trouvé" }
```

| Statut | Signification |
| --- | --- |
| `400` | Opération impossible ou contraire aux règles de la paie ; le message explique pourquoi |
| `401` | Clé d’API absente, invalide ou révoquée |
| `403` | Opération interdite, par exemple sur un mois de paie déjà validé |
| `404` | Ressource introuvable |
| `409` | Identifiant externe déjà utilisé, ou autre opération en cours sur la même ressource |
| `422` | Paramètres invalides ou manquants |

### `422` : champ invalide

Un champ manquant ou mal formé renvoie `422`, avec le détail de chaque champ :

```json
{
  "errors": [
    {
      "message": "Le champ type d’absence doit être une valeur autorisée",
      "rule": "enum",
      "field": "absences.0.type"
    }
  ]
}
```

Une combinaison de champs incohérente, comme une date de fin sur un CDI ou une période d’essai sur
un stage, renvoie `400`.

### `409` : élément existant ou opération en cours

Si une création ou un envoi de document désigne un élément qui existe déjà (même `foreignErpId`,
contrat qui commence le même jour), la réponse `409` contient son identifiant Puncto
(`collaboratorId`, `contractId` ou `documentId`) :

```json
{
  "error": "Le foreignErpId \"salarie-123\" est déjà celui du collaborateur coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY : pour lui créer un nouveau contrat, utilisez POST /public/v1/contracts",
  "collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
}
```

Si une autre opération est en cours sur la même entreprise ou le même contrat (création, avenant,
import), réessayez quelques instants plus tard.

Source: https://docs.puncto.fr/developpeurs/conventions/index.mdx
