FAQ
Generale
Posso integrare qualsiasi funzionalità di GipoNext via API?
No. Le API coprono un perimetro specifico. Prima di stimare tempi e costi, verifica risorse e operazioni disponibili in Entità e operazioni e nel Riferimento API.
GipoNext sviluppa anche l'integrazione del mio cliente?
No. GipoNext fornisce piattaforma, onboarding tecnico, approvazione OAuth e supporto mirato. Delivery e manutenzione dell'integrazione restano in carico al System Integrator.
Esiste un ambiente sandbox per sviluppare?
Sì. È possibile richiede un tenant sandbox che si può libraramente popolare con dati fittizzi ai fini di sviluppo. L'accesso a dati reali richiede coinvolgimento esplicito del centro medico. Puoi completare l'intero ciclo di sviluppo e test senza mai toccare dati di produzione.
Qual è la sequenza consigliata per partire?
Usa questa progressione:
- Da dove iniziare per onboarding e responsabilità.
- Registrare l'applicazione per provisioning OAuth.
- Flussi OAuth e token per il flusso tecnico.
- Entità e operazioni per la mappa funzionale API.
Come contatto il supporto in caso di problemi?
Scrivi ai contatti di supporto. Includi sempre: endpoint chiamato, codice HTTP ricevuto, body della risposta e timestamp della richiesta.
Autenticazione e OAuth
Basta avere client_id e client_secret per accedere ai dati?
No. Servono sia identità applicativa (client OAuth) sia login utente. Tenant e permessi dipendono dall'utente autenticato. Vedi Credenziali sviluppatore e credenziali di accesso al sistema.
Esiste un token "globale" dell'integratore?
No. Non esiste un token con accesso trasversale a tutti i tenant. Ogni token rappresenta un utente e i relativi permessi.
Quanto dura un access token?
L'access token ha una durata limitata. Quando scade, le API rispondono 401 Unauthorized. Usa il refresh token per ottenerne uno nuovo senza richiedere il login all'utente. Vedi Flussi OAuth e token.
Il refresh token può scadere?
Sì. Un refresh token può diventare non valido per diversi motivi: revoca da parte dell'utente, inattività prolungata, disattivazione dell'account, superamento del limite di token attivi. In questo caso, l'utente deve fare un nuovo login completo.
Vedi Scadenza del refresh token.
Posso usare il flusso Client Credentials (machine-to-machine)?
No. Le API GipoNext richiedono sempre il contesto di un utente autenticato. I flussi supportati sono Authorization Code e Device Code.
Vedi Flussi OAuth e token in particolar modo la sezione sui servizi in background.
Dati e formati
In che formato sono le date nelle risposte?
Le date sono in formato ISO 8601 (es. 2025-03-15T10:30:00Z). Usa una libreria di parsing date per gestirle correttamente nel tuo linguaggio.
La risposta può contenere campi che non conosco?
Sì. Le API possono aggiungere nuovi campi in qualsiasi momento (modifiche additive). Il tuo client deve ignorare in sicurezza i campi non riconosciuti. Non validare la risposta in modo rigido. Vedi Change management.
Quale encoding usano le API?
Tutte le risposte sono in formato JSON con encoding UTF-8.
Operatività
Come gestisco i limiti di traffico?
Implementa retry con backoff e rispetta Retry-After in caso di 429. Dettagli in Rate limiting.
Come gestisco paginazione e sincronizzazioni massive?
Itera le pagine usando hasMore come condizione di uscita e non assumere dataset statici. Dettagli in Paginazione.
Cosa succede se ricevo un errore 400 o 422?
Il body della risposta contiene i dettagli dell'errore (campo message e, se presente, errors con i campi specifici). Leggi il body per capire cosa correggere. Vedi Gestione errori.
Posso fare richieste in parallelo?
Sì, ma con moderazione. Tutte le richieste dalla stessa applicazione (stesso client_id) condividono lo stesso contatore di rate limiting, indipendentemente dall'utente. Se invii troppe richieste in parallelo, rischi di raggiungere il limite. Vedi Rate limiting.
Quali requisiti TLS devo rispettare?
Le connessioni devono usare TLS 1.2 come versione minima, con una delle cipher suite supportate. Vedi TLS.