Skip to content

Créer des collaborateurs et des contrats

Embaucher un salarié depuis votre SIRH, puis lui créer de nouveaux contrats.

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 est 409 avec le collaboratorId existant, et rien n’est créé.
  • Si le numéro de sécurité sociale est déjà connu dans l’entreprise, la réponse est 409 avec le collaboratorId. Créez alors le contrat avec POST /public/v1/contracts.
  • personalEmail sert à la connexion. Il doit être unique sur tout Puncto, toutes entreprises confondues, sinon la réponse est 422.
  • Sans socialSecurityNumber, sex est obligatoire et Puncto attribue un NTT. "dpaeDoneByPuncto": false est aussi obligatoire, sinon la réponse est 400.
  • Avec un numéro, identityType vaut NIR par défaut (ou NIA), et sex doit 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

Une fois le collaborateur créé :

  • Modifier un collaborateur permet de changer son identité, ses coordonnées, son mode de paiement ou son manager (null le 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 409 avec son contractId.
  • 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

  • endDate manquante pour un CDD, un apprentissage ou un stage.
  • Contrat de professionnalisation (pas encore géré).
  • Date hors format YYYY-MM-DD ou inexistante (2026-02-31).
  • codePcsEse manquant sur un avenant (exigé par la DSN).
  • Rémunération absente ou null :
    • amendment.grossAnnualSalary pour un CDI, un CDD ou un mandat social ;
    • amendment.hourlyRate (ou amendment.smoothedMonthlyAmount, gratification lissée) pour un stage ;
    • remunerationPercentage sur 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 trialPeriodEndDate pour un stage ou un mandat social.
  • Un CDD doit avoir un cddMotif, un stage un internshipStudies et un internshipSchool. Un CDI n’a pas de endDate (sa fin se saisit à la clôture).
  • isCadre cohérent avec la position : true pour CADRE, false pour ETAM. Statut conventionnel 03 ou 04 pour un cadre, 05 à 07 pour 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 healthServiceCode si 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 format ApiContractFull. C’est ainsi que vous retrouvez l’identifiant Puncto à partir du vôtre. matchingBy=BY_PUNCTO_CONTRACT_ID est déprécié, car il renvoie le contrat en vigueur du collaborateur, qui n’est pas forcément celui demandé.
  • referenceDate fixe 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é.

Type to search…

↑↓ navigate↵ selectEsc close