- Pour une personne que Puncto ne connaît pas encore, utilisez Créer un collaborateur et son premier contrat.
- Pour un collaborateur déjà présent (réembauche, stage puis CDI, CDD puis CDI…), utilisez Créer un contrat.
- Pour relire les données, utilisez Lister les contrats, Consulter un contrat et Consulter un collaborateur.
Embaucher un collaborateur
Une seule requête crée le collaborateur, son compte et son contrat :
curl https://api.puncto.fr/public/v1/collaborators \
-H "Authorization: Bearer $PUNCTO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"foreignErpId": "salarie-123",
"identity": {
"firstName": "Camille",
"lastName": "Durand",
"birthDate": "1991-06-14",
"birthCountryCode": "FR",
"birthCity": "Nantes",
"birthDepartmentCode": "44",
"nationality": "FR"
},
"contact": {
"address": "12 rue de la Paix",
"postalCode": "75002",
"city": "Paris",
"countryCode": "FR",
"personalEmail": "camille.durand@example.com",
"professionalEmail": "camille.durand@entreprise.fr"
},
"socialSecurityNumber": "2910644123456",
"isBoeth": false,
"dependentChildrenCount": 0,
"iban": "FR7630004000031234567890143",
"bic": "BNPAFRPPXXX",
"contract": {
"workerType": "EMPLOYEE_CDI",
"startDate": "2026-11-02",
"establishmentSiret": "55210055400013",
"companyRoleName": "Développeuse backend",
"managerId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XZ",
"trialPeriodEndDate": "2027-03-01",
"dpaeDoneByPuncto": true,
"amendment": {
"isCadre": true,
"quotity": {
"type": "HEURE",
"monthlyWorkingHours": 151.67,
"workingPercentage": 100,
"paidContractualOvertimeHours": 0,
"rttContractualOvertimeHours": 0,
"rcrContractualOvertimeHours": 0
},
"conventionalWorkerStatus": "04",
"workerOutsideFranceStatus": "99",
"conventionalPosition": { "type": "CADRE", "position": "2.1 (au moins 26 ans)" },
"weekDaysWorked": 31,
"grossAnnualSalary": 48000,
"codePcsEse": "388a"
}
}
}'La réponse 201 contient { "collaborator": …, "contract": … }. En cas d’erreur, rien n’est
enregistré, pas même le poste qu’un companyRoleName inconnu aurait créé.
Bon à savoir
foreignErpId(votre identifiant) est obligatoire. S’il correspond à un collaborateur déjà embauché, la réponse est409avec lecollaboratorIdexistant, et rien n’est créé.- Si le numéro de sécurité sociale est déjà connu dans l’entreprise, la réponse est
409avec lecollaboratorId. Créez alors le contrat avecPOST /public/v1/contracts. personalEmailsert à la connexion. Il doit être unique sur tout Puncto, toutes entreprises confondues, sinon la réponse est422.- Sans
socialSecurityNumber,sexest obligatoire et Puncto attribue un NTT."dpaeDoneByPuncto": falseest aussi obligatoire, sinon la réponse est400. - Avec un numéro,
identityTypevautNIRpar défaut (ouNIA), etsexdoit correspondre au premier chiffre. Les NIR provisoires (commençant par 7 ou 8) sont refusés.
Désigner l’établissement, le poste, l’équipe et le manager
Chacun se désigne soit par son identifiant Puncto, soit par votre référence, mais jamais par les
deux (422) :
| Désignation | Identifiant Puncto | Votre référence |
|---|---|---|
| Établissement | establishmentId |
establishmentSiret |
| Poste (obligatoire) | companyRoleId |
companyRoleName |
| Équipe | companyTeamId |
companyTeamName |
| Manager | managerId |
aucune : identifiant Puncto seulement |
- Un nom (
companyRoleName,companyTeamName) est comparé exactement, casse et accents compris. Un nom inconnu est créé. - Si vous ne précisez pas l’établissement, Puncto prend celui du dernier contrat du collaborateur à sa fin (y compris après un changement de lieu de travail), sinon celui du contrat en attente de saisie dans Puncto, sinon le siège.
- Pour retrouver les identifiants, utilisez Lister les établissements, Lister les postes, Lister les équipes et Lister les contrats de mutuelle et de prévoyance.
Une fois le collaborateur créé :
- Modifier un collaborateur permet de changer son identité,
ses coordonnées, son mode de paiement ou son manager (
nullle retire). Les champs absents ne sont pas modifiés. - Supprimer un collaborateur reste possible tant qu’aucune paie de son contrat n’est clôturée.
Créer un contrat pour un collaborateur existant
Désignez le collaborateur par son identifiant Puncto, collaboratorId. Pour le retrouver à partir
de votre identifiant, appelez GET /public/v1/collaborators?collaboratorForeignErpId=…. Les autres
champs sont ceux de contract à l’embauche :
curl https://api.puncto.fr/public/v1/contracts \
-H "Authorization: Bearer $PUNCTO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
"workerType": "EMPLOYEE_CDD",
"startDate": "2027-01-04",
"endDate": "2027-06-30",
"cddMotif": "02",
"companyRoleName": "Développeuse backend",
"dpaeDoneByPuncto": false,
"amendment": {
"isCadre": false,
"quotity": {
"type": "HEURE",
"monthlyWorkingHours": 151.67,
"workingPercentage": 100,
"paidContractualOvertimeHours": 0,
"rttContractualOvertimeHours": 0,
"rcrContractualOvertimeHours": 0
},
"conventionalWorkerStatus": "05",
"workerOutsideFranceStatus": "99",
"conventionalPosition": { "type": "ETAM", "position": "2.2" },
"weekDaysWorked": 31,
"grossAnnualSalary": 34000,
"codePcsEse": "478a"
}
}'La réponse 201 renvoie le contrat, avec ses valeurs résolues à sa date de début.
Bon à savoir
- Les autres contrats du collaborateur doivent se terminer avant la date de début. Un contrat sans date de fin (CDI) doit d’abord être clôturé dans Puncto, car l’API ne le permet pas.
- Si un contrat a été laissé en attente de saisie dans Puncto, la requête le complète au lieu d’en créer un second.
- Si un contrat du collaborateur commence déjà le même jour, la réponse est
409avec soncontractId. - Un collaborateur invité à compléter son dossier doit d’abord finir son embauche dans Puncto, sinon
la réponse est
400.
Après la création
- Le collaborateur reçoit son invitation à Puncto sur son email personnel 2 jours avant le début du contrat, ou immédiatement si le début est plus proche.
- Le bulletin du mois en cours est recalculé si le contrat couvre ce mois.
- Si ces envois échouent, la réponse reste
201.
Erreurs
422 : requête invalide
endDatemanquante pour un CDD, un apprentissage ou un stage.- Contrat de professionnalisation (pas encore géré).
- Date hors format
YYYY-MM-DDou inexistante (2026-02-31). codePcsEsemanquant sur un avenant (exigé par la DSN).- Rémunération absente ou
null:amendment.grossAnnualSalarypour un CDI, un CDD ou un mandat social ;amendment.hourlyRate(ouamendment.smoothedMonthlyAmount, gratification lissée) pour un stage ;remunerationPercentagesur chaque avenant d’un apprentissage.
400 : règle de paie non respectée
Le message indique la règle qui bloque. Rien n’est enregistré.
- Salaire au moins égal au minimum Syntec et au SMIC, au prorata du temps de travail. Gratification minimale pour un stage, rémunération minimale de chaque année pour un apprentissage.
- Période d’essai entre la date de début et le maximum conventionnel. Pas de
trialPeriodEndDatepour un stage ou un mandat social. - Un CDD doit avoir un
cddMotif, un stage uninternshipStudieset uninternshipSchool. Un CDI n’a pas deendDate(sa fin se saisit à la clôture). isCadrecohérent avec la position :truepourCADRE,falsepourETAM. Statut conventionnel03ou04pour un cadre,05à07pour un non-cadre.- Mutuelle et prévoyance : contrats de l’entreprise, du bon type, en vigueur à la date de début,
ouverts au statut du salarié (
isCadre), avec une formule (mutuelleForfaitChoice) du contrat. - DPAE par Puncto : NIR ou NIA du collaborateur, et
healthServiceCodesi l’établissement n’a pas encore de code de service de santé au travail.
Contrat d’apprentissage
Pour un apprentissage, amendment est refusé. Envoyez amendments, avec un avenant par année de
formation qui commence au début de son année. Les années doivent :
- se suivre sans se chevaucher ;
- aller de
startDate(première) àendDate(dernière) ; - avoir chacune exactement un avenant.
Sinon, la réponse est 400. Pour un apprenti qui commence en deuxième année, renseignez seulement
SECOND_YEAR et les années suivantes.
{
"workerType": "APPRENTICESHIP_CONTRACT",
"startDate": "2026-09-01",
"endDate": "2028-08-31",
"apprenticeshipFormationLevel": "06",
"apprenticeshipFormationYearsPeriods": {
"FIRST_YEAR": { "startDate": "2026-09-01", "endDate": "2027-08-31" },
"SECOND_YEAR": { "startDate": "2027-09-01", "endDate": "2028-08-31" }
},
"amendments": [
{
"apprenticeshipFormationYear": "FIRST_YEAR",
"remunerationPercentage": 53,
"remunerationReference": "SMIC"
// + les champs de amendment : isCadre, quotity, codePcsEse…
},
{
"apprenticeshipFormationYear": "SECOND_YEAR",
"remunerationPercentage": 61,
"remunerationReference": "SMIC"
// + les champs de amendment
}
],
// Facultatif : jours en formation, qui décalent la fin de la période d’essai
"apprenticeshipCalendar": { "schoolDays": ["2026-09-07", "2026-09-08"] }
}Relire les contrats
- Lister les contrats renvoie tous les contrats de
l’entreprise (terminés, à venir et en cours de création compris), avec avenants, périodes
d’essai, clôture et affiliations. Filtres : collaborateur,
workerType[],activationStatus[],activeAt. - Consulter un contrat renvoie le contrat par son identifiant
Puncto. Avec
matchingBy, il renvoie le contrat en vigueur d’un collaborateur, au formatApiContractFull. C’est ainsi que vous retrouvez l’identifiant Puncto à partir du vôtre.matchingBy=BY_PUNCTO_CONTRACT_IDest déprécié, car il renvoie le contrat en vigueur du collaborateur, qui n’est pas forcément celui demandé. referenceDatefixe la date de résolution de l’avenant en vigueur (currentAmendment) et de l’établissement (establishmentId). Par défaut, c’est la date du jour, ou la date de début si le contrat n’a pas encore commencé.