Registrare l'applicazione

Questa pagina descrive i passi operativi per ottenere un account sviluppatore, registrare la tua applicazione OAuth e configurare gli ambienti di sviluppo e produzione.

Per capire il modello concettuale (perché servono due identità e come funzionano insieme), vedi prima Flussi OAuth e token.

Account sviluppatore

L'account sviluppatore è un account GipoNext con il ruolo "Developer" attivato. Serve esclusivamente a gestire le registrazioni delle applicazioni OAuth — non dà accesso ai dati di nessuna clinica.

Nel modello OAuth, l'account sviluppatore corrisponde al ruolo del costruttore di automobili: ti dà accesso alla motorizzazione, dove puoi immatricolare nuovi modelli (applicazioni) e ottenere per ciascuno una targa (client_id).

Come ottenerlo

1. Se non hai un account GipoNext, registrati in modalità DEMO su www.giponext.it.
2. Il responsabile della clinica (il tuo cliente) richiede l'attivazione del ruolo sviluppatore per te, scrivendo ai contatti di supporto e indicando la tua email.
3. Dopo l'attivazione, accedi a account.gipo.it. Troverai il menu Developer → Applicazioni OAuth.

💡 L'account sviluppatore non è un accesso ai dati

Questo account ti permette di registrare e gestire le tue applicazioni. Per accedere ai dati di una clinica ti serve un'utenza con accesso al tenant — è un passaggio separato (vedi Accesso ai dati di produzione più sotto).

Registrare un'applicazione OAuth

Per ogni applicazione che sviluppi (sito, app mobile, servizio, ecc.) devi creare una nuova registrazione OAuth e ottenere l'approvazione.

La registrazione non è una credenziale: è l'accreditamento del canale. Come la targa di un'auto, dichiara al sistema che il tuo software esiste, è legittimo e può presentarsi al controllo. Ma la targa da sola non apre nessuna frontiera — per quello serve il login dell'utente.

Cosa configuri nella richiesta

• Tipo di applicazione (es. web, nativa, daemon)
• Grant type (es. Authorization Code, Device Code — vedi Flussi OAuth e token)
• Nome e descrizione dell'applicazione
• Redirect URI (per il flusso Authorization Code)
• Scope richiesti (vedi Scope e autenticazione: giponext.patients, giponext.agenda, ecc.)
• Claim che l'applicazione può richiedere all'utente durante l'autorizzazione

I claim definiscono quali informazioni puoi chiedere all'utente in fase di consenso (es. profilo, email, tenant). Vanno specificati in fase di creazione della richiesta.

Approvazione e credenziali

• La richiesta viene approvata da un amministratore Gipo.
• Dopo l'approvazione ricevi:
  • client_id (visibile in cima alla pagina di dettaglio del client OAuth)
  • client_secret (nella sezione "Secrets" della stessa pagina)

Con client_id e client_secret puoi implementare il flusso OAuth nella tua applicazione (vedi Flussi OAuth e token).

Ambiente sandbox

Puoi sviluppare e testare la tua integrazione su un tenant sandbox: un ambiente vuoto con dati fittizi, completamente separato dai tenant di produzione dei tuoi clienti.

Lavorare in sandbox ti permette di:

• completare l'implementazione OAuth e le chiamate API senza toccare dati reali;
• validare il flusso end-to-end (login, token, chiamate, gestione errori) in sicurezza;
• mostrare al cliente un prototipo funzionante prima di coinvolgerlo con dati reali.

💡 Nessun rischio per il cliente

Il tenant sandbox è isolato: nulla di ciò che fai in sandbox ha effetto sui tenant di produzione. Puoi creare, modificare e cancellare dati liberamente.

Accesso ai dati di produzione

Quando sei pronto a lavorare con i dati reali di una clinica, serve il coinvolgimento diretto del centro medico. L'integratore non può auto-attivarsi su un tenant di produzione.

La procedura

1. Il centro medico richiede la creazione di un'utenza per l'integratore, aprendo un ticket e indicando l'email da associare.
2. L'integratore riceve le credenziali e le usa per il login OAuth interattivo (l'utenza determina il tenant e i permessi).
3. A progetto concluso, il centro medico disattiva l'utenza temporanea fornita all'integratore.

⚠️ Le credenziali di produzione sono temporanee

Le utenze fornite all'integratore per lavorare su dati reali devono essere disattivate quando non sono più necessarie. È responsabilità del centro medico gestire il ciclo di vita di queste utenze.

Un client per applicazione

Ogni applicazione (o ogni variante che usa redirect URI o scope diversi) dovrebbe avere il proprio client OAuth. Non riutilizzare lo stesso client per più prodotti o ambienti non coerenti con la configurazione approvata.

Best practice operative

• Registra applicazioni OAuth separate per produzione e non produzione quando i redirect URI sono diversi.
• Tieni separati i rispettivi client_secret, per semplificare sicurezza e troubleshooting.
• Considera il supporto email di GipoNext come canale per chiarimenti ed eccezioni, non come presidio continuo dello sviluppo.

FAQ

Quante applicazioni OAuth devo registrare?

Nella maggior parte dei casi una sola registrazione è sufficiente: un client_id per tutta la tua applicazione, indipendentemente da quante cliniche o quanti utenti la useranno.

Conviene registrare applicazioni separate nei seguenti scenari:

Scenario	Perché registrare app separate
Produzione vs. non produzione	Redirect URI diversi, segreti separati, possibilità di revocare l'accesso all'ambiente di test senza impattare la produzione
Più sviluppatori sullo stesso progetto	L'ambiente di sviluppo condiviso (staging, sandbox) può avere una propria registrazione, con un client_secret noto al team ma distinto da quello di produzione
Redirect URI strutturalmente diversi	Se la stessa logica viene distribuita su domini o app con URI che non possono essere ricondotti a una configurazione comune

💡 Regola pratica

Tieni un'unica registrazione per produzione.

Crea registrazioni aggiuntive solo se hai redirect URI incompatibili o se vuoi isolare gli ambienti di sviluppo.

Non moltiplicare le registrazioni senza motivo: ogni app va mantenuta e approvata da Gipo.

Esempio

Quali tenant possono collegarsi alla mia applicazione?

Tutti i tenant GipoNext attivi possono autenticarsi tramite la tua applicazione OAuth: il sistema non limita automaticamente l'accesso a una singola clinica.

Questo significa che se stai sviluppando un'integrazione dedicata a un singolo cliente, devi implementare tu il controllo sul tenant autorizzato. Dopo il login, il tenant dell'utente connesso è disponibile nella risposta dell'endpoint UserInfo:

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

{
  "sub": "user-id",
  "name": "Mario Rossi",
  "tenants": [
    { "id": "tenant-abc123", "name": "Clinica Esempio" }
  ]
}

Verifica che il tenantId restituito corrisponda al tenant che hai autorizzato per la tua integrazione. Se non corrisponde, rifiuta l'accesso e mostra un messaggio esplicativo all'utente.

⚠️ Attenzione

Il login OAuth autentica l'utente presso Gipo, ma non garantisce che quell'utente appartenga alla clinica che la tua app serve. Se la tua integrazione è dedicata a un singolo cliente, verifica sempre il tenant dopo il login.

Prossimi passi

• Flussi OAuth e token — flussi tecnici, identità e gestione token
• Scope e autenticazione — permessi disponibili e criteri di accesso
• Entità e operazioni — mappa funzionale API e risorse disponibili