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) :
{
"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).
Erreurs
Une erreur renvoie un statut HTTP et un message en français :
{ "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 :
{
"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) :
{
"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.