Tramite l'API REST di Altamira è possibile gestire da sistemi esterni le anagrafiche dipendenti e l'intero organigramma (posizioni e assegnazioni dipendente-posizione). Le operazioni vengono eseguite dai sistemi del cliente e i dati aggiornati sono visibili in piattaforma agli utenti finali, che operano in sola lettura sull'interfaccia standard.

Questo articolo è una panoramica: gli endpoint, i payload e le regole specifiche di ciascuna entità sono descritti nei sotto-articoli linkati in fondo.

Approccio

L'API di Altamira è basata su viste: per ogni operazione il cliente crea una vista SceltaCampi sull'entità di riferimento, le assegna un TagName, la espone come API e la chiama in lettura (GET) o scrittura (POST/DELETE) autenticandosi con token JWT. I meccanismi generali sono descritti negli articoli Introduzione, Autenticazione e Come esporre una vista nell'API.

Modello dei dati

Anagrafiche e organigramma sono modellati su tre entità (Dipendenti, Posizioni, Assegnazioni) collegate fra loro tramite gli id primari delle rispettive entità. La struttura, le relazioni e i concetti chiave (direct boss, riporti, posizione vacante, ruolo degli id nei riferimenti, storico) sono spiegati nell'articolo dedicato:

• REST - Modello dati di anagrafiche e organigramma — lettura preliminare consigliata.

Endpoint da predisporre

Per coprire la gestione completa di anagrafiche e organigramma vanno predisposti i seguenti endpoint, ciascuno corrispondente a una vista esposta come API:

Anagrafiche

• Endpoint per lettura delle anagrafiche dipendente.
• Endpoint per scrittura dell'anagrafica dipendente.

Organigramma — codifiche di lookup

• Endpoint per lettura codifica Organigrammi.
• Endpoint per lettura codifica Ruoli.
• Endpoint per lettura codifica Sedi.

Organigramma — posizioni

• Endpoint per lettura posizioni.
• Endpoint per lettura organigramma completo.
• Endpoint per scrittura posizioni ed eliminazione posizioni.

Organigramma — assegnazione dipendenti

• Endpoint per scrittura e chiusura delle assegnazioni dipendenti-posizioni.

Regole comuni a tutti gli endpoint

• Formato date: "2026-04-02T00:00:00Z" (ISO 8601, UTC).
• Campo id: sempre obbligatorio nel payload di scrittura. Va passato a 0 per la creazione di un nuovo record, o all'identificativo del record per l'aggiornamento.
• Struttura del payload: oggetto JSON con proprietà data, contenente un array di oggetti. Ogni oggetto rappresenta un record da creare o aggiornare.
• Nomi dei campi: corrispondono ai TagName dei campi della vista. I nomi indicati negli esempi dei sotto-articoli sono il set minimo per il corretto funzionamento delle scritture e devono essere rispettati. È invece possibile aggiungere ulteriori campi nelle viste, secondo le esigenze del cliente.

Permessi necessari

L'utente con cui l'integrazione si autentica deve avere assegnati al proprio account i permessi di lettura e/o scrittura sulle entità coinvolte. I permessi sono dettagliati in ciascuno dei sotto-articoli. Si consiglia di creare un utente dedicato all'integrazione, con il solo set di permessi strettamente necessari alle operazioni previste.

Sotto-articoli

• REST - Modello dati di anagrafiche e organigramma
• REST - Anagrafica dipendenti via API
• REST - Organigramma e posizioni via API
• REST - Assegnazione dipendenti alle posizioni via API
• REST - Casistiche operative su organigramma via API

Articoli correlati

• Introduzione alle API Altamira
• Autenticazione — generazione e rinnovo token JWT
• Come esporre una vista nell'API
• REST - Esempio chiamata di scrittura
• REST - Esempio chiamata di lettura