Skip to content

API reference ​

Integration type ​

GipoNext APIs are exclusively REST (HTTP + JSON). Each operation follows the synchronous request/response model: your client sends a request, the server processes it and returns a response.

No other integration models are supported. In particular:

  • No webhooks — GipoNext does not send push notifications to your server when data changes.
  • No WebSockets — no bidirectional real-time communication channel is available.
  • No message queues — no integration via broker (RabbitMQ, Azure Service Bus, etc.) is available for external systems.

If you need to know when data changes, the only approach is polling: query the relevant endpoint periodically at reasonable intervals (see Rate limiting for applicable limits).

OpenAPI 2.0 specification ​

The APIs are described by an OpenAPI 2.0 specification (the format formerly known as Swagger). It is a machine-readable JSON document that describes all endpoints, parameters, request/response models, and authentication schemes.

Specification URL:

https://api.giponext.it/swagger/docs/v2

You can use this URL to:

  • Import the collection into development tools such as Postman, Bruno, Insomnia, or Hoppscotch and have all endpoints ready to call.
  • Generate client SDKs for your language with tools like OpenAPI Generator, NSwag, AutoRest, or Kiota.
  • Browse interactive documentation on Swagger UI, where you can explore endpoints, read models, and try calls with OAuth authentication.
  • Explore the APIs with the integrated Scalar client on this site.

Generating a client: why and how ​

Generating a client SDK from the OpenAPI spec is the recommended best practice for integrating GipoNext APIs. A generated client:

  • Saves work — you do not write request, response, serialization, and endpoint handling classes by hand.
  • Reduces errors — types, field names, and method signatures are derived from the spec, not manual copy-paste.
  • Updates easily — when the spec changes, regenerate the client and the compiler will flag incompatibilities.
  • Ensures consistency — the client reflects what the server exposes, including optional fields, enums, and formats.

💡 Tip

Include client generation in your build pipeline. Each spec update will produce an updated client, and the compiler will flag incompatibilities.

OAuth client configuration ​

To call the APIs, your client (generated or manual) must authenticate via OAuth 2.0. The parameters to configure are the same regardless of the tool you use.

Common parameters ​

ParameterValueWhere to find it
Grant Typeauthorization_codeFixed
Auth URLhttps://account.gipo.it/connect/authorizeFixed
Token URLhttps://account.gipo.it/connect/tokenFixed
Client IDYour client_idOAuth client detail page on account.gipo.it
Client SecretYour client_secret"Secrets" section of the OAuth client
ScopesSpace-separated scopes (e.g. openid offline_access giponext.patients)Based on endpoints you need — see Authentication and authorization
Redirect URIDepends on your client (see below)Must match one of the redirect URIs registered on account.gipo.it
StateRandom valueGenerated by the client for CSRF protection — verify it in the callback

⚠️ Redirect URI

The redirect URI configured in your tool must be identical to the one registered in the OAuth client configuration on account.gipo.it. Even a small difference (trailing slash, http vs https) causes an authorization error.

Client configuration ​

Each development tool has its own interface for OAuth configuration. Below are the settings for the most common clients.

yaml
# Specs / Scalar tab on this site
# OAuth endpoints and scopes are preconfigured.
# You only need to enter Client ID and Client Secret.

Client ID:      <your client_id>
Client Secret:  <your client_secret>
Scope:          <scopes required for that session>

# to register on account.gipo.it:
Redirect URI:
  - https://api.giponext.it/specs/scalar.html
  - https://api.giponext.it/en/specs/scalar.html
yaml
# Authorization tab in the collection or request
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:        <your client_id>
Client Secret:    <your client_secret>
Scope:            <scopes required for that session>
State:            <generated automatically>

# to register on account.gipo.it:
Redirect URI:
  - https://oauth.pstmn.io/v1/callback
yaml
# Auth tab in the 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:          <your client_id>
Client Secret:      <your client_secret>
Scope:              <scopes required for that session>
State:              <generated automatically>

# to register on account.gipo.it:
Redirect URI:
  - https://oauth.usebruno.com/callback
  # Bruno also supports local callback:
  - http://localhost:3000/oauth/callback
yaml
# Auth tab in the request or 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:          <your client_id>
Client Secret:      <your client_secret>
Scope:              <scopes required for that session>

# to register on account.gipo.it:
Redirect URI:
  - http://localhost:7171/oauth/callback

Rules valid for all clients ​

  1. Set Grant Type = Authorization Code.
  2. If the client supports PKCE, enable it.
  3. After authorization, use the token with the header Authorization: Bearer <access_token>.
  4. When the token expires (response 401), renew it with the refresh token — see OAuth flows and tokens.

API calls after login ​

After obtaining a valid access token, all calls follow the same pattern.

Base URL:

https://api.giponext.it/v2

First call — obtain tenantId:

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

The response contains the list of tenants the user can access. Use the tenantId in all subsequent calls.

Example — list patients:

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

For the full resource and endpoint map, see Entities and operations.

Advanced settings ​

You can use Postman scripts to automate repetitive operations. This example saves tenantId from the UserInfo response and injects it automatically into all routes that require it.

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

Next steps ​