L'utilizzo delle API è riservato a clienti, partner o soggetti autorizzati. Per poter utilizzare le API PEOPLELINK è necessario creare una o più chiavi di accesso, ognuna composta da una serie di informazioni e configurazioni tecniche necessarie sia a tracciare gli utilizzatori e il motivo della creazione, sia per applicare configurazioni e/o limitazioni di accesso.

Tramite la funzionalità Chiavi di accesso per le API, presente nel modulo ADVANCED, puoi creare e gestire tutte le chiavi di accesso di cui necessiti.

Esempio: potresti voler creare una chiave di accesso da utilizzare su un software terzo per la sincronizzazione dei soli dati del timesheet, e un'altra chiave di accesso per integrare unicamente le unità organizzative con un differente servizio aziendale.

L'accesso a questa funzionalità è gestita, al pari di tutte le altre funzionalità di PEOPLELINK, ovvero tramite i Ruoli autorizzativi.

 Ti consigliamo di prestate la massima attenzione agli operatori a cui fornisci l'accesso, sia in lettura sia in scrittura.

Creare una nuova chiave di accesso alle API

Utilizza il pulsante Gestisci - Crea per avviare la procedura di creazione di una nuova chiave di accesso. La procedura di creazione è composta da due fasi distinte.

La prima fase prevede la compilazione delle informazioni fondamentali, ovvero lo username e la password da utilizzare per la richiesta del Token ACS oltre ai riferimenti tecnici.

Lo Userame ha una lunghezza minima di 10 caratteri, fino ad un massimo di 20 e deve essere univoco a livello globale.

La Password è sempre e obbligatoriamente generata da PEOPLELINK, ma può essere rigenerata più volte prima di essere salvata.

 La password viene criptata e protetta al momento del salvataggio e non potrà essere recuperata in nessun modo. Va quindi copiata con l'apposito tasto alla destra della casella di testo e memorizzarla in un luogo sicuro prima di salvare l'utenza.

La descrizione, ovvero il motivo per cui viene creata la chiave di accesso, e i dati del referente sono obbligatori.

Il rate limit è fisso e i campi sono sempre disabilitati. I valori vengono ereditati dalle policy globali di PEOPLELINK. Per approfondimenti su cosa è e come funziona un rate limit fare riferimento ai Concetti di base.

Una volta che tutti i campi sono compilati si può procedere al salvataggio utilizzando il pulsante Salva. A seguire, utilizzando il pulsante Gestisci - Modifica, potrai avviare la modifica della chiave di accesso appena creata al fine procedere con la fase 2, ovvero l'inizializzazione delle ApiKey di lettura e/o scrittura, insieme ad eventuali limitazioni specifiche.

Le API di PEOPLELINK prevedono una differenziazione tra gli endpoint che consentono l'accesso in lettura rispetto agli endpoint di scrittura. Per generare la rispettiva ApiKey è necessario cliccare sul pulsante Genera Key in corrispondenza della rispettiva casella di testo. L'ApiKey può essere rigenerata più volte, ma tutte le eventuali versioni precedenti vengono annullate e sostituite sempre da quella nuova.

Di default, tutti gli endpoint sono abilitati per essere utilizzati. E' possibile applicare delle restrizioni agli endpoint abilitati sulla specifica chiave di accesso che si sta modificando utilizzando i dropdown Endpoint abilitati in lettura ed Endpoint abilitati in scrittura per selezionare cosa può essere utilizzato. Per indentificare cosa fa ogni endpoint e quali sono le sue caratteristiche, fare riferimento allo swagger.

Nel caso in cui siano abilitati, in lettura, uno o più endpoint che operano sugli eventi anagrafici, sarà obbligatorio anche indicare un Profilo amministrativo degli eventi anagrafici, il cui scopo è quello di applicare delle limitazioni ai dati anagrafici che possono essere letti nelle API (es. dati retributivi, indirizzi, formazione, visite mediche, etc.). Nel caso non vuoi applicare nessuna limitazione, dovrai obbligatoriamente selezionare la voce Non applicare nessun Profilo amministrativo degli eventi anagrafici.

Un ulteriore limitazione che puoi applicare alle chiavi di accesso alle API è relativa agli indirizzi IP del chiamante. Il campo IP Whitelist ti consente di indicare gli indirizzi IP abilitati a chiamare gli endpoint associati a questa chiave di accesso. Puoi indicare singoli indirizzi o range di IP, sia in formato IPV4 che IPV6.

Una volta che tutti i campi sono compilati si può procedere al salvataggio utilizzando il pulsante Salva.

Modificare le limitazioni e rigenerare le ApiKey di una chiave di accesso

Per modificare le limitazioni oppure per rigenerare le ApiKey di una chiave di accesso alle API premi sul pulsante Gestisci - Modifica.

Lo Username e la descrizione non sono mai modificabili, mentre la password non è mai visibile dopo che la chiave di accesso è stata creata e salvata.

Tutte le altre configurazioni, ad eccezione del rate limit, sono modificabili e rigenerabili in qualsiasi momento. Le regole e le logiche di funzionamento sono le stesse indicate nella fase della creazione di un nuova chiave di accesso.

Modificare la password di una chiave di accesso

Puoi modificare la password di una chiave di accesso alle API rigenerandola.

Così come avviene in fase di creazione di una nuova chiave di accesso, la Password è sempre e obbligatoriamente generata da PEOPLELINK, ma può essere rigenerata più volte prima di essere salvata.

 La password viene criptata e protetta al momento del salvataggio e non potrà essere recuperata in nessun modo. Va quindi copiata con l'apposito tasto alla destra della casella di testo e memorizzarla in un luogo sicuro prima di salvare il cambio password.

Il sistema distingue gli accessi API in base alla tipologia di operazione da eseguire, prevedendo due chiavi distinte:

·         UniversaRead, dedicata agli endpoint in lettura

·         UniversaWrite, dedicata agli endpoint in scrittura.

Gli endpoint associati alla chiave UniversaRead permettono esclusivamente il recupero di dati già presenti nel sistema PEOPLELINK. Si tratta quindi di API pensate per consultare informazioni, esportare dati o alimentare sistemi esterni, senza apportare modifiche ai dati presenti nell'impianto.

Gli endpoint associati alla chiave UniversaWrite, invece, permettono l'invio di dati verso PEOPLELINK con finalità di creazione, aggiornamento o, dove previsto, eliminazione. Le API di scrittura non operano come semplici chiamate dirette di salvataggio, ma sfruttano lo stesso sistema interno di import avanzato disponibile nel modulo DOCKS, già utilizzato per gli import da file.

Questo significa che i tracciati disponibili per la scrittura via API sono gli stessi previsti dagli import avanzati del portale, con la differenza che:

·         tramite interfaccia DOCKS i dati vengono forniti mediante file Excel

·         tramite API i dati vengono forniti in formato JSON.

La logica di validazione, elaborazione e controllo rimane coerente con quella dell'import avanzato. Ogni richiesta di scrittura viene analizzata e validata formalmente; se i dati risultano corretti, l'elaborazione viene inserita in una coda dedicata ed eseguita in modalità asincrona. Sarà poi possibile consultare lo stato dell'elaborazione tramite un apposito endpoint.

Le API di scrittura seguono una logica all-or-nothing: se durante la validazione o l'elaborazione viene rilevato anche un solo errore, l'intero import viene annullato e nessun dato viene scritto su PEOPLELINK. Gli import eseguiti tramite API, sia conclusi correttamente sia terminati con errori, possono essere consultati anche dal modulo DOCKS per un periodo determinato, con la possibilità di verificarne l'esito e i dati elaborati.

In conclusione, la chiave UniversaRead abilita l'accesso ai dati in sola consultazione, con model in response specifici per ogni endpoint, mentre la chiave UniversaWrite abilita operazioni di scrittura controllate, validate e tracciate attraverso il motore di import avanzato di PEOPLELINK, condiviso con quello in interfaccia di DOCKS.

Il set di API indicate come Import avanzato e raccolte, nello swagger, sotto il tag ALL (Scrittura) rappresentano il canale ufficiale attraverso cui software esterni possono scrivere dati all'interno di PEOPLELINK. Si tratta di tre endpoint che lavorano in sequenza e in modo asincrono, formando un flusso completo: scoperta della struttura dati, invio dei dati, monitoraggio dell'elaborazione.

Il principio architetturale di fondo è la generalità: anziché esporre un endpoint per ogni entità, viene offerto un unico punto di ingresso capace di gestire tipologie di import diverse, differenziate dal codice implementativo impl passato nella chiamata. Questo riduce la superficie dell'API pubblica e uniforma il comportamento per tutti i moduli.

Flusso operativo

Il flusso inizia con GetJsonExample, un endpoint di supporto che restituisce un template JSON completo per la tipologia di import desiderata. Il template include i nomi di tutti i fogli previsti, le colonne necessarie e dati mock di esempio. Può essere ottenuto in formato grezzo con commenti esplicativi oppure come JSON valido e immediatamente utilizzabile. Questo endpoint elimina la necessità di consultare documentazione esterna: il contratto dati è autodocumentato e sempre aggiornato.

Una volta costruito il JSON con i dati reali, si procede con SendJson, il cuore del sistema. L'endpoint riceve un body strutturato a fogli, dove ogni foglio rappresenta una categoria di dati e contiene una lista di righe, ognuna a sua volta composta da celle chiave-valore. Prima di qualunque elaborazione, il sistema esegue una pre-validazione sincrona: se il JSON è malformato o contiene errori strutturali, la risposta lo segnala immediatamente senza accodare nulla. Se invece la validazione ha esito positivo, l'import viene messo in coda per l'elaborazione asincrona e viene restituito un identificativo univoco. Il comportamento in caso di sovrapposizione con dati già presenti è controllabile tramite due parametri: l'algoritmo di upsert aggiorna i record esistenti identificandoli univocamente, mentre il flag di upsert parziale permette di scegliere se sovrascrivere il record per intero o aggiornare soltanto i campi effettivamente presenti nel JSON. Per alcuni import, è possibile indicare anche un algoritmo di post-elaborazione specifico, da eseguire al termine dell'import. La gestione è ALL-OR-NOTHING: se anche un solo record presenta un errore in fase di elaborazione, l'intero import viene annullato e nulla viene scritto sul database.

Una volta ottenuto l'identificativo dell'import, il chiamante deve interrogare CheckState per sapere come procede l'elaborazione. L'endpoint riceve l'ID e il codice di tipologia, e restituisce uno stato che può essere: completato con successo, in errore, ancora in coda, oppure sconosciuto. In caso di errore, viene fornita la lista dei messaggi di dettaglio generati durante l'elaborazione, utili per diagnosticare il problema e correggere i dati prima di un nuovo invio.

Parametri in Request da utilizzare con l'import

impl è il parametro che identifica la tipologia di import da eseguire. Ogni valore numerico corrisponde a una specifica entità del sistema e determina quale struttura dati viene attesa nel body, quali validazioni vengono applicate e su quali tabelle di PEOPLELINK verranno scritti i dati. È obbligatorio sia in SendJson che in CheckState, perché il sistema non ha modo di inferire autonomamente di quale entità si tratti. In sostanza, è la chiave che disambigua il comportamento dell'endpoint unico: lo stesso SendJson si comporta in modo completamente diverso a seconda del valore di impl passato.

alg definisce la strategia con cui il sistema gestisce i dati in ingresso rispetto a quelli già presenti sul database. Il valore 1, detto algoritmo di startup, esegue un inserimento diretto senza verificare se esistono già record equivalenti: va usato esclusivamente in fase di prima installazione o in scenari in cui si è certi dell'assenza di duplicati, perché non offre alcuna protezione contro la creazione di record sovrapposti. Il valore 2, detto algoritmo di upsert, è quello pensato per l'uso ordinario: il sistema cerca di identificare univocamente ogni record in ingresso e, se lo trova già presente, lo aggiorna; se non lo trova, lo inserisce come nuovo. Questo approccio è però applicabile solo alle entità che dispongono di un identificativo univoco stabile, poiché senza di esso il sistema non è in grado di stabilire se un record esista già o meno.

partialupsert entra in gioco esclusivamente quando si utilizza l'algoritmo di upsert (alg=2) e controlla la profondità dell'aggiornamento in caso di sovrapposizione. Con il valore false, che è il comportamento predefinito, l'aggiornamento è totale: il record esistente viene completamente riscritto con i dati del JSON, e i campi non presenti nella chiamata vengono azzerati o riportati al valore di default. Con il valore true, l'aggiornamento è invece parziale: vengono toccati soltanto i campi esplicitamente presenti nel JSON, lasciando invariati tutti gli altri. La scelta tra i due comportamenti dipende dall'intenzione del chiamante: se si vuole sincronizzare completamente un record lo si imposta a false, se si vuole aggiornare solo alcuni attributi senza rischiare di perdere dati già presenti lo si imposta a true.

postelab è un parametro opzionale che permette di agganciare, al termine dell'import, un algoritmo di post-elaborazione specifico, cablato all'interno del software PEOPLELINK. Se non viene valorizzato, l'import si conclude con la sola scrittura dei dati. Se invece viene indicato un valore riconosciuto dal sistema, al completamento dell'import viene eseguita automaticamente una logica aggiuntiva configurata lato server, tipicamente utile per aggiornare strutture derivate, ricalcolare aggregati o innescare processi consequenziali all'inserimento dei dati. I valori ammessi non sono liberi ma predefiniti: dipendono dalla tipologia di import (impl) e dalla configurazione dell'installazione.

Conseguentemente a quanto sopra riportato si ricorda che:

·         la lista di tutte le tipologie di import disponibili è consultabile direttamente nello swagger e viene aggiornata ad ogni rilascio

·         l'algoritmo di startup è sempre disponibile per tutti gli import. La disponibilità o meno dell'algoritmo di upsert è indicata nel template JSON di esempio.

Correlazione tra import multipli con l'header X-PL-SyncId

X-PL-SyncId è un header HTTP opzionale, ma fortemente consigliato, che il client genera autonomamente e passa nella chiamata a SendJson. Il valore atteso è un GUID, ma non ci sono specifiche stringenti.

La sua funzione è di correlazione: quando un import logicamente unitario viene spezzato in più chiamate a SendJson - ad esempio, perché il client decide di inviare un'entità alla volta invece che in batch - passando lo stesso GUID in tutte le chiamate si comunica al sistema che quelle operazioni fanno parte di uno stesso contesto. Questo permette di tracciarle e riconciliarle insieme lato PEOPLELINK, anziché trattarle come import indipendenti e scollegati.

Non è quindi un meccanismo di idempotenza nel senso stretto del termine, ovvero non impedisce la doppia esecuzione di una stessa chiamata in caso di retry. Il suo scopo è semantico: fornire un filo conduttore tra operazioni distinte che il chiamante considera parte di uno stesso evento di import.