Caratteristiche delle API

Le API GipoNext condividono un insieme di comportamenti trasversali che si applicano a tutti gli endpoint, indipendentemente dalla risorsa che stai utilizzando. Conoscerli prima di iniziare a scrivere codice ti aiuta a costruire un'integrazione più solida e a evitare problemi in produzione.

Questa sezione raccoglie le regole operative comuni che ogni integratore dovrebbe considerare:

• Tenant — cos'è un tenant, come ottenere il tenantId, come gestire il filtro per centro medico e l'ambiente sandbox.
• Autenticazione e autorizzazione — come funzionano i flussi OAuth, quali scope richiedere e come gestire il consenso dell'utente.
• Gestione errori — i codici di stato HTTP restituiti dalle API, il formato del body di errore e la strategia per distinguere errori recuperabili da quelli che richiedono una correzione.
• Paginazione — come scorrere elenchi di risorse senza sovraccaricare il server, usando offset, limit e hasMore.
• Rate limiting — i limiti al numero di richieste per finestra temporale, come leggere gli header di risposta e come implementare retry con backoff.
• TLS — la versione minima del protocollo e le cipher suite supportate per la connessione sicura.
• Change management — come evolvono le API nel tempo, cosa sono le modifiche additive e come progettare un client che non si rompa quando arrivano nuovi campi.

Ogni pagina è pensata per essere letta in modo indipendente, ma se parti da zero ti consigliamo di scorrerle tutte almeno una volta: molte situazioni che in produzione sembrano bug sono in realtà comportamenti documentati in queste pagine.