Politica di "fair use" degli strumenti di caricamento massivo dati (KB040)

Questo documento descrive la politica di “fair use” degli strumenti di caricamento massivo dati come l’API e i caricamenti di dati in blocco noti come KB020, e include indicazioni relative ai limiti dell’API.

API

L’API di Smartosh è progettata per facilitare l’integrazione e la sincronizzazione dei dati tra la piattaforma Smart OSH e sistemi esterni dei clienti. Il suo scopo è permettere:

Scambio bidirezionale di informazioni tra sistemi aziendali
Aggiornamento automatizzato dei dati da fonti esterne (ERP, HRIS, sistemi di gestione, ecc.)
Query puntuali per integrazione con strumenti di reporting o BI
Sincronizzazione dei dati con altri sistemi dell’organizzazione
Automazione di flussi di lavoro che completino l’uso della piattaforma

Uso non previsto

L’API non è progettata né offerta per:

Creare interfacce utente alternative che sostituiscano significativamente l’uso della piattaforma web di Smart OSH
Sviluppare applicazioni complete che replicano la funzionalità principale di Smart OSH
Sostituire l’accesso normale degli utenti alla piattaforma con accesso esclusivo via API
Estrarre continuamente l’intero database per operare al di fuori di Smart OSH

Principi Generali

L’API di Smart OSH è disponibile per tutti i nostri clienti senza un limite stabilito di query o aggiornamenti, sotto il principio di uso “fair use” delle risorse della piattaforma.

Autenticazione e gestione delle sessioni

L’autenticazione nell’API di SmartOSH avviene tramite HTTP Basic Authentication. Alla prima chiamata, il cliente deve autenticarsi utilizzando le credenziali utente API. Il client HTTP salverà il token risultante dalla HTTP Authentication Challenge e le chiamate successive saranno automaticamente autenticate.

Le credenziali di accesso (utente e password) possono essere create dall’amministratore di SmartOSH dalla console di amministrazione della piattaforma.

Gestione delle sessioni

Quando si usa Basic Authentication è necessario che il client API mantenga la sessione tra le chiamate. Esistono due metodi equivalenti:

Cookie di sessione: Il client HTTP mantiene automaticamente i cookie ricevuti alla prima chiamata.
Header x-session: Il client cattura il valore dell’header x-session ricevuto nella prima risposta e lo reinvia in tutte le chiamate successive.

Se la sessione non viene mantenuta correttamente:

Le chiamate saranno estremamente lente
Può compromettere le prestazioni dell’abbonamento del cliente
Si raggiungerà il limite di sessioni simultanee

Limite di sessioni

L’API ha un limite di 50 identificatori di sessione distinti per utente per ora. Quando si supera questo limite, il servizio rifiuterà le richieste con il messaggio:

“You are using too many sessions. Please make sure that you are reusing your sessions using cookies. For more information please check the reference guide KB008.”

Cause comuni di eccesso di sessioni:

Lo stesso utente API è condiviso da più utenti o sistemi reali
Gli identificatori di sessione non vengono conservati adeguatamente tra le chiamate
Non si stanno riutilizzando i cookie di sessione

Raccomandazioni:

Mantenere la sessione attiva correttamente tramite cookie o header x-session
Se più sistemi necessitano accesso simultaneo, distribuire le richieste tra diversi utenti API
Verificare che il client HTTP sia configurato per preservare i cookie tra le chiamate

Uso previsto

Aggiornamenti dati

L’API è progettata per ricevere solo dati che hanno subito cambiamenti reali. I clienti devono:

Inviare aggiornamenti solo quando l’informazione è effettivamente cambiata
Implementare logica di rilevamento cambiamenti prima di effettuare chiamate all’API
NON inviare aggiornamenti reiterativi della stessa informazione senza modifiche

Limiti tecnici di velocità (Rate Limiting)

Sebbene non esista un limite rigido di volume totale, Smart OSH implementa controlli di velocità per garantire la stabilità del servizio:

Limite massimo: 3.600 richieste all’ora (equivalente a 60 richieste al minuto)
Chiamate concorrenti: 1. Le chiamate in parallelo riceveranno un codice di stato 429
Meccanismo di protezione: Quando il sistema rileva un ritmo superiore a questi valori, si attiva automaticamente un meccanismo di throttling che limiterà temporaneamente le richieste

Codici di risposta e gestione errori

Codici HTTP rilevanti

Codice	Significato	Azione richiesta
`200 OK`	Richiesta riuscita	Continuare normalmente
`400 Bad Request`	Solitamente “You are using too many sessions”	Vedere gestione sessioni
`401 Unauthorized`	Credenziali non valide o sessione scaduta	Verificare credenziali e riautenticare
`429 Too Many Requests`	Limite di velocità superato	Implementare backoff e ritentare
`503 Service Unavailable`	Servizio temporaneamente non disponibile	Ritentare con strategia esponenziale
`504 / 524 Gateway Timeout`	Timeout per blocco risorse	Ritentare dopo un intervallo

Manutenzione programmata

Smart OSH effettua manutenzioni periodiche che possono causare codice 503 Service Unavailable. Le finestre di manutenzione sono notificate in anticipo. I clienti devono implementare strategie di ritentativo per gestire questi periodi senza perdita di dati.

Blocchi per operazioni concorrenti

La piattaforma può trattenere o bloccare temporaneamente l’accesso a certi dati quando:

Sono in esecuzione operazioni massive (importazioni, processi batch, ecc.)
Altri utenti stanno effettuando operazioni individuali sugli stessi dati
Sono in corso processi di calcolo intensivi

Durante questi blocchi l’API può sperimentare tempi di risposta più lunghi o restituire codici 503 / 504 / 524. Il client deve implementare ritentativi con intervalli crescenti.

Strategie di ritentativo raccomandate

Backoff esponenziale con jitter:

Ritentativo 1: attendere 1–2 secondi
Ritentativo 2: attendere 2–4 secondi
Ritentativo 3: attendere 30–60 secondi
Ritentativo 4: attendere 180–300 secondi

Codici che richiedono ritentativo: 429, 503, 504, 524, errori di rete/timeout.

Codici che NON devono essere ritentati automaticamente: 400, 401, 403, 404, 422.

Best practice

Query in blocco con paginazione — Utilizzare endpoint di query massiva per grandi volumi. Dimensione pagina raccomandata: 100–500 record.
Strategie di backoff — Implementare retrocessione esponenziale in caso di errori o risposte 429 / >500. Aggiungere jitter casuale per evitare sincronizzazione dei ritentativi.
Rilevamento locale dei cambiamenti — Mantenere un registro dello stato dei dati nel sistema cliente. Considerare l’uso di timestamp, checksum o hash per rilevare cambiamenti.
Consolidamento degli aggiornamenti — Raggruppare più cambiamenti in una singola richiesta quando l’API lo permette. Utilizzare operazioni batch quando disponibili.
Timeout appropriati — Connessione: 10–30 secondi. Lettura: 60–100 secondi per operazioni complesse.

Header informativi

L’API può includere i seguenti header per monitorare l’uso:

x-throttled — Indica se le query sono limitate dal server
x-requestsUserMinCount — Contatore delle query effettuate negli ultimi 60 secondi

Orari raccomandati

Per operazioni massive, evitare per quanto possibile gli orari di punta:

Evitare: 9:00–18:00 (CET)
Preferire: 20:00–7:00 (CET) per caricamenti massivi
Coordinarsi con il supporto per operazioni straordinarie

Caricamenti massivi tramite Excel (KB020)

Scopo

Gli strumenti di caricamento massivo tramite file Excel (KB020) sono progettati per:

Migrazioni iniziali di dati all’implementazione di SmartOSH
Aggiornamenti massivi puntuali quando ci sono cambiamenti significativi nei dati
Caricamenti incrementali di nuovi record o modifiche di record esistenti
Correzioni massive di dati in caso di problemi identificati

Principio di uso incrementale

I caricamenti tramite KB020 devono seguire un modello incrementale, non di sostituzione totale:

Caricare solo i record che sono cambiati dall’ultimo caricamento
Includere solo le colonne con valori modificati quando possibile
NON ricaricare massivamente l’intero database periodicamente
NON caricare file con dati identici a quelli già presenti nella piattaforma
NON usare KB020 come metodo abituale di aggiornamento dati che cambiano frequentemente

Impatto dei caricamenti massivi

Come per l’API, ogni caricamento dati tramite KB020 attiva validazioni, ricalcoli automatici, notifiche via email, attivazione di flussi di lavoro e blocchi temporanei di risorse.

I caricamenti ripetitivi di dati senza cambiamenti generano costi computazionali inutili, saturano gli utenti con notifiche superflue e possono influire sulle prestazioni generali dell’ambiente cliente.

Uso non appropriato di KB020

Gli strumenti di caricamento massivo non devono essere utilizzati per:

Sostituire le funzionalità di aggiornamento dati disponibili nell’interfaccia web
Effettuare ricariche sistematiche e periodiche di tutti i dati senza modifiche effettive
Aggiornare record i cui valori non sono cambiati
Costituire il metodo principale di gestione e manutenzione dati in sostituzione dell’uso normale della piattaforma

Buone pratiche per caricamenti batch

Preparazione del file Excel:

Identificare quali record sono realmente cambiati dall’ultimo caricamento
Esportare da SmartOSH lo stato attuale se necessario per confronto
Includere solo i record modificati o nuovi con le colonne identificative (ID, Key, codice unico, ecc.)

Frequenza raccomandata:

Migrazioni iniziali: una sola volta all’implementazione
Aggiornamenti normali: solo quando ci sono cambiamenti significativi che lo giustificano
Frequenza massima raccomandata: un caricamento al giorno
Per aggiornamenti frequenti, urgenti o unitari: utilizzare l’API invece di KB020

Segnali di uso inadeguato:

Caricamenti giornalieri o più volte a settimana degli stessi dati
File con migliaia di record ma pochi cambiamenti reali
Caricamenti automatici programmati senza validazione preventiva dei cambiamenti che generano molti errori

Intervento in casi di uso abusivo

Smartosh si riserva il diritto di contattare clienti il cui modello di utilizzo:

Superi sistematicamente i limiti di velocità stabiliti
Generi caricamenti inutili tramite aggiornamenti ripetitivi senza cambiamenti
Comprometta le prestazioni generali della piattaforma
Non implementi strategie di ritentativo adeguate

In questi casi, lavoreremo con il cliente per ottimizzare la sua integrazione e garantire un uso sostenibile del servizio. SmartOSH si riserva il diritto di limitare o restringere l’uso dell’API.

Disponibilità e SLA

Disponibilità obiettivo: 99,5% (esclude manutenzioni programmate e blocchi dati funzionali dell’ambiente cliente)
Supporto tecnico: Disponibile in orario lavorativo