Entità e operazioni

Questa è la pagina di riferimento per capire:

• quali sono le principali entità API;
• come puoi interagire con ciascuna entità (lettura/scrittura);
• quale scope OAuth serve per ciascuna risorsa.
• quale permesso applicativo serve per chiamare ogni singola rotta.

Per la lista completa degli scope, come funzionano e come gestirli, vedi Scope e autenticazione.

Ogni chiamata può richiedere due livelli di autorizzazione: lo scope OAuth (token) e il permesso applicativo dell'utente in GipoNext. In questa pagina trovi entrambi: lo scope principale per risorsa e, sotto ogni risorsa, i permessi richiesti per ciascuna rotta.

Per i dettagli completi (campi obbligatori, enum, tipi) usa sempre lo Swagger UI.

Mappa rapida: risorse, operazioni e scope

Risorsa	Scope principale	Lettura	Scrittura
UserInfo	n/a (contesto utente autenticato)	Sì	No
Pazienti	giponext.patients	Sì	Sì
Agende	giponext.agenda	Sì	No
Appuntamenti	giponext.agenda	Sì	Sì
Disponibilità	giponext.agenda	Sì	No
Prestazioni	giponext.treatments	Sì	No
Listini	giponext.treatments	Sì	No
Episodi	giponext.episodes	Sì	Sì
Referti	giponext.medicalreports	Sì	Sì
Fatture	giponext.invoices	Sì	Sì

401 - Unauthorized

Nel caso in cui l'utente non sia correttamente autenticato l'errore sarà

GET/v2/userinfo

Header	Value
Authorization	<missing_wrong_or_expired_token>
Accept	application/json

401 Unauthorized

403 - Forbidden

L'utente è correttamente autenticato ma non ha privilegi sufficienti

Claim mancante

Nell'autenticazione che precede la chiamata NON è stato specificato un claim necessario per effettuare la chiamata

GET/v2/tenants/:tenantId/agendas

Header	Value
Authorization	{access_token}
Accept	application/json

403 Forbidden

Permessi utente non sufficienti

In caso l'utente collegato non possa accedere alla risorsa richiesta, si otterrà un messaggio come questo

GET/v2/tenants/:tenantId/agendas

Header	Value
Authorization	{access_token}
Accept	application/json

403 Forbidden

Risorse

UserInfo

• Prefisso /v2/userinfo
• Scope contesto utente autenticato

Specs	Operazione	Permesso
Swagger - Scalar	GET /	nessun permesso specifico (utente autenticato)

È il punto di partenza di ogni integrazione: ti restituisce il contesto dell'utente autenticato e i tenant a cui può accedere. In pratica lo usi per capire "chi sta operando" e su quali strutture puoi lavorare.

Da qui ricavi il tenantId da usare nelle chiamate successive sotto /v2/tenants/{tenantId}/....

Tenant

Le API prevedono che un utente possa essere associato a più tenant. In questo momento su GipoNext non è un caso possibile, ma si raccomanda di gestire l'eventualità.

Utente inesistente in GipoNext

L'identity provider (GipoAccount) e GipoNext sono due oggetti distinti. Può quindi capitare che l'autenticazione OAuth vada a buon fine con un utente correttamente attivo in GipoAccount ma non presente in GipoNext.

In questo caso si potrebbe ottenere un 200 con alcune informazioni dell'utente ma nessuna informazione sul tenant. In questo caso l'utente è da considerarsi non valido.

GET/v2/userinfo

Header	Value
Authorization	Bearer {access_token}
Accept	application/json

200 OK

Pazienti

• Prefisso /v2/tenants/{tenantId}/patients
• Scope giponext.patients

Specs	Operazione	Permesso
Swagger - Scalar	GET /	pazienti.visualizza
Swagger - Scalar	POST /	pazienti.modifica
Swagger - Scalar	GET /{patientId}	pazienti.visualizza
Swagger - Scalar	PUT /{patientId}	pazienti.modifica

Questa risorsa rappresenta l'anagrafica paziente e la relativa gestione operativa. È tipicamente la base per tutte le integrazioni che devono creare, aggiornare o sincronizzare dati anagrafici con sistemi esterni (CRM, portali, middleware amministrativi).

Agende

• Prefisso /v2/tenants/{tenantId}/agendas
• Scope giponext.agenda

Specs	Operazione	Permesso
Swagger - Scalar	GET /	agende.visualizza oppure agende-medico-account.visualizza
Swagger - Scalar	GET /{agendaId}	agende.visualizza oppure agende-medico-account.visualizza

Le agende descrivono i calendari disponibili nel tenant (per medico, risorsa o postazione). In pratica sono il riferimento per capire dove e come pianificare visite e attività.

Appuntamenti

• Prefisso /v2/tenants/{tenantId}/appointments
• Scope giponext.agenda

Specs	Operazione	Permesso
Swagger - Scalar	GET /	appuntamenti.visualizza
Swagger - Scalar	GET /{appointmentId}	appuntamenti.visualizza
Swagger - Scalar	POST /	appuntamenti.crea
Swagger - Scalar	PUT /{appointmentId}	appuntamenti.modifica
Swagger - Scalar	PUT /{appointmentId}/status	appuntamenti.modifica
Swagger - Scalar	PUT /{appointmentId}/payment	appuntamenti.modifica
Swagger - Scalar	DELETE /{appointmentId}/payment	appuntamenti.modifica
Swagger - Scalar	DELETE /{appointmentId}	appuntamenti.cancella
Swagger - Scalar	POST /{appointmentId}/checkin	appuntamenti.modifica

È la risorsa centrale per la gestione del planning: puoi leggere appuntamenti esistenti, crearne di nuovi, aggiornarli e cancellarli. È la base per integrazioni di prenotazione online, front desk, reminder e sincronizzazioni calendario.

Prestazioni

• Prefisso /v2/tenants/{tenantId}/treatments
• Scope giponext.treatments

Specs	Operazione	Permesso
Swagger - Scalar	GET /	prestazioni.visualizza
Swagger - Scalar	GET /{treatmentId}	prestazioni.visualizza

Le prestazioni rappresentano il catalogo delle attività erogabili. In integrazione servono per costruire cataloghi esterni, associare appuntamenti a servizi e calcolare correttamente il contesto economico/operativo delle prenotazioni.

Listini

• Prefisso /v2/tenants/{tenantId}/pricelists
• Scope giponext.treatments

Specs	Operazione	Permesso
Swagger - Scalar	GET /	listini.visualizza
Swagger - Scalar	GET /{priceListId}	listini.visualizza
Swagger - Scalar	GET /{priceListCode}	listini.visualizza

I listini definiscono regole prezzo e validità economiche. Sono utili quando devi mostrare prezzi, fare verifiche preliminari o mantenere allineata la parte economica tra GipoNext e applicazioni esterne.

Episodi

• Prefisso /v2/tenants/{tenantId}/episodes
• Scope giponext.episodes

Specs	Operazione	Permesso
Swagger - Scalar	GET /	assegnazione.visualizza
Swagger - Scalar	GET /{id}	assegnazione.visualizza
Swagger - Scalar	POST /	assegnazione.crea
Swagger - Scalar	PUT /{id}	assegnazione.modifica
Swagger - Scalar	DELETE /{id}	assegnazione.cancella

Gli episodi raggruppano attività cliniche e amministrative legate a un percorso paziente. Sono fondamentali quando l'integrazione deve seguire un processo completo (presa in carico, avanzamento, chiusura e collegamento con componenti economiche).

Fatture

• Prefisso /v2/tenants/{tenantId}/invoices
• Scope giponext.invoices

Specs	Operazione	Permesso
Swagger - Scalar	GET /	fatture.visualizza
Swagger - Scalar	GET /{invoiceId}	fatture.visualizza
Swagger - Scalar	GET /{invoiceId}/pdf	fatture.visualizza
Swagger - Scalar	POST /	fatture.crea
Swagger - Scalar	POST /{invoiceId}/reimbursements	fatture.crea

Questa risorsa copre il ciclo di fatturazione: consultazione documenti, creazione e recupero output correlati. Se integri flussi amministrativi o contabili, è il punto di raccordo principale tra parte clinica e parte economica.

Referti

• Prefisso /v2/tenants/{tenantId}/medicalreports
• Scope giponext.medicalreports

Specs	Operazione	Permesso
Swagger - Scalar	POST /	referti.crea
Swagger - Scalar	GET /	referti.visualizza
Swagger - Scalar	GET /{medicalReportId}	referti.visualizza
Swagger - Scalar	GET /{medicalReportId}/pdf	referti.visualizza

I referti permettono di pubblicare e gestire documentazione clinica. Questa area è tipica per integrazioni con sistemi di diagnostica, repository documentale, portali paziente o workflow di consegna referti.

Dimensione massima del PDF

Nelle API di creazione referto (POST /), il file PDF allegato non può superare 25 MB. Richieste con file di dimensioni superiori verranno rifiutate.

Disponibilità

• Prefisso /v2/tenants/{tenantId}
• Scope giponext.agenda

Specs	Operazione	Permesso
Swagger - Scalar	GET /availabilities	appuntamenti.visualizza
Swagger - Scalar	GET /treatments/{treatmentId}/listprices/{priceListId}/availabilities	appuntamenti.visualizza

La disponibilità serve per proporre slot prenotabili in modo affidabile. È particolarmente utile in flussi di booking esterni dove devi verificare finestre orarie e coerenza con il contesto organizzativo/economico.

Locations

• Prefisso /v2/tenants/{tenantId}/locations
• Scope contesto tenant dell'utente autenticato

Specs	Operazione	Permesso
Swagger - Scalar	GET /	nessun permesso specifico (utente autenticato con accesso tenant)
Swagger - Scalar	GET /{locationId}	nessun permesso specifico (utente autenticato con accesso tenant)

Le locations rappresentano le sedi operative del tenant. Sono utili quando l'integrazione deve distinguere tra più sedi fisiche (es. ambulatori, studi distaccati) per associare risorse, agende o appuntamenti alla sede corretta.

TenantInfo

• Prefisso /v2/tenants/{tenantId}/info
• Scope contesto tenant dell'utente autenticato

Specs	Operazione	Permesso
Swagger - Scalar	GET /	nessun permesso specifico (utente autenticato con accesso tenant)

Restituisce le informazioni generali sul tenant (ragione sociale, indirizzo, configurazioni). È utile per visualizzare i dati della struttura nell'interfaccia della tua applicazione o per verificare la configurazione del tenant.

Accounting

• Prefisso /v2/tenants/{tenantId}/accounting
• Scope giponext.invoices

Specs	Operazione	Permesso
Swagger - Scalar	GET /sections	fatture.visualizza
Swagger - Scalar	GET /issuers	fatture.visualizza
Swagger - Scalar	GET /issuers/{issuerId}	fatture.visualizza

L'area contabile fornisce accesso ai dati di riepilogo economico e ai sezionali. È il punto di raccordo per integrazioni con sistemi contabili o gestionali esterni che necessitano di dati aggregati.

FAQ

Come faccio a risalire ai medici da una fattura ?

Il flusso da seguire sulle risorse è

Invoice → Items → LinkedPractices → Episode → Doctors

1. Dalla fattura, naviga in Items → LinkedPractices per ottenere:

• episodeId (Assegnazione)
• practiceId (Riga di dettaglio)

2. Chiama l'API Episodes: GET /episodes/{episodeId}
3. Nella response, filtra l'array practices usando il practiceId ottenuto al punto 1: practices[practiceId].doctors

📌 Nota

Ogni riga fattura può avere più LinkedPractices e ogni prestazione può avere più medici.

Come vengono codificati i riferimenti normativi relativi all'esenzione IVA nelle risposte delle API?

Riferimento Normativo	Codice API
Art. 10 n. 18 del DPR 26/10/1972 n. 633	Art10_n18
Art. 1, comma 58, legge n. 190/2014	Art1_Comma58_Legge190_2014
Art. 1, comma 100, legge n. 244/2007	Art1_Comma100_Legge244_2007
Art. 13, comma 5 dpr 633/72	Art13
Ex art. 10, comma 1, n. 20, del Dpr 633/1972	Art10_Comma1_n20
Art.10 n.20 del DPR 26/10/1972 n.633	Art10_n20
ART.17 DPR 633/1972	ART17_DPR_633_1972
Ex art. 10, comma 8, del Dpr 633/1972	Art10_Comma8_633_1972
Art. 124 DL 34/2020	Art124_DL_34_2020
Art. 10 n. da 1 a 9	Art10_nda1a9
Art. 1 comma 452 L. 178 del 30/12/2020	Art1_Comma452_Legge178_2020
Art. 10, comma 1, n. 27-quinquies), Dpr 633/72	Art10_Comma1_N27_quinquies
Esente Iva Art.10 punto 21 del DPR 633/72	Art10_Punto21_DPR_633_1972
Articolo 8 comma C - DPR 633/72	Art8_CommaC_DPR633_72
Articolo 2, comma 3, lettera a, del DPR 633/72	Art2_Comma3_LetteraA_DPR633_1972
Art. 8 comma 35 L. 67/1988	Art8_Comma35_L_67_1988
Art. 8 co 2 Dpr 633/72	Art8_Co2
Art. 26 DPR 633/72	Art26_DPR633_72

Note operative

• Fatture: la creazione fatture è consentita in modo sequenziale per sezionale.
• TLS: per i requisiti di sicurezza trasporto vedi TLS.
• FAQ operative: vedi FAQ.

Per parametri di query (filtri), codici di stato e payload completi, fai riferimento allo Swagger.