Toutes les données se lisent avec des routes GET, donc une clé en Lecture Seule suffit. Une
lecture ne modifie rien dans Puncto (aucun mois ouvert, aucune semaine de temps créée, aucun solde
enregistré).
Routes de lecture
Toutes les routes sont des GET sous /public/v1/. Collaborateurs, contrats, absences, variables
de paie, périodes d’astreinte, bulletins et documents ont aussi une fiche par identifiant
(GET /public/v1/<ressource>/{id}).
| Données | Routes |
|---|---|
| Entreprise : identité, effectifs, modules, règles de paie | company |
| Établissements, postes, équipes | establishments, company-roles, company-teams |
| Contrats de mutuelle et de prévoyance | oc-contracts |
| Collaborateurs | collaborators |
| Contrats, avenants, sorties, affiliations | contracts, et contracts/{contractId}/trial-period pour la période d’essai |
| Absences, soldes de congés | absences, holidays-balances |
| Variables de paie (astreintes comprises), variables récurrentes | payroll-variables, recurring-variables |
| Astreintes | on-call-types, on-call-periods |
| Télétravail, feuilles de temps, forfait jours | remote-work-days, timesheets, forfait-jour-declarations |
| Mois de paie et DSN mensuelles, suivi des déclarations | payroll-months, declaration-trackings |
| Bulletins de paie | payslips, et payslips/{payslipId}/pdf pour le PDF |
| Documents | documents, et documents/{documentId}/download pour le fichier |
| Index de l’égalité professionnelle | reports/gender-equality-index |
Pour un premier export, lisez dans cet ordre :
- les référentiels : entreprise, établissements, postes, équipes, mutuelle et prévoyance ;
- les collaborateurs et leurs contrats ;
- les données de chaque mois.
Les ressources se référencent par establishmentId, companyRoleId, companyTeamId,
collaboratorId, contractId, payrollMonthId et documentId.
Parcourir une liste
Demandez les pages une à une jusqu’à meta.lastPage, 200 éléments par page au plus (50 pour les
soldes de congés) :
page=1
while : ; do
curl -s "https://api.puncto.fr/public/v1/establishments?page=$page&perPage=200" \
-H "Authorization: Bearer $PUNCTO_TOKEN" > "etablissements-$page.json"
last=$(jq '.meta.lastPage' "etablissements-$page.json")
[ "$page" -ge "$last" ] && break
page=$((page + 1))
done- L’ordre est stable, mais une création ou une suppression pendant le parcours décale les pages. Dédoublonnez par identifiant et relancez le parcours si la liste a changé.
- Pour un filtre à plusieurs valeurs, répétez le paramètre (
status[]=CLOSED&status[]=SUPERSEDED). Aveccurl, ajoutez-gpour que les crochets ne soient pas interprétés.
Soldes de congés
La route Lister les soldes de congés calcule les
compteurs de chaque contrat en vigueur à calculationDate (aujourd’hui par défaut) : congés payés
N, N-1 et N-2, ancienneté, fractionnement, jours non travaillés, RTT et repos compensateurs.
curl "https://api.puncto.fr/public/v1/holidays-balances?calculationDate=2026-05-31&perPage=50" \
-H "Authorization: Bearer $PUNCTO_TOKEN"Bon à savoir :
- Les absences validées sont décomptées, les demandes en attente ne le sont pas.
- Un solde qui ne peut pas être calculé vaut
null, avec la raison dansunavailableReason. Les autres soldes de la page sont calculés normalement. - Les mandats sociaux n’ont pas de compteurs et ne sont pas listés.
- Avec
contractId, un contrat qui n’est pas en vigueur àcalculationDatedonne une page vide. - Une date antérieure au paramétrage de paie de l’entreprise dans Puncto renvoie
400. - Une date après la fin du douzième mois à venir renvoie
422.
Temps de travail
- Jours de télétravail : ceux déclarés par
les collaborateurs. Les corrections saisies en variables de paie (
REMOTE_WORK_DAY) se lisent avec les variables de paie. - Feuilles de temps : une semaine appartient au mois
de paie de son dimanche, celui que filtrent
yearetmonth. Elle n’est listée qu’une fois créée dans Puncto (par le collaborateur, un responsable ou une relance). - Relevés forfait jours : chaque jour du mois, matin et après-midi.
Ces données n’existent que si le module correspondant est activé (modules de
l’entreprise). Celles saisies avant la désactivation d’un
module restent lisibles.
Mois de paie et déclarations
La route Lister les mois de paie donne l’état de chaque
mois de chaque établissement et de sa DSN mensuelle. Quand un mois clôturé est rouvert, une
nouvelle révision est créée. L’ancienne passe à SUPERSEDED, et ses bulletins sont remplacés par
ceux de la nouvelle quand celle-ci est clôturée.
Le suivi des déclarations se filtre par
source : dsn, dpae, fctu (fin de contrat) ou arret (signalements d’arrêt et de reprise).
curl -g "https://api.puncto.fr/public/v1/declaration-trackings?source=dsn&months[]=2026-09&statuses[]=error" \
-H "Authorization: Bearer $PUNCTO_TOKEN"Pour les DSN mensuelles, seul le dernier dépôt de chaque mois est listé. Le fichier déclaré se
télécharge avec GET /public/v1/documents/{documentId}/download.
Détecter les changements
Relisez périodiquement les listes utiles, par période (year et month, dates) plutôt qu’en
entier, et comparez les identifiants reçus à ceux que vous connaissez. Une donnée supprimée
disparaît simplement des listes, et la date de modification d’une ressource ne suit pas toujours
celle de ses éléments rattachés.