Enregistrez votre propre identifiant sur chaque collaborateur, dans le champ foreignErpId. Il
vous sert à retrouver les identifiants Puncto. Les écritures (création, modification,
suppression) se font ensuite avec l’identifiant Puncto, ce qui garantit que vous modifiez bien
l’élément que vous avez lu.
Renseigner le foreignErpId
- Listez les collaborateurs.
- Rapprochez-les des vôtres, par exemple par nom, date de naissance ou numéro de sécurité sociale.
- Enregistrez votre identifiant sur chacun :
curl -X PUT https://api.puncto.fr/public/v1/collaborators/coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY \
-H "Authorization: Bearer $PUNCTO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "foreignErpId": "salarie-123" }'- Le
foreignErpIdest unique dans l’entreprise. L’attribuer à un second collaborateur renvoie409. - Un collaborateur créé par l’API reçoit le sien dès sa création.
Retrouver un identifiant Puncto
| Pour | Lecture |
|---|---|
| un collaborateur | GET /public/v1/collaborators?collaboratorForeignErpId=salarie-123 |
| ses contrats | GET /public/v1/contracts?collaboratorForeignErpId=salarie-123 |
| son contrat en vigueur à une date | GET /public/v1/contracts/salarie-123?matchingBy=BY_COLLABORATOR_FOREIGN_ERP_ID&matchingDate=2026-10-20 |
| une variable de paie, une astreinte ou une variable récurrente | GET …/{id}?matchingBy=BY_FOREIGN_ERP_ID sur sa route |
Conservez l’identifiant Puncto renvoyé, car c’est lui qu’attendent les routes POST, PUT et
DELETE.
Désigner le contrat d’une création
Les absences, variables de paie, astreintes et variables récurrentes désignent leur contrat avec
contractMatching :
{
"contractMatching": {
"type": "BY_PUNCTO_COLLABORATOR_ID",
"value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
"eventDate": "2026-10-20"
}
}type |
value |
|---|---|
BY_PUNCTO_COLLABORATOR_ID |
l’identifiant Puncto du collaborateur, coll_… |
BY_PUNCTO_CONTRACT_ID |
l’identifiant Puncto du contrat, cont_… |
Les imports historiques acceptent encore
BY_COLLABORATOR_FOREIGN_ERP_ID.
Choisir le contrat avec eventDate
Une absence ou une variable de paie est rattachée à un contrat. Le champ eventDate, facultatif,
permet de choisir lequel :
- Sans
eventDate, Puncto retient le contrat actif à la fin du mois concerné, ou à défaut à son début. Le mois concerné est celui de la date de début pour une absence, le mois de paie pour une variable. - Avec
eventDate, Puncto retient le contrat actif à cette date. Précisez-la quand le collaborateur change de contrat en cours de mois (fin de CDD suivie d’un CDI, par exemple). - Avec
BY_PUNCTO_CONTRACT_ID, le contrat est désigné directement eteventDateest ignorée.