Guida all'API di ingestione dei dipendenti

Questo documento descrive i campi dell'ingestione dei dipendenti dal punto di vista di un team di integrazione lato cliente o di terze parti. Si concentra sul significato di ciascun campo, sugli effetti su codeto plan e codeto report e sui valori che richiedono particolare attenzione durante la preparazione dei dati.

L'ingestione crea o aggiorna dipendenti e i loro contratti. I campi legati al contratto possono essere dipendenti dal tempo: quando un valore cambia nel tempo, indicalo con il periodo di validità corretto, in modo che codeto plan e codeto report possano applicarlo alle settimane, ai rapporti, ai saldi e alle viste di pianificazione corretti.

Panoramica del DTO

L'ingestione dei dipendenti accetta uno o più dipendenti. Ogni dipendente dispone di campi al livello superiore e di uno o più contratti collegati. I campi contrassegnati come VersionableProperty<T> sono liste di valori con periodi di validità, come descritto nella sezione successiva.

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;
};

Attributi versionabili

Alcuni campi sono versionabili, ovvero il loro valore può cambiare nel tempo e codeto plan o codeto report possono dover sapere quale valore era valido in una data specifica. Un campo versionabile va quindi inviato con il periodo di efficacia corretto ogniqualvolta il sistema sorgente supporti modifiche storiche o future.

Ogni versione è identificata dalla sua data validFrom. Questa data definisce il primo giorno in cui il valore si applica. Il sistema calcola automaticamente i confini di validità a partire dalla sequenza delle date validFrom: una versione è valida dal suo validFrom fino al giorno precedente al validFrom della versione successiva, oppure a tempo indeterminato se non esiste alcuna versione successiva.

Ad esempio, se un dipendente cambia centro di costo il 2026-04-01, invia il vecchio centro di costo come versione con il suo validFrom originale e il nuovo centro di costo come seconda versione con validFrom: "2026-04-01". Il sistema considererà il vecchio valore valido fino al 2026-03-31 incluso e il nuovo valore a partire dal 2026-04-01. In questo modo, rapporti, saldi, voci di pianificazione e documenti di archivio precedenti continueranno a utilizzare il valore corretto al relativo momento.

Nota sulle convenzioni di data

I periodi di validità dei campi versionabili sono derivati dalle date validFrom come descritto sopra (il periodo di efficacia della versione precedente termina il giorno prima del successivo validFrom). Questa non è la stessa convenzione di workingPeriods, dove endDate è inclusivo, vedi la sezione workingPeriods per quel caso.

Campi del dipendente

employeeId

Identificatore univoco del dipendente nel sistema sorgente.

Utilizza un valore stabile che non cambi durante il ciclo di vita del dipendente. codeto plan e codeto report utilizzano questo identificatore per riconoscere lo stesso dipendente in ingestioni successive.

Il valore deve essere globalmente univoco nell'intero ambiente del cliente.

Esempi:

• Utilizza il numero di matricola dei dati anagrafici HR se rimane stabile anche dopo cambi di nome, reparto o contratto.
• Gli indirizzi e-mail sono di solito meno adatti, perché possono cambiare dopo un matrimonio, un rebranding o una migrazione di account.

firstName

Nome legale del dipendente o riportato nel sistema sorgente.

Questo nome è utilizzato per visualizzazione, ricerca e identificazione del dipendente. In codeto plan, gli utenti possono gestire un nome visualizzato separato che può apparire al suo posto in alcune viste. In codeto report, il nome ingerito rimane il valore sorgente rilevante per la visualizzazione e il reporting.

firstName è versionabile: invia ogni nome storico come versione separata con la data in cui è diventato effettivo se il sistema sorgente tiene traccia delle modifiche del nome nel tempo. Una singola versione con il nome attuale è sufficiente in assenza di storico.

Esempi:

• Se il sistema sorgente cambia firstName da Jon a Jonathan il 2026-03-01, invia il vecchio valore con il suo validFrom originale e una seconda versione con value: "Jonathan" e validFrom: "2026-03-01".
• Se gli utenti di codeto plan mantengono un nome visualizzato come John, tale nome può apparire nelle viste di pianificazione, mentre codeto report continua a utilizzare il nome ingerito.

lastName

Cognome legale del dipendente o riportato nel sistema sorgente.

Questo cognome è utilizzato insieme al nome per visualizzazione, ricerca, viste di rapporto e documenti archiviati. Come per firstName, codeto plan può supportare un nome visualizzato separato, mentre codeto report si basa principalmente sul valore ingerito.

lastName è versionabile allo stesso modo di firstName: invia ogni cognome storico come versione propria con il validFrom appropriato se il sistema sorgente tiene traccia delle modifiche di cognome (ad es. dopo un matrimonio).

Esempi:

• Se il cognome di un dipendente cambia, aggiorna questo campo affinché le future viste di rapporto e i documenti di archivio utilizzino il nuovo cognome.
• Mantieni stabili gli identificatori storici del dipendente quando il cognome cambia; non creare un nuovo dipendente solo perché il cognome è cambiato.

username

Login o nome account del dipendente, se disponibile.

Questo campo è memorizzato a fini di identificazione e per un possibile uso a valle. Attualmente non influenza pianificazione, reporting, saldi o approvazioni.

username è versionabile: invia ogni login storico come versione propria con la data in cui è diventato effettivo se il sistema sorgente tiene traccia delle modifiche di login. Altrimenti è sufficiente una singola versione con il valore attuale.

language

Lingua preferita del dipendente.

Questo campo influenza le comunicazioni rivolte al dipendente, ad esempio le notifiche. In codeto report influenza anche la lingua dei documenti di archivio del dipendente. Indica un valore corrispondente alla lingua in cui il dipendente deve ricevere le comunicazioni ufficiali o operative.

I valori accettati sono de (tedesco), fr (francese), it (italiano) ed en (inglese), secondo la convenzione ISO 639 in minuscolo.

Esempi:

• Utilizza de per un dipendente che deve ricevere notifiche in tedesco e documenti di archivio codeto report in tedesco.
• Utilizza fr per un dipendente che lavora in una filiale francofona se la sua comunicazione ufficiale deve avvenire in francese.

contracts

Elenco dei contratti che appartengono al dipendente.

Un dipendente ha bisogno di almeno un contratto valido per apparire in codeto plan e codeto report. I contratti definiscono l'appartenenza organizzativa del dipendente, quando è attivo, come viene calcolato il tempo di lavoro, quali regole di reporting si applicano e quali saldi sono visualizzati.

Esempi:

• Un dipendente con un contratto in corso ha di solito una sola voce contrattuale con un periodo di lavoro attivo.
• Un dipendente che è passato da una filiale a un'altra può avere due contratti, ciascuno con la propria filiale e il proprio periodo di lavoro.
• Un dipendente che si è dimesso e successivamente è stato riassunto può avere periodi di lavoro o contratti separati, a seconda di come il sistema HR del cliente modella la riassunzione.

Campi del contratto

contractId

Identificatore univoco del contratto.

Utilizza un valore stabile che resti uguale fra le ingestioni dello stesso contratto. codeto plan e codeto report utilizzano l'identificatore del contratto per collegare le voci di pianificazione, le prenotazioni, i rapporti, i saldi, le approvazioni e i documenti di archivio al contratto corretto. Modificarlo scollega i nuovi dati dallo storico di pianificazione o di reporting esistente.

Il valore deve essere globalmente univoco nell'intero ambiente del cliente, non solo univoco per dipendente.

Esempi:

• Utilizza il numero di contratto HR se è univoco e resta stabile attraverso i cambiamenti di paga e organizzativi.
• Non riutilizzare lo stesso contractId per un contratto rinnovato se il vecchio e il nuovo contratto devono mantenere storici di reporting o di saldo separati.

subsidiaryId

Identificatore della filiale o dell'unità aziendale a cui appartiene il contratto.

Si tratta di uno dei campi di scoping più importanti. Determina la configurazione aziendale applicabile al contratto, comprese le regole sul tempo di lavoro, i calendari festivi, le impostazioni dei rapporti, il comportamento di arrotondamento e i confini di autorizzazione.

In codeto plan, la filiale influenza chi può visualizzare o modificare il dipendente e quale contesto organizzativo di tempo di lavoro viene utilizzato. In codeto report, influenza il momento in cui il dipendente appare nel reporting, le regole applicate ai rapporti e le informazioni aziendali presenti nei documenti di archivio.

Esempi:

• Se un dipendente passa dalla filiale CH01 alla CH02, è necessario un nuovo contratto che faccia riferimento a CH02. subsidiaryId non è versionabile, quindi un cambio di filiale non può essere espresso come nuova versione sul contratto esistente.
• Se vengono utilizzate autorizzazioni basate sulla filiale, la filiale assegnata fa parte del contesto di controllo accessi.

costCenterIds

Centri di costo assegnati al contratto.

Utilizza questo campo per attribuire il dipendente o il contratto a uno o più centri di costo. Questi valori sono utilizzati per filtri, viste specifiche per centro di costo, riepiloghi dei rapporti, esportazioni e documenti di archivio.

Esempi:

• Assegna un solo centro di costo quando il lavoro del dipendente appartiene a una singola unità contabile.
• Assegna più centri di costo se la configurazione di reporting del cliente prevede che il contratto sia visibile sotto più filtri di centro di costo.
• Aggiorna il valore quando il dipendente passa a un'altra unità contabile, in modo che i futuri rapporti ed esportazioni utilizzino la corretta attribuzione.

employmentLevel

Percentuale di occupazione del contratto, di solito da 0 a 100.

Questo valore è mostrato come metadato del contratto e può essere utilizzato per filtrare o raggruppare i dipendenti. Rappresenta la percentuale di occupazione concordata. Per i calcoli del tempo di lavoro e di reporting, indica le ore effettivamente attese per ciascun giorno della settimana in workingPattern. Il modello orario fornito non viene normalizzato in base alla percentuale di occupazione.

Esempi:

• Un dipendente a tempo pieno viene tipicamente inviato come 100.
• Un dipendente al 60% viene tipicamente inviato come 60, mentre workingPattern deve comunque contenere le ore effettive attese per ciascun giorno della settimana.

apprenticeshipYear

Anno di apprendistato del dipendente, se rilevante.

Questo campo è memorizzato come metadato del contratto. Attualmente non modifica il comportamento di codeto plan né di codeto report, ma può essere utile per la visualizzazione, le esportazioni o esigenze di integrazione future.

salaryType

Categoria salariale del contratto.

I valori accettati sono S per i dipendenti pagati a ore e M per i dipendenti con stipendio mensile.

Il campo distingue i dipendenti pagati a ore da quelli con stipendio mensile. Questo è rilevante soprattutto in codeto report:

• i dipendenti pagati a ore possono essere gestiti diversamente per giorni festivi, saldi e validazione delle assenze;
• i dipendenti con stipendio mensile devono in genere seguire le ore obiettivo configurate e le regole di reporting.

Il comportamento di pianificazione di codeto plan attualmente non viene modificato da questo campo.

Esempi:

• Utilizza S per i dipendenti i cui giorni festivi e saldi devono seguire le regole dei dipendenti pagati a ore.
• Utilizza M per i dipendenti i cui rapporti devono essere verificati rispetto alle ore obiettivo regolari.

roleId

Ruolo assegnato al contratto.

In codeto plan, il ruolo aiuta a classificare i dipendenti nelle viste di pianificazione e può influire su quali dipendenti compaiono nelle selezioni basate sul ruolo. In codeto report, il ruolo è mostrato come informazione contrattuale nelle viste e nei documenti relativi ai rapporti.

Questo campo non definisce di per sé il routing di approvazione dei rapporti. Il comportamento di approvazione dipende dalle responsabilità di reporting e di progetto configurate dal cliente.

Esempi:

• Assegna un ruolo come capo progetto o capo cantiere se codeto plan deve includere il dipendente nelle selezioni di pianificazione basate sul ruolo.
• Aggiorna il ruolo a partire dalla data di efficacia quando un dipendente cambia funzione, in modo che le visualizzazioni di pianificazione e di rapporto mostrino il ruolo attuale corretto.

employeeCategory

Categoria dipendente specifica del cliente.

Questo campo è memorizzato come metadato del contratto. Attualmente non modifica direttamente il comportamento di codeto plan né di codeto report, ma può essere utile per esportazioni, classificazione o filtri futuri.

workingPattern.monday fino a workingPattern.sunday

Ore di lavoro attese per ciascun giorno della settimana.

Questo è il gruppo di campi centrale per il calcolo delle ore obiettivo. Indica il tempo di lavoro effettivamente atteso per ciascun giorno della settimana per questo contratto, ovvero il piano concordato come dovrebbe apparire giorno per giorno. Non scalare questi valori in base a employmentLevel; vengono utilizzati così come forniti, senza normalizzazione. Ad esempio, se un dipendente part-time lavora quattro ore il lunedì, il valore del lunedì deve essere quattro ore, non il valore predefinito a tempo pieno dell'azienda.

In codeto plan, il modello orario influenza l'utilizzazione e i calcoli relativi alle politiche. Potrebbe non modificare visivamente ogni visualizzazione del calendario di pianificazione, perché alcune rappresentazioni del calendario si basano sulle impostazioni del tempo di lavoro a livello di filiale.

In codeto report, il modello orario determina le ore attese, i riepiloghi dei rapporti, le segnalazioni di approvazione, i controlli relativi a straordinari o GAV, i totali dei documenti di archivio e se i giorni sono considerati lavorativi.

Esempi:

• Un modello settimanale a tempo pieno potrebbe essere lunedì-venerdì 8, sabato 0, domenica 0.
• Un dipendente al 60% che lavora lunedì, martedì e giovedì può essere inviato come 8, 8, 0, 8, 0, 0, 0.
• Un dipendente che non lavora mai il mercoledì può avere il mercoledì impostato a 0.

workingPeriods

Intervalli di date durante i quali il contratto è attivo.

Ogni periodo di lavoro ha una startDate e una endDate inclusiva. I periodi definiscono quando il dipendente può essere pianificato, quando sono attesi i rapporti e quale contratto si applica per una data specifica.

In codeto plan, i periodi di lavoro definiscono gli intervalli di date in cui il dipendente è disponibile sulla timeline di pianificazione e può ricevere prenotazioni.

In codeto report, i periodi di lavoro determinano se i rapporti vengono creati o mostrati per una settimana, quale contratto riceve il rapporto, quale configurazione di filiale si applica e quali informazioni aziendali appaiono nei documenti di archivio.

Utilizza periodi separati quando il dipendente deve essere inattivo tra due fasi contrattuali attive.

Esempi:

• Un contratto in corso può avere una startDate e nessuna fine significativa oltre il periodo di impiego attivo, a seconda del formato di ingestione concordato con il cliente.
• Un contratto attivo dal 2026-01-01 al 2026-06-30 deve rendere il dipendente pianificabile e rapportabile solo all'interno di tale intervallo.
• Se il rapporto di lavoro si interrompe per un congedo non retribuito, utilizza periodi separati solo se il dipendente non deve essere pianificato né tenuto a rapportare durante l'interruzione.

Campi delle componenti salariali

salaryComponents.controllingCode

Codice di controllo di gestione o contabile del contratto.

Questo campo è memorizzato per finalità di utilizzo finanziario, contabile, di esportazione o di integrazione a valle. Attualmente non modifica il comportamento di codeto plan né di codeto report. Può influenzare i payload in uscita che includono informazioni finanziarie o di controllo di gestione.

Esempi:

• Utilizza il codice di controllo di gestione previsto dall'esportazione di paga, ERP o finanziaria del cliente.
• Aggiorna il valore quando l'attribuzione finanziaria cambia e le esportazioni future devono utilizzare il nuovo codice.

salaryComponents.billingRate

Tariffa di fatturazione associata al contratto.

Questo campo è memorizzato per finalità di fatturazione, contabilità, esportazione o integrazione a valle. Attualmente non modifica il comportamento di codeto plan né di codeto report. Può influenzare i payload in uscita che includono informazioni di fatturazione o di tariffa.

Esempi:

• Indica la tariffa oraria o contrattuale che le esportazioni di fatturazione a valle devono ricevere.
• Aggiorna il valore a partire dalla data di efficacia di un cambio di tariffa.

salaryComponents.overtimePayCode

Codice che indica se la gestione degli straordinari è attiva per il contratto. Valori numerici inferiori a 5 attivano la gestione degli straordinari; valori pari a 5 o superiori la disattivano.

codeto report utilizza questa informazione per decidere se applicare supplementi automatici legati agli straordinari, segnalazioni o comportamenti di saldo. Un valore che disattiva gli straordinari può spostare il dipendente in una modalità di reporting diversa, in cui le deviazioni dalle ore obiettivo vengono trattate diversamente.

Il comportamento di pianificazione di codeto plan attualmente non viene modificato da questo campo.

Esempi:

• Utilizza un valore inferiore a 5 per i dipendenti il cui lavoro ulteriore ammissibile deve contribuire alla gestione degli straordinari in codeto report.
• Utilizza un valore pari a 5 o superiore per i dipendenti le cui deviazioni dalle ore obiettivo devono essere trattate secondo le regole non-straordinari o di partecipazione agli utili del cliente.

salaryComponents.billingRateMileage

Tariffa di fatturazione chilometrica associata al contratto.

Questo campo è memorizzato per finalità di fatturazione, contabilità, esportazione o integrazione a valle. Attualmente non modifica il comportamento di codeto plan né di codeto report. Può influenzare i payload in uscita che includono fatturazione chilometrica o rimborso.

Esempi:

• Indica la tariffa chilometrica prevista dall'esportazione di fatturazione o rimborso del cliente.
• Aggiorna il valore quando la tariffa chilometrica rimborsata cambia.

salaryComponents.vehicleBillingType

Categoria di fatturazione veicolo. I valori numerici accettati sono:

• 0: nessuna fatturazione veicolo
• 1: fatturazione veicolo privato
• 2: fatturazione veicolo aziendale

Il campo è memorizzato per finalità di fatturazione, contabilità, esportazione o integrazione a valle. Attualmente non modifica il comportamento di codeto plan né di codeto report.

Esempi:

• Utilizza 1 quando i chilometri devono essere associati a un veicolo privato.
• Utilizza 2 quando i chilometri devono essere associati a un veicolo aziendale.
• Utilizza 0 quando non deve essere applicata alcuna fatturazione veicolo.

salaryComponents.dailyAllowance

Indicatore che specifica se le regole di indennità giornaliera si applicano al contratto.

codeto report utilizza questo valore per decidere se generare supplementi dipendenti dall'indennità giornaliera per questo contratto.

Il comportamento di pianificazione di codeto plan attualmente non viene modificato da questo campo.

Esempi:

• Attiva questo campo per i dipendenti che devono ricevere supplementi dipendenti dall'indennità giornaliera quando i loro rapporti soddisfano le condizioni configurate.
• Disattivalo per i dipendenti che non devono mai ricevere tali supplementi, anche se altre condizioni di lavoro rapportate corrispondono.

salaryComponents.vacationBalanceLastPayRun

Saldo ferie riportato dall'ultima elaborazione paghe, espresso in ore.

Questo è il punto di partenza per i calcoli del saldo ferie in codeto report. codeto report aggiunge a questo valore di base i successivi utilizzi, le correzioni e i diritti di ferie.

codeto plan attualmente non visualizza né calcola i saldi ferie.

Esempi:

• Se l'elaborazione paghe si è chiusa con 42 ore di ferie residue, invia 42 come riporto in modo che codeto report parta da quel saldo.
• Se prima del passaggio è già stata applicata una correzione nella paga, invia il saldo residuo corretto invece del valore precedente alla correzione.

salaryComponents.overtimeBalanceLastPayRun

Saldo straordinari riportato dall'ultima elaborazione paghe, espresso in ore.

Questo è il punto di partenza per i calcoli del saldo straordinari in codeto report. Le successive ore rapportate, compensazioni e adeguamenti vengono calcolati rispetto a questo valore di base.

codeto plan attualmente non visualizza né calcola i saldi straordinari.

Esempi:

• Se l'elaborazione paghe si è chiusa con 10.5 ore di straordinari, invia 10.5 come saldo iniziale.
• Se il dipendente aveva compensato tutti gli straordinari prima del passaggio, invia 0.

salaryComponents.gavBalanceLastPayRun

Saldo GAV riportato dall'ultima elaborazione paghe, espresso in ore.

Questo è il punto di partenza per i calcoli del saldo GAV in codeto report dove si applica il monitoraggio GAV. I successivi eventi rilevanti e gli adeguamenti vengono calcolati rispetto a questo valore di base.

codeto plan attualmente non visualizza né calcola i saldi GAV.

Esempi:

• Invia il saldo GAV dell'ultima elaborazione paghe quando il dipendente è soggetto al monitoraggio GAV.
• Invia 0 se al momento del passaggio la paga non ha alcun saldo GAV residuo.

salaryComponents.vacationMonthlyAllowance

Diritto mensile alle ferie, espresso in ore.

codeto report utilizza questo valore per calcolare il diritto alle ferie nel tempo, comprese le proiezioni pro-rata per il resto dell'anno basate sui periodi di lavoro attivi del dipendente. Valori errati influiscono sui saldi ferie, sulla proiezione del diritto alle ferie, sui riepiloghi dei saldi e sui dettagli di ferie mostrati in codeto report.

codeto plan attualmente non visualizza né calcola i diritti alle ferie.

Esempi:

• Se il dipendente matura 14 ore di ferie al mese, invia 14.
• Per un dipendente part-time, invia il diritto mensile già proporzionato se il sistema paghe del cliente calcola il diritto in questo modo.