Aller au contenu principal

Guide de l'API d'ingestion des collaborateurs

Ce document explique les champs de l'ingestion des collaborateurs du point de vue d'une équipe d'intégration côté client ou tierce. Il décrit la signification de chaque champ, son influence sur codeto plan et codeto report et les valeurs qui demandent une attention particulière lors de la préparation des données.

L'ingestion crée ou met à jour des collaborateurs et leurs contrats. Les champs liés au contrat peuvent dépendre du temps : lorsqu'une valeur change au fil du temps, transmets-la avec la période de validité correcte afin que codeto plan et codeto report puissent l'appliquer aux bonnes semaines, rapports, soldes et vues de planification.

Aperçu du DTO​

L'ingestion des collaborateurs accepte un ou plusieurs collaborateurs. Chaque collaborateur dispose de champs au niveau supérieur ainsi que d'un ou plusieurs contrats associés. Les champs marqués VersionableProperty<T> sont des listes de valeurs avec périodes de validité, comme décrit dans la section suivante.

type VersionedValue<T> = {
  value: T;
  validFrom: string;
};

type VersionableProperty<T> = VersionedValue<T>[];

type EmployeeIngestPayload = CreateEmployeeDto[];

type CreateEmployeeDto = {
  employeeId: string;
  contracts: CreateContractDto[];
  firstName: VersionableProperty<string>;
  lastName: VersionableProperty<string>;
  username: VersionableProperty<string>;
  language: VersionableProperty<string>;
};

type CreateContractDto = {
  contractId: string;
  subsidiaryId: string;
  costCenterIds: VersionableProperty<string[]>;
  employmentLevel: VersionableProperty<number>;
  apprenticeshipYear: VersionableProperty<string>;
  salaryType: VersionableProperty<string>;
  roleId: VersionableProperty<string>;
  employeeCategory: VersionableProperty<string>;
  workingPattern: WorkingPattern;
  workingPeriods: WorkingPeriod[];
  salaryComponents: SalaryComponents;
};

type WorkingPattern = {
  monday: VersionableProperty<number>;
  tuesday: VersionableProperty<number>;
  wednesday: VersionableProperty<number>;
  thursday: VersionableProperty<number>;
  friday: VersionableProperty<number>;
  saturday: VersionableProperty<number>;
  sunday: VersionableProperty<number>;
};

type WorkingPeriod = {
  startDate: string;
  endDate: string;
};

type SalaryComponents = {
  controllingCode: VersionableProperty<string>;
  billingRate: VersionableProperty<number>;
  overtimePayCode: VersionableProperty<number>;
  billingRateMileage: VersionableProperty<number>;
  vehicleBillingType: VersionableProperty<number>;
  dailyAllowance: VersionableProperty<number>;
  vacationBalanceLastPayRun: number;
  overtimeBalanceLastPayRun: number;
  gavBalanceLastPayRun: number;
  vacationMonthlyAllowance: number;
};

Attributs versionnables​

Certains champs sont versionnables, ce qui signifie que leur valeur peut évoluer dans le temps et que codeto plan ou codeto report peuvent avoir besoin de connaître la valeur valide à une date donnée. Un champ versionnable doit donc être transmis avec la bonne période d'effet dès lors que le système source prend en charge des changements historiques ou datés dans le futur.

Chaque version est identifiée par sa date validFrom. Cette date définit le premier jour à partir duquel la valeur s'applique. Le système calcule automatiquement les limites de validité à partir de la suite des dates validFrom : une version est valable de son validFrom jusqu'à la veille du validFrom de la version suivante, ou indéfiniment s'il n'existe pas de version ultérieure.

Par exemple, si un collaborateur change de centre de coûts le 2026-04-01, transmets l'ancien centre de coûts comme version avec son validFrom d'origine, et le nouveau centre de coûts comme deuxième version avec validFrom: "2026-04-01". Le système considérera l'ancienne valeur comme valable jusqu'au 2026-03-31 inclus et la nouvelle à partir du 2026-04-01. Cela permet aux anciens rapports, soldes, entrées de planification et documents d'archive de continuer à utiliser la valeur correcte à l'époque.

Note sur les conventions de date

Les périodes de validité des champs versionnables sont déduites des dates validFrom comme décrit ci-dessus (la période effective de la version précédente se termine la veille du validFrom suivant). Ce n'est pas la même convention que pour workingPeriods, où endDate est inclusif, voir la section sur workingPeriods pour ce cas.

Champs collaborateur​

employeeId​

Identifiant unique du collaborateur dans le système source.

Utilise une valeur stable qui ne change pas au cours du cycle de vie du collaborateur. codeto plan et codeto report utilisent cet identifiant pour reconnaître le même collaborateur lors d'ingestions ultérieures.

La valeur doit être globalement unique dans l'ensemble de l'environnement client.

Exemples :

  • Utilise le numéro de personnel issu des données de base RH s'il reste stable après des changements de nom, de département ou de contrat.
  • Les adresses e-mail conviennent généralement moins bien, car elles peuvent changer suite à un mariage, un changement de marque ou une migration de comptes.

firstName​

Prénom légal du collaborateur ou tel qu'il figure dans le système source.

Ce prénom est utilisé pour l'affichage, la recherche et l'identification du collaborateur. Dans codeto plan, les utilisateurs peuvent gérer un prénom d'affichage distinct qui peut être affiché à la place dans certaines vues. Dans codeto report, le prénom ingéré reste la valeur source pertinente pour l'affichage et le reporting.

firstName est versionnable : transmets chaque prénom historique comme version distincte avec la date à laquelle il est devenu effectif si le système source suit les changements de nom dans le temps. Une seule version avec le prénom actuel suffit en l'absence d'historique.

Exemples :

  • Si le système source change le firstName de Jon en Jonathan au 2026-03-01, transmets l'ancienne valeur avec son validFrom d'origine et une deuxième version avec value: "Jonathan" et validFrom: "2026-03-01".
  • Si les utilisateurs de codeto plan gèrent un prénom d'affichage tel que John, ce prénom d'affichage peut apparaître dans les vues de planification, alors que codeto report continue d'utiliser le prénom ingéré.

lastName​

Nom de famille légal du collaborateur ou tel qu'il figure dans le système source.

Ce nom est utilisé conjointement avec le prénom pour l'affichage, la recherche, les vues de rapport et les documents archivés. Comme pour firstName, codeto plan peut gérer un nom d'affichage distinct, tandis que codeto report s'appuie principalement sur la valeur ingérée.

lastName est versionnable de la même manière que firstName : transmets chaque nom historique comme version distincte avec le validFrom approprié si le système source suit les changements de nom (p. ex. après un mariage).

Exemples :

  • Si le nom d'un collaborateur change, mets à jour ce champ afin que les futures vues de rapport et les documents d'archive utilisent le nouveau nom.
  • Conserve les identifiants historiques du collaborateur stables lors d'un changement de nom ; ne crée pas un nouveau collaborateur uniquement parce que le nom de famille a changé.

username​

Identifiant de connexion ou nom de compte du collaborateur, le cas échéant.

Ce champ est stocké à des fins d'identification et d'éventuelle utilisation en aval. Il n'a actuellement aucune incidence sur la planification, le reporting, les soldes ou les validations.

username est versionnable : transmets chaque identifiant historique comme version distincte avec la date à laquelle il est devenu effectif si le système source suit les changements d'identifiants. Sinon, une seule version avec la valeur actuelle suffit.

language​

Langue préférée du collaborateur.

Ce champ influence les communications adressées au collaborateur, telles que les notifications. Dans codeto report, il influence également la langue des documents d'archive du collaborateur. Indique une valeur correspondant à la langue dans laquelle le collaborateur doit recevoir les communications officielles ou opérationnelles.

Les valeurs acceptées sont de (allemand), fr (français), it (italien) et en (anglais), conformément à la convention ISO 639 en minuscules.

Exemples :

  • Utilise de pour un collaborateur qui doit recevoir des notifications en allemand et des documents d'archive codeto report en allemand.
  • Utilise fr pour un collaborateur travaillant dans une filiale francophone si sa communication officielle doit se faire en français.

contracts​

Liste des contrats appartenant au collaborateur.

Un collaborateur a besoin d'au moins un contrat valide pour apparaître dans codeto plan et codeto report. Les contrats définissent l'appartenance organisationnelle du collaborateur, sa période d'activité, le mode de calcul du temps de travail, les règles de reporting applicables et les soldes affichés.

Exemples :

  • Un collaborateur ayant un contrat en cours possède en général une seule entrée contractuelle avec une période de travail active.
  • Un collaborateur qui a changé de filiale peut avoir deux contrats, chacun avec sa propre filiale et sa propre période de travail.
  • Un collaborateur parti puis revenu peut avoir des périodes de travail ou des contrats séparés, selon la façon dont le système RH du client modélise le réembauchage.

Champs contrat​

contractId​

Identifiant unique du contrat.

Utilise une valeur stable qui reste identique entre les ingestions du même contrat. codeto plan et codeto report utilisent l'identifiant du contrat pour rattacher les entrées de planification, les bookings, les rapports, les soldes, les validations et les documents d'archive au bon contrat. Le modifier déconnecte de nouvelles données de l'historique de planification ou de reporting préalable.

La valeur doit être globalement unique dans l'ensemble de l'environnement client, et pas seulement par collaborateur.

Exemples :

  • Utilise le numéro de contrat RH s'il est unique et reste stable malgré les changements de paie ou d'organisation.
  • Ne réutilise pas le même contractId pour un contrat renouvelé si l'ancien et le nouveau contrats doivent conserver des historiques de reporting ou de soldes distincts.

subsidiaryId​

Identifiant de la filiale ou de l'unité d'entreprise à laquelle le contrat appartient.

Il s'agit de l'un des champs de cadrage les plus importants. Il détermine la configuration d'entreprise applicable au contrat, y compris les règles de temps de travail, les calendriers de jours fériés, les paramètres de rapport, le comportement d'arrondi et les limites d'autorisation.

Dans codeto plan, la filiale influence qui peut voir ou modifier le collaborateur et quel contexte organisationnel de temps de travail s'applique. Dans codeto report, elle influence le moment où le collaborateur apparaît dans le reporting, les règles appliquées aux rapports et les informations d'entreprise figurant sur les documents d'archive.

Exemples :

  • Si un collaborateur passe de la filiale CH01 à CH02, cela nécessite un nouveau contrat référençant CH02. subsidiaryId n'est pas versionnable, donc un changement de filiale ne peut pas être exprimé comme une nouvelle version sur le contrat existant.
  • Lorsque des permissions basées sur la filiale sont utilisées, la filiale attribuée fait partie du contexte de contrôle d'accès.

costCenterIds​

Centres de coûts assignés au contrat.

Utilise ce champ pour attribuer le collaborateur ou le contrat à un ou plusieurs centres de coûts. Ces valeurs servent au filtrage, aux vues spécifiques par centre de coûts, aux récapitulatifs de rapports, aux exports et aux documents d'archive.

Exemples :

  • Attribue un seul centre de coûts lorsque le travail du collaborateur relève d'une seule unité comptable.
  • Attribue plusieurs centres de coûts si la configuration de reporting du client attend que le contrat soit visible sous plus d'un filtre de centre de coûts.
  • Mets à jour la valeur lorsque le collaborateur change d'unité comptable afin que les futurs rapports et exports utilisent la bonne attribution.

employmentLevel​

Pourcentage d'occupation du contrat, généralement de 0 à 100.

Cette valeur est affichée comme métadonnée du contrat et peut servir au filtrage ou au regroupement des collaborateurs. Elle représente le taux d'occupation convenu. Pour les calculs de temps de travail et de reporting, indique les heures effectivement attendues par jour de la semaine dans workingPattern. Le modèle horaire fourni n'est pas normalisé en fonction du taux d'occupation.

Exemples :

  • Un collaborateur à plein temps est généralement transmis avec 100.
  • Un collaborateur à 60 % est généralement transmis avec 60, tandis que workingPattern doit toujours contenir les heures réellement attendues pour chaque jour de la semaine.

apprenticeshipYear​

Année d'apprentissage du collaborateur, le cas échéant.

Ce champ est stocké comme métadonnée du contrat. Il ne modifie actuellement ni le comportement de codeto plan ni celui de codeto report, mais peut être utile pour l'affichage, les exports ou de futurs besoins d'intégration.

salaryType​

Catégorie salariale du contrat.

Les valeurs acceptées sont S pour les collaborateurs payés à l'heure et M pour les collaborateurs au salaire mensuel.

Ce champ distingue les collaborateurs payés à l'heure de ceux au salaire mensuel. Cela importe surtout dans codeto report :

  • les collaborateurs payés à l'heure peuvent être traités différemment pour les jours fériés, les soldes et la validation des absences ;
  • les collaborateurs au salaire mensuel doivent généralement suivre les heures cibles configurées et les règles de reporting.

Le comportement de planification de codeto plan n'est actuellement pas modifié par ce champ.

Exemples :

  • Utilise S pour les collaborateurs dont les jours fériés et les soldes doivent suivre les règles applicables aux collaborateurs payés à l'heure.
  • Utilise M pour les collaborateurs dont les rapports doivent être contrôlés par rapport aux heures cibles régulières.

roleId​

Rôle assigné au contrat.

Dans codeto plan, le rôle aide à classer les collaborateurs dans les vues de planification et peut influencer les collaborateurs apparaissant dans les sélections basées sur le rôle. Dans codeto report, le rôle est affiché comme information contractuelle dans les vues et documents liés aux rapports.

Ce champ ne définit pas à lui seul le routage de validation des rapports. Le comportement de validation dépend des responsabilités de reporting et de projet configurées par le client.

Exemples :

  • Attribue un rôle tel que chef de projet ou chef de chantier si codeto plan doit inclure le collaborateur dans des sélections de planification basées sur le rôle.
  • Mets à jour le rôle à partir de la date d'effet lorsqu'un collaborateur change de fonction, afin que les affichages de planification et de rapport reflètent le rôle actuel correct.

employeeCategory​

Catégorie de collaborateur spécifique au client.

Ce champ est stocké comme métadonnée du contrat. Il ne modifie actuellement ni le comportement de codeto plan ni celui de codeto report directement, mais peut être utile pour les exports, la classification ou de futurs filtres.

workingPattern.monday à workingPattern.sunday​

Heures de travail attendues pour chaque jour de la semaine.

Il s'agit du groupe de champs central pour le calcul des heures cibles. Indique le temps de travail réellement attendu pour chaque jour de la semaine pour ce contrat, c'est-à-dire le planning convenu tel qu'il doit apparaître jour après jour. Ne mets pas ces valeurs à l'échelle avec employmentLevel ; elles sont utilisées telles quelles, sans normalisation. Par exemple, si un collaborateur à temps partiel travaille quatre heures le lundi, la valeur du lundi doit être de quatre heures, et non la valeur par défaut à plein temps de l'entreprise.

Dans codeto plan, le modèle horaire influence l'utilisation et les calculs liés aux politiques. Il ne modifie pas nécessairement visuellement chaque vue calendrier de planification, car certaines présentations de calendrier reposent sur les paramètres de temps de travail au niveau de la filiale.

Dans codeto report, le modèle horaire détermine les heures attendues, les récapitulatifs de rapport, les avertissements de validation, les contrôles liés aux heures supplémentaires ou à la GAV, les totaux des documents d'archive et le caractère ouvré ou non d'un jour.

Exemples :

  • Un modèle hebdomadaire à plein temps pourrait être : du lundi au vendredi 8, samedi 0, dimanche 0.
  • Un collaborateur à 60 % travaillant le lundi, le mardi et le jeudi peut être transmis comme 8, 8, 0, 8, 0, 0, 0.
  • Un collaborateur qui ne travaille jamais le mercredi peut avoir le mercredi à 0.

workingPeriods​

Plages de dates pendant lesquelles le contrat est actif.

Chaque période de travail comporte une startDate et une endDate inclusive. Les périodes définissent quand le collaborateur peut être planifié, quand des rapports sont attendus et quel contrat s'applique pour une date donnée.

Dans codeto plan, les périodes de travail définissent les plages de dates pendant lesquelles le collaborateur est disponible sur la timeline de planification et peut recevoir des bookings.

Dans codeto report, les périodes de travail déterminent si des rapports sont créés ou affichés pour une semaine donnée, quel contrat reçoit le rapport, quelle configuration de filiale s'applique et quelles informations d'entreprise apparaissent dans les documents d'archive.

Utilise des périodes séparées lorsque le collaborateur doit être inactif entre deux phases contractuelles actives.

Exemples :

  • Un contrat en cours peut comporter une startDate sans fin pertinente au-delà de la période d'emploi active, selon le format d'ingestion convenu avec le client.
  • Un contrat actif du 2026-01-01 au 2026-06-30 ne doit rendre le collaborateur planifiable et rapportable qu'à l'intérieur de cette plage.
  • Si l'emploi est suspendu pour un congé non payé, n'utilise des périodes séparées que si le collaborateur ne doit pas être planifié ni tenu de rapporter pendant l'interruption.

Champs des composantes salariales​

salaryComponents.controllingCode​

Code de contrôle de gestion ou de comptabilité du contrat.

Ce champ est stocké à des fins d'utilisation financière, comptable, d'export ou d'intégration en aval. Il ne modifie actuellement ni le comportement de codeto plan ni celui de codeto report. Il peut influencer les payloads sortants comportant des informations financières ou de contrôle de gestion.

Exemples :

  • Utilise le code de contrôle de gestion attendu par l'export de paie, ERP ou financier du client.
  • Mets à jour la valeur lorsque l'attribution financière change et que les futurs exports doivent utiliser le nouveau code.

salaryComponents.billingRate​

Taux de facturation associé au contrat.

Ce champ est stocké à des fins de facturation, comptables, d'export ou d'intégration en aval. Il ne modifie actuellement ni le comportement de codeto plan ni celui de codeto report. Il peut influencer les payloads sortants comportant des informations de facturation ou de tarif.

Exemples :

  • Indique le taux horaire ou contractuel que les exports de facturation en aval doivent recevoir.
  • Mets à jour la valeur à partir de la date d'effet d'un changement de tarif.

salaryComponents.overtimePayCode​

Code indiquant si la gestion des heures supplémentaires est activée pour le contrat. Les valeurs numériques inférieures à 5 activent la gestion des heures supplémentaires ; les valeurs de 5 ou plus la désactivent.

codeto report utilise cette information pour déterminer si les suppléments automatiques liés aux heures supplémentaires, les avertissements ou le comportement des soldes doivent s'appliquer. Une valeur qui désactive les heures supplémentaires peut faire passer le collaborateur dans un mode de reporting différent où les écarts par rapport aux heures cibles sont traités autrement.

Le comportement de planification de codeto plan n'est actuellement pas modifié par ce champ.

Exemples :

  • Utilise une valeur inférieure à 5 pour les collaborateurs dont les heures supplémentaires éligibles doivent contribuer à la gestion des heures supplémentaires dans codeto report.
  • Utilise une valeur de 5 ou plus pour les collaborateurs dont les écarts d'heures cibles doivent être traités selon les règles de participation aux bénéfices ou hors heures supplémentaires du client.

salaryComponents.billingRateMileage​

Taux de facturation kilométrique associé au contrat.

Ce champ est stocké à des fins de facturation, comptables, d'export ou d'intégration en aval. Il ne modifie actuellement ni le comportement de codeto plan ni celui de codeto report. Il peut influencer les payloads sortants comportant des informations de facturation kilométrique ou de remboursement.

Exemples :

  • Indique le tarif kilométrique attendu par l'export de facturation ou de remboursement du client.
  • Mets à jour la valeur lorsque le tarif kilométrique remboursé change.

salaryComponents.vehicleBillingType​

Catégorie de facturation véhicule. Les valeurs numériques acceptées sont :

  • 0 : pas de facturation véhicule
  • 1 : facturation véhicule privé
  • 2 : facturation véhicule d'entreprise

Ce champ est stocké à des fins de facturation, comptables, d'export ou d'intégration en aval. Il ne modifie actuellement ni le comportement de codeto plan ni celui de codeto report.

Exemples :

  • Utilise 1 lorsque les kilomètres doivent être associés à un véhicule privé.
  • Utilise 2 lorsque les kilomètres doivent être associés à un véhicule fourni par l'entreprise.
  • Utilise 0 lorsqu'aucune facturation véhicule ne doit s'appliquer.

salaryComponents.dailyAllowance​

Indicateur précisant si les règles d'indemnité journalière s'appliquent au contrat.

codeto report utilise cette valeur pour déterminer si des suppléments dépendant de l'indemnité journalière doivent être générés pour ce contrat.

Le comportement de planification de codeto plan n'est actuellement pas modifié par ce champ.

Exemples :

  • Active ce champ pour les collaborateurs qui doivent recevoir des suppléments dépendant de l'indemnité journalière lorsque leurs rapports remplissent les conditions configurées.
  • Désactive-le pour les collaborateurs qui ne doivent jamais recevoir ces suppléments, même si d'autres conditions de travail rapportées correspondent.

salaryComponents.vacationBalanceLastPayRun​

Solde de vacances reporté du dernier traitement de paie, exprimé en heures.

Il s'agit du point de départ pour les calculs du solde de vacances dans codeto report. codeto report ajoute ensuite les utilisations, corrections et droits de vacances ultérieurs à cette valeur de base.

codeto plan n'affiche ni ne calcule actuellement les soldes de vacances.

Exemples :

  • Si le traitement de paie s'est clôturé avec 42 heures de vacances restantes, transmets 42 comme report afin que codeto report parte de ce solde.
  • Si une correction a déjà été appliquée dans la paie avant la bascule, transmets le solde restant après correction plutôt que la valeur antérieure.

salaryComponents.overtimeBalanceLastPayRun​

Solde d'heures supplémentaires reporté du dernier traitement de paie, exprimé en heures.

Il s'agit du point de départ pour les calculs du solde d'heures supplémentaires dans codeto report. Les heures rapportées, compensations et ajustements ultérieurs sont calculés relativement à cette valeur de base.

codeto plan n'affiche ni ne calcule actuellement les soldes d'heures supplémentaires.

Exemples :

  • Si le traitement de paie s'est clôturé avec 10.5 heures supplémentaires, transmets 10.5 comme solde de départ.
  • Si le collaborateur avait compensé toutes ses heures supplémentaires avant la bascule, transmets 0.

salaryComponents.gavBalanceLastPayRun​

Solde GAV reporté du dernier traitement de paie, exprimé en heures.

Il s'agit du point de départ pour les calculs du solde GAV dans codeto report lorsque le suivi GAV s'applique. Les événements pertinents et ajustements ultérieurs sont calculés relativement à cette valeur de base.

codeto plan n'affiche ni ne calcule actuellement les soldes GAV.

Exemples :

  • Transmets le solde GAV du dernier traitement de paie lorsque le collaborateur est soumis au suivi GAV.
  • Transmets 0 si la paie n'a aucun solde GAV restant au moment de la bascule.

salaryComponents.vacationMonthlyAllowance​

Droit mensuel à des vacances, exprimé en heures.

codeto report utilise cette valeur pour calculer le droit aux vacances dans le temps, y compris les projections au prorata pour le reste de l'année à partir des périodes de travail actives du collaborateur. Des valeurs incorrectes affectent les soldes de vacances, la projection du droit aux vacances, les récapitulatifs de soldes et les détails de vacances affichés dans codeto report.

codeto plan n'affiche ni ne calcule actuellement les droits aux vacances.

Exemples :

  • Si le collaborateur acquiert 14 heures de vacances par mois, transmets 14.
  • Pour un collaborateur à temps partiel, transmets le droit mensuel déjà proratisé si le système de paie du client calcule le droit ainsi.
Dernière mise à jour le