Skip to content
Navigation

Importer des variables de paie

Route historique : pour une nouvelle intégration, créez et modifiez les variables une à une avec POST /public/v1/payroll-variables et PUT /public/v1/payroll-variables/{payrollVariableId}.

Crée ou met à jour un lot de variables de paie en une seule transaction. Pour les clients qui l’utilisent encore :

  • Une variable invalide (collaborateur ou contrat introuvable, contrôle de saisie échoué) est ignorée et listée dans errors : vérifiez errors, même avec une réponse 200.
  • Un foreignErpId présent plusieurs fois dans le lot est refusé à chaque occurrence.
  • Une variable renvoyée à l’identique, justificatif compris, n’est pas réécrite et compte dans unchangedCount. Si seul le justificatif change, il est remplacé. Dans les deux cas, ni recalcul ni saisie tardive.
  • Une variable importée garde son contrat : désignée sur un autre, elle est refusée (supprimez-la puis réimportez-la) ; désignée par son collaborateur sans eventDate, elle y reste tant qu’il couvre son mois de paie.
  • Jamais remplacées : astreintes, heures d’une feuille de temps, intéressement, prime de vacances ou chèques-vacances de la page Primes, indemnités de fin de contrat du mois du solde de tout compte, variables récurrentes. Un abonnement annuel de transport est refusé : créez-le avec POST /public/v1/recurring-variables.
  • primeType n’accepte que les primes saisissables : ni indemnité de fin de contrat, ni prime collective (vacances, PPV, intéressement).

Justificatif : envoyez la requête en multipart/form-data avec un fichier variables[i][proofFile] (pdf, jpg, jpeg, png, webp, heic, txt, csv, xml, json, xlsx, doc, docx, zip). Sans fichier, le justificatif déjà enregistré est retiré.

POST
https://api.puncto.fr/public/v1/payroll-variables/actions/import

Authentification

  • bearerAuth
    HTTP
    requis

Corps de la requête JSON requis

  • variables
    tableau de
    object
    requis
    • status
      PENDING
      ou
      VALIDATED
      ou
      REJECTED
      requis

      Seules les variables VALIDATED entrent dans le bulletin.

      • PENDING : En attente
      • VALIDATED : Accepté
      • REJECTED : Refusé
    • year
      integer
      requis

      Année de paie.

      maximum: 2100 · minimum: 2000
    • month
      integer
      requis

      Mois de paie.

      maximum: 12 · minimum: 1
    • contractMatching
      object
      requis

      Contrat qui porte la variable : celui du collaborateur actif à eventDate, à défaut sur le mois de paie, ou le contrat lui-même avec BY_PUNCTO_CONTRACT_ID (utile quand le collaborateur a deux contrats dans le mois).

      • type
        BY_COLLABORATOR_FOREIGN_ERP_ID
        ou
        BY_PUNCTO_COLLABORATOR_ID
        ou
        BY_PUNCTO_CONTRACT_ID
        requis

        Clé de correspondance utilisée par value.

        • BY_COLLABORATOR_FOREIGN_ERP_ID : value est le foreignErpId du collaborateur
        • BY_PUNCTO_COLLABORATOR_ID : value est l’identifiant Puncto du collaborateur
        • BY_PUNCTO_CONTRACT_ID : value est l’identifiant Puncto du contrat
      • value
        string
        requis

        Identifiant du collaborateur ou du contrat.

      • eventDate
        optionnel
        string

        Date de l’événement, pour choisir parmi plusieurs contrats du mois. Ignorée avec BY_PUNCTO_CONTRACT_ID.

        format: date
    • data
      requis

      Contenu de la variable. La forme dépend de type, et pour TAX_FREE_INDEMNITY de indemnityType.

      One of the following:

      • Prime
      • Heures supplémentaires
      • Jours de télétravail
      • Ajustement des primes de panier
      • Ajustement des titres restaurant
      • Acompte sur salaire
      • Retenue sur salaire
      • Avantage en nature
      • Note de frais
      • Transport personnel
      • Autre indemnité non soumise
    • foreignErpId
      optionnel
      string

      Identifiant de l’élément dans votre système. Réimporter le même foreignErpId met à jour l’élément existant.

    • createdAt
      optionnel
      string

      Date de création. Par défaut, maintenant ; une variable mise à jour garde la sienne.

      format: date-time
    • businessMealParticipants
      optionnel
      tableau de
      object

      Participants d’un repas d’affaires (expenseType MEALS), désignés comme contractMatching. Les titres restaurant du mois de chacun sont réduits ; son contrat doit être en vigueur à la date de la dépense.

      La réduction s’applique dès l’enregistrement, quel que soit le statut de la note : envoyez les participants avec une note VALIDATED et retirez-les d’une note refusée. Sur un mois clôturé, c’est une saisie tardive sur la paie de chaque participant.

      Absent, les participants enregistrés sont conservés ; une liste vide les retire. Si la note change de mois de paie, ils la suivent avec leur réduction.

      • type
        BY_COLLABORATOR_FOREIGN_ERP_ID
        ou
        BY_PUNCTO_COLLABORATOR_ID
        ou
        BY_PUNCTO_CONTRACT_ID
        requis
        • BY_COLLABORATOR_FOREIGN_ERP_ID : value est le foreignErpId du collaborateur
        • BY_PUNCTO_COLLABORATOR_ID : value est l’identifiant Puncto du collaborateur
        • BY_PUNCTO_CONTRACT_ID : value est l’identifiant Puncto du contrat
      • value
        string
        requis

        Identifiant du participant ou de son contrat.

  • disableIdempotency
    optionnel
    boolean

    Rend foreignErpId facultatif : chaque élément est alors créé, même s’il a déjà été importé.

    default: false

Retour

200

Bilan de l’import

JSON
  • createdCount
    integer
    requis

    Éléments créés.

  • modifiedCount
    integer
    requis

    Éléments existants mis à jour.

  • errors
    tableau de
    string
    requis

    Un message par élément ignoré ; les autres sont importés.

  • unchangedCount
    integer
    requis

    Variables renvoyées à l’identique, laissées telles quelles.

400

foreignErpId manquant sans disableIdempotency, ou import annulé
JSON
  • error
    string
    requis

    Message lisible, en français.

  • errorCode
    optionnel
    string

    Code stable, sur certaines erreurs.

401

Clé d’API absente, invalide ou révoquée
JSON
  • error
    string
    requis

    Message lisible, en français.

  • errorCode
    optionnel
    string

    Code stable, sur certaines erreurs.

403

Opération hors de l’accès de la clé d’API
JSON
  • error
    string
    requis

    Message lisible, en français.

  • errorCode
    optionnel
    string

    Code stable, sur certaines erreurs.

409

Conflit avec un autre import, rien n’est importé : renvoyez le lot. Un autre import de variables de paie de l’entreprise est en cours, ou un foreignErpId du lot vient d’être importé par un autre appel.
JSON
  • error
    string
    requis

    Message lisible, en français.

  • errorCode
    optionnel
    string

    Code stable, sur certaines erreurs.

422

Paramètres invalides
JSON
  • errors
    tableau de
    object
    requis
    • message
      string
      requis
    • rule
      string
      requis

      Règle de validation en échec.

    • field
      string
      requis

      Chemin du champ, par exemple absences.0.type.

Type to search…

↑↓ navigate↵ selectEsc close