Riferimento API

Tipo di integrazione

Le API GipoNext sono esclusivamente REST (HTTP + JSON). Ogni operazione segue il modello request/response sincrono: il tuo client invia una richiesta, il server la elabora e restituisce una risposta.

Non sono previsti altri modelli di integrazione. In particolare:

• Non ci sono webhook — GipoNext non invia notifiche push al tuo server quando un dato cambia.
• Non ci sono WebSocket — non è disponibile un canale di comunicazione bidirezionale in tempo reale.
• Non ci sono code di messaggi — non è prevista integrazione tramite broker (RabbitMQ, Azure Service Bus, ecc.) verso l'esterno.

Se hai bisogno di sapere quando un dato cambia, l'unico approccio è il polling: interroga periodicamente l'endpoint interessato a intervalli ragionevoli (vedi Rate limiting per i limiti applicabili).

Specifica OpenAPI 2.0

Le API sono descritte da una specifica OpenAPI 2.0 (il formato un tempo noto come Swagger). È un documento JSON leggibile da macchine che descrive tutti gli endpoint, i parametri, i modelli di richiesta/risposta e gli schemi di autenticazione.

URL della specifica:

https://api.giponext.it/swagger/docs/v2

Puoi usare questo URL per:

• Importare la collection in tool di sviluppo come Postman, Bruno, Insomnia o Hoppscotch e avere subito tutti gli endpoint pronti da chiamare.
• Generare client SDK per il tuo linguaggio con tool come OpenAPI Generator, NSwag, AutoRest o Kiota.
• Navigare la documentazione interattiva su Swagger UI, dove puoi esplorare endpoint, leggere i modelli e provare le chiamate con autenticazione OAuth.
• Esplorare le API con il client Scalar integrato in questo sito.

Generare un client: perché e come

Generare un client SDK dalla specifica OpenAPI è la best practice raccomandata per integrare le API GipoNext. Un client generato automaticamente:

• Risparmia lavoro — non devi scrivere a mano classi per request, response, serializzazione e gestione degli endpoint.
• Riduce gli errori — i tipi, i nomi dei campi e le firme dei metodi sono derivati dalla specifica, non da copia-incolla manuale.
• Si aggiorna facilmente — quando la specifica cambia, rigeneri il client e il compilatore ti segnala eventuali incompatibilità.
• Garantisce coerenza — il client riflette fedelmente ciò che il server espone, inclusi campi opzionali, enum e formati.

💡 Consiglio

Includi la generazione del client nella tua pipeline di build. In questo modo, ogni aggiornamento della specifica si traduce automaticamente in un client aggiornato, e il compilatore ti avvisa se qualcosa è cambiato.

Configurazione del client OAuth

Per chiamare le API, il tuo client (generato o manuale) deve autenticarsi tramite OAuth 2.0. I parametri da configurare sono gli stessi indipendentemente dallo strumento che usi.

Parametri comuni

Parametro	Valore	Dove si trova
Grant Type	authorization_code	Fisso
Auth URL	https://account.gipo.it/connect/authorize	Fisso
Token URL	https://account.gipo.it/connect/token	Fisso
Client ID	Il tuo client_id	Pagina di dettaglio del client OAuth su account.gipo.it
Client Secret	Il tuo client_secret	Sezione "Secrets" del client OAuth
Scopes	Scope separati da spazio (es. openid offline_access giponext.patients)	In base agli endpoint che vuoi chiamare — vedi Autenticazione e autorizzazione
Redirect URI	Dipende dal client che usi (vedi sotto)	Deve corrispondere a uno dei redirect URI registrati su account.gipo.it
State	Valore casuale	Generato dal client per protezione CSRF — verificalo nella callback

⚠️ Redirect URI

Il redirect URI configurato nel tuo tool deve essere identico a quello registrato nella configurazione del client OAuth su account.gipo.it. Anche una differenza minima (slash finale, http vs https) causa un errore di autorizzazione.

Configurazione per client

Ogni tool di sviluppo ha la propria interfaccia per configurare OAuth. Di seguito trovi le impostazioni specifiche per i client più comuni.

Scalar (integrato)

# Tab Specifiche / Scalar di questo sito internet
# Endpoint OAuth e scope sono già preconfigurati.
# Devi solo inserire Client ID e Client Secret.

Client ID:      <il tuo client_id>
Client Secret:  <il tuo client_secret>
Scope:          <gli scope richiesti per quella sessione>

# da registrare su account.gipo.it:
Redirect URI:
  - https://api.giponext.it/specs/scalar.html
  - https://api.giponext.it/en/specs/scalar.html

Postman

# Tab Authorization nella collection o nella richiesta
Type:             OAuth 2.0
Grant Type:       Authorization Code
Callback URL:     https://oauth.pstmn.io/v1/callback
Auth URL:         https://account.gipo.it/connect/authorize
Access Token URL: https://account.gipo.it/connect/token
Client ID:        <il tuo client_id>
Client Secret:    <il tuo client_secret>
Scope:            <gli scope richiesti per quella sessione>
State:            <generato automaticamente>

# da registrare su account.gipo.it:
Redirect URI:
  - https://oauth.pstmn.io/v1/callback

Bruno

# Tab Auth nella collection
Auth Type:          OAuth 2.0
Grant Type:         Authorization Code
Callback URL:       https://oauth.usebruno.com/callback
Authorization URL:  https://account.gipo.it/connect/authorize
Access Token URL:   https://account.gipo.it/connect/token
Client ID:          <il tuo client_id>
Client Secret:      <il tuo client_secret>
Scope:              <gli scope richiesti per quella sessione>
State:              <generato automaticamente>

# da registrare su account.gipo.it:
Redirect URI:
  - https://oauth.usebruno.com/callback
  # Bruno supporta anche callback locale:
  - http://localhost:3000/oauth/callback

Insomnia

# Tab Auth nella richiesta o nell'environment
Auth Type:          OAuth 2.0
Grant Type:         Authorization Code
Redirect URL:       http://localhost:7171/oauth/callback
Authorization URL:  https://account.gipo.it/connect/authorize
Access Token URL:   https://account.gipo.it/connect/token
Client ID:          <il tuo client_id>
Client Secret:      <il tuo client_secret>
Scope:              <gli scope richiesti per quella sessione>

# da registrare su account.gipo.it:
Redirect URI:
  - http://localhost:7171/oauth/callback

Regole valide per tutti i client

1. Imposta sempre Grant Type = Authorization Code.
2. Se il client supporta PKCE, abilitalo.
3. Dopo l'autorizzazione, usa il token con l'header Authorization: Bearer <access_token>.
4. Quando il token scade (risposta 401), rinnova con il refresh token — vedi Flussi OAuth e token.

Chiamate API dopo il login

Dopo aver ottenuto un access token valido, tutte le chiamate seguono lo stesso schema.

Base URL:

https://api.giponext.it/v2

Prima chiamata — ottenere il tenantId:

GET https://api.giponext.it/v2/userinfo
Authorization: Bearer <access_token>

La risposta contiene l'elenco dei tenant a cui l'utente ha accesso. Usa il tenantId in tutte le chiamate successive.

Esempio — lista pazienti:

GET https://api.giponext.it/v2/tenants/{tenantId}/patients
Authorization: Bearer <access_token>

Per la mappa completa di risorse ed endpoint, vedi Entità e operazioni.

Impostazioni avanzate

Puoi usare gli script di Postman per automatizzare operazioni ripetitive. Questo esempio salva il tenantId dalla risposta di UserInfo e lo inietta automaticamente in tutte le rotte che lo richiedono.

UserInfo / Scripts / Post-Response

const tenantId = pm.response.json().tenants.at(0);
pm.collectionVariables.set('tenantId', tenantId);

Collection / Scripts / Pre-Request

const url = pm.request.url.toJSON();
const index = url.variable.findIndex(item => item.key === 'tenantId');

if (index < 0) return;

url.variable[index].value = pm.collectionVariables.get('tenantId');
pm.request.url = url

Prossimi passi

• Swagger UI — documentazione interattiva con tutti gli endpoint
• Scalar — client API integrato in questo sito
• Entità e operazioni — mappa risorse, operazioni e scope
• Flussi OAuth e token — dettagli tecnici sul flusso di autenticazione
• Caratteristiche delle API — regole operative trasversali (errori, paginazione, rate limiting, TLS)