Skip to content

Conventions

Les formats, la pagination et les erreurs communs à toutes les routes.

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.

Type to search…

↑↓ navigate↵ selectEsc close