Da dove iniziare

Questa guida serve a impostare un'integrazione efficace fin dall'inizio: aspettative allineate, responsabilità chiare e nessuna sorpresa. Non serve esperienza pregressa con OAuth: i concetti sono introdotti passo dopo passo.

I 3 attori di un'integrazione

Ogni integrazione coinvolge tre parti con ruoli distinti:

Chi	Cosa fa
GipoNext	Fornisce le API, gestisce l'onboarding tecnico, approva le applicazioni OAuth
System Integrator (tu)	Sviluppa, testa e mantiene l'integrazione
Centro medico (il tuo cliente)	Definisce gli obiettivi, autorizza gli accessi, presenta l'integratore a GipoNext

💡 Responsabilità chiave

GipoNext fornisce piattaforma e supporto mirato. Il progetto di integrazione (sviluppo, test, go-live, manutenzione) è interamente in carico all'integratore.

Due identità separate: app e utente

Per accedere alle API servono due cose distinte:

Identità	Cos'è	Come si ottiene
Applicazione (client_id + client_secret)	Identifica il tuo software	Registrazione OAuth su account.gipo.it
Utente (login interattivo)	Determina tenant e permessi	Login dell'utente finale su account.gipo.it

Le credenziali dell'applicazione non danno accesso ai dati: servono solo a identificare il software. L'accesso ai dati dipende sempre dall'utente che fa il login.

Per capire a fondo questa separazione e perché è importante, vedi Credenziali sviluppatore e credenziali di accesso al sistema.

Cosa fare in pratica

Passo 1 — Accreditamento

Il centro medico presenta l'integratore a GipoNext, che attiva l'account sviluppatore e approva la registrazione dell'applicazione OAuth.

Tutto il dettaglio operativo è nella pagina Processo di accreditamento.

Passo 2 — Implementare OAuth

Usa uno dei flussi supportati:

• Authorization Code (raccomandato) — per app con browser o interfaccia completa (web, desktop, mobile).
• Device Code — per dispositivi senza browser (l'utente autorizza da un altro dispositivo).

Dettagli: Flussi OAuth e token.

Passo 3 — Chiamare le API

• Base URL: https://api.giponext.it/v2/tenants/{tenantId}/...
• Recupera tenantId dall'endpoint UserInfo dopo l'autenticazione.
• Includi il Bearer token nell'header Authorization di ogni richiesta.

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

Per l'elenco completo di endpoint e modelli dati: Swagger UI e Riferimento API.

Prossimi passi

• Processo di accreditamento — come ottenere account sviluppatore e credenziali OAuth
• Registrare l'applicazione — dettagli sulla registrazione dell'applicazione
• Entità e operazioni — risorse disponibili, operazioni e scope OAuth richiesti
• FAQ — risposte rapide ai dubbi più frequenti