Skip to content

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 ​

ParametroValoreDove si trova
Grant Typeauthorization_codeFisso
Auth URLhttps://account.gipo.it/connect/authorizeFisso
Token URLhttps://account.gipo.it/connect/tokenFisso
Client IDIl tuo client_idPagina di dettaglio del client OAuth su account.gipo.it
Client SecretIl tuo client_secretSezione "Secrets" del client OAuth
ScopesScope separati da spazio (es. openid offline_access giponext.patients)In base agli endpoint che vuoi chiamare — vedi Autenticazione e autorizzazione
Redirect URIDipende dal client che usi (vedi sotto)Deve corrispondere a uno dei redirect URI registrati su account.gipo.it
StateValore casualeGenerato 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.

yaml
# 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
yaml
# 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
yaml
# 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
yaml
# 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:

http
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:

http
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.

javascript
const tenantId = pm.response.json().tenants.at(0);
pm.collectionVariables.set('tenantId', tenantId);
javascript
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 ​