English

Italiano

English

Italiano

Appearance

Entities and operations ​

This is the reference page for understanding:

  • which main API entities exist;
  • how you can interact with each (read/write);
  • which OAuth scope is required for each resource.
  • which applicative permission is required for each specific route.

For the full scope list, how they work, and how to manage them, see Scopes and authentication.

Each call may require two authorization layers: the OAuth scope (token) and the user's applicative permission in GipoNext. This page shows both: the main scope per resource and, under each resource, the permissions required for each route.

For full details (required fields, enums, types) always use Swagger UI.

Quick map: resources, operations, and scopes ​

ResourceMain scopeReadWrite
UserInfon/a (authenticated user context)YesNo
Patientsgiponext.patientsYesYes
Agendasgiponext.agendaYesNo
Appointmentsgiponext.agendaYesYes
Availabilitiesgiponext.agendaYesNo
Treatmentsgiponext.treatmentsYesNo
Price listsgiponext.treatmentsYesNo
Episodesgiponext.episodesYesYes
Medical reportsgiponext.medicalreportsYesYes
Invoicesgiponext.invoicesYesYes

401 - Unauthorized ​

When the user is not correctly authenticated the error will be:

GET/v2/userinfo
json

403 - Forbidden ​

The user is correctly authenticated but lacks sufficient privileges

Missing claim ​

In the authentication preceding the call, a claim required for the call was not specified

GET/v2/tenants/:tenantId/agendas
json

Insufficient user permissions ​

When the connected user cannot access the requested resource, you will get a message like this:

GET/v2/tenants/:tenantId/agendas
json

Resources ​

UserInfo ​

  • Required prefix /v2/userinfo
  • Scope authenticated user context
SpecsOperationPermission
Swagger - ScalarGET /no specific permission (authenticated user)

This is the starting point for every integration: it returns the authenticated user context and the tenants they can access. In practice you use it to understand "who is operating" and which structures you can work with.

From here you obtain the tenantId for subsequent calls under /v2/tenants/{tenantId}/....

Tenant ​

APIs allow for a user to be associated with multiple tenants. Currently this is not possible in GipoNext, but handling this case is recommended.

User not present in GipoNext ​

The identity provider (GipoAccount) and GipoNext are distinct. A user may be correctly authenticated and active in GipoAccount but not present in GipoNext.

In that case you may receive a 200 with some user information but no tenant information. The user should be considered invalid.

GET/v2/userinfo
json

Patients ​

  • Required prefix /v2/tenants/{tenantId}/patients
  • Scope giponext.patients
SpecsOperationPermission
Swagger - ScalarGET /pazienti.visualizza
Swagger - ScalarPOST /pazienti.modifica
Swagger - ScalarGET /{patientId}pazienti.visualizza
Swagger - ScalarPUT /{patientId}pazienti.modifica

This resource represents patient demographics and related operational management. It is typically the base for integrations that create, update, or synchronize demographics with external systems (CRM, portals, administrative middleware).

Agendas ​

  • Required prefix /v2/tenants/{tenantId}/agendas
  • Scope giponext.agenda
SpecsOperationPermission
Swagger - ScalarGET /agende.visualizza or agende-medico-account.visualizza
Swagger - ScalarGET /{agendaId}agende.visualizza or agende-medico-account.visualizza

Agendas describe the calendars available in the tenant (per doctor, resource, or station). In practice they are the reference for understanding where and how to schedule visits and activities.

Appointments ​

  • Required prefix /v2/tenants/{tenantId}/appointments
  • Scope giponext.agenda
SpecsOperationPermission
Swagger - ScalarGET /appuntamenti.visualizza
Swagger - ScalarGET /{appointmentId}appuntamenti.visualizza
Swagger - ScalarPOST /appuntamenti.crea
Swagger - ScalarPUT /{appointmentId}appuntamenti.modifica
Swagger - ScalarPUT /{appointmentId}/statusappuntamenti.modifica
Swagger - ScalarPUT /{appointmentId}/paymentappuntamenti.modifica
Swagger - ScalarDELETE /{appointmentId}/paymentappuntamenti.modifica
Swagger - ScalarDELETE /{appointmentId}appuntamenti.cancella
Swagger - ScalarPOST /{appointmentId}/checkinappuntamenti.modifica

This is the core resource for planning: you can read existing appointments, create new ones, update them, and delete them. It is the base for online booking, front desk, reminder, and calendar sync integrations.

Treatments ​

  • Required prefix /v2/tenants/{tenantId}/treatments
  • Scope giponext.treatments
SpecsOperationPermission
Swagger - ScalarGET /prestazioni.visualizza
Swagger - ScalarGET /{treatmentId}prestazioni.visualizza

Treatments represent the catalog of deliverable activities. In integration they are used to build external catalogs, associate appointments with services, and correctly compute the economic/operational context of bookings.

Price lists ​

  • Required prefix /v2/tenants/{tenantId}/pricelists
  • Scope giponext.treatments
SpecsOperationPermission
Swagger - ScalarGET /listini.visualizza
Swagger - ScalarGET /{priceListId}listini.visualizza
Swagger - ScalarGET /{priceListCode}listini.visualizza

Price lists define pricing and validity rules. They are useful when you need to show prices, run preliminary checks, or keep the economic alignment between GipoNext and external applications.

Episodes ​

  • Required prefix /v2/tenants/{tenantId}/episodes
  • Scope giponext.episodes
SpecsOperationPermission
Swagger - ScalarGET /assegnazione.visualizza
Swagger - ScalarGET /{id}assegnazione.visualizza
Swagger - ScalarPOST /assegnazione.crea
Swagger - ScalarPUT /{id}assegnazione.modifica
Swagger - ScalarDELETE /{id}assegnazione.cancella

Episodes group clinical and administrative activities across a patient pathway. They are essential when an integration must follow a complete process (intake, progress, closure, and links to economic components).

Invoices ​

  • Required prefix /v2/tenants/{tenantId}/invoices
  • Scope giponext.invoices
SpecsOperationPermission
Swagger - ScalarGET /fatture.visualizza
Swagger - ScalarGET /{invoiceId}fatture.visualizza
Swagger - ScalarGET /{invoiceId}/pdffatture.visualizza
Swagger - ScalarPOST /fatture.crea
Swagger - ScalarPOST /{invoiceId}/reimbursementsfatture.crea

This resource covers the invoicing cycle: document lookup, creation, and related outputs. If you integrate administrative or accounting flows, it is the main bridge between clinical and economic operations.

Medical reports ​

  • Required prefix /v2/tenants/{tenantId}/medicalreports
  • Scope giponext.medicalreports
SpecsOperationPermission
Swagger - ScalarPOST /referti.crea
Swagger - ScalarGET /referti.visualizza
Swagger - ScalarGET /{medicalReportId}referti.visualizza
Swagger - ScalarGET /{medicalReportId}/pdfreferti.visualizza

Medical reports allow publishing and managing clinical documentation. This area is typical for integrations with diagnostic systems, document repositories, patient portals, or report delivery workflows.

Maximum PDF size

When creating a medical report (POST /), the attached PDF file must not exceed 25 MB. Requests with larger files will be rejected.

Availabilities ​

  • Required prefix /v2/tenants/{tenantId}
  • Scope giponext.agenda
SpecsOperationPermission
Swagger - ScalarGET /availabilitiesappuntamenti.visualizza
Swagger - ScalarGET /treatments/{treatmentId}/listprices/{priceListId}/availabilitiesappuntamenti.visualizza

Availabilities are used to propose bookable slots reliably. They are especially useful in external booking flows where you need to validate time windows and consistency with organizational/economic context.

Locations ​

  • Required prefix /v2/tenants/{tenantId}/locations
  • Scope authenticated user tenant context
SpecsOperationPermission
Swagger - ScalarGET /no specific permission (authenticated user with tenant access)
Swagger - ScalarGET /{locationId}no specific permission (authenticated user with tenant access)

Locations represent the tenant's operational sites. They are useful when the integration must distinguish between multiple physical sites (e.g. clinics, satellite offices) to associate resources, agendas, or appointments with the correct site.

TenantInfo ​

  • Required prefix /v2/tenants/{tenantId}/info
  • Scope authenticated user tenant context
SpecsOperationPermission
Swagger - ScalarGET /no specific permission (authenticated user with tenant access)

Returns general information about the tenant (business name, address, configurations). Useful for displaying practice details in your application's interface or for verifying the tenant configuration.

Accounting ​

  • Required prefix /v2/tenants/{tenantId}/accounting
  • Scope giponext.invoices
SpecsOperationPermission
Swagger - ScalarGET /sectionsfatture.visualizza
Swagger - ScalarGET /issuersfatture.visualizza
Swagger - ScalarGET /issuers/{issuerId}fatture.visualizza

The accounting area provides access to economic summary data and invoice sections. It is the integration point for external accounting or management systems that need aggregated data.

FAQ ​

How do I trace doctors from an invoice? ​

The flow to follow across resources is:

Invoice → Items → LinkedPractices → Episode → Doctors
  1. From the invoice, navigate to Items → LinkedPractices to obtain:
    • episodeId (Episode)
    • practiceId (Detail line)
  2. Call the Episodes API: GET /episodes/{episodeId}
  3. In the response, filter the practices array using the practiceId obtained in step 1: practices[practiceId].doctors

📌 Note

Each invoice line can have multiple LinkedPractices and each practice can have multiple doctors.

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

Operational notes ​

  • Invoices: invoice creation is sequential per section.
  • TLS: transport security requirements are in TLS.
  • Operational FAQ: see FAQ.

For query parameters (filters), status codes, and full payloads, refer to Swagger.