L'API PSB di eConnect utilizza OAuth 2.0 per l'autenticazione. Ogni richiesta API contiene un Bearer token che si ottiene dall'Identity Server di eConnect. Questo token è valido per un'ora e contiene tutte le informazioni di cui la PSB necessita per determinare chi è Lei, per conto di quale organizzazione sta lavorando e cosa è autorizzato a fare.

In questo articolo verrà illustrato l'intero processo di autenticazione: dalla comprensione del modello di autenticazione alla richiesta e all'utilizzo dei token.

La PSB lavora con quattro livelli di identificazione. Ogni livello risponde a una domanda diversa e insieme determinano l'accesso all'API.

Livello 1: Applicazione (clientId + clientSecret) Identifica il software che si connette alla PSB. Di norma, un partner software utilizza un unico set clientId/clientSecret per tutti i propri clienti finali. Questo semplifica l'onboarding: i clienti finali devono compilare meno dati tecnici e la probabilità di errori di configurazione è minore. Tutti i clientId hanno lo stesso scope (ap) e quindi gli stessi permessi funzionali.

Livello 2: Cliente finale (username + password) Identifica per conto di quale organizzazione si sta lavorando. Per ogni cliente finale, eConnect crea un account utente PSB collegato a uno o più partyId (numero della camera di commercio, partita IVA, OIN, numero di impresa belga). Con il flusso Resource Owner Password Credentials, si forniscono un username e una password che determinano a quali party è possibile accedere. Con il flusso Client Credentials ciò non è necessario, poiché i permessi sono collegati direttamente all'applicazione. Nome utente e password vengono generalmente forniti direttamente al cliente finale; il cliente finale li condivide poi con il fornitore del software. Quando si crea un account utente cliente finale all'interno del proprio tenant PSB (ad esempio per l'integrazione 4PS Business Central), la password non puo contenere caratteri speciali, ad eccezione del punto esclamativo (!).

Livello 3: Ambiente (tenantId) Offre la separazione amministrativa tra gli ambienti. Ogni cliente finale riceve di norma un proprio tenant, il che garantisce una separazione completa di messaggi, configurazione e logging. Alcuni partner software raggruppano più clienti finali in un unico tenant per una gestione centralizzata; altri scelgono un tenant separato per cliente per il massimo isolamento. I tenant non possono essere uniti, ma gli account utente possono essere modificati o ampliati.

Livello 4: Logging (subscription key, legacy) L'header Subscription-Key era originariamente destinato all'identificazione nei file di log dell'API. Per l'API PSB questo header non è più richiesto. Se lo invia, il valore deve essere valido. eConnect emette talvolta ancora subscription key perché consentono di ricondurre ogni richiesta nei log a un partner software specifico. Nota: per la piattaforma eConnect (platform.econnect.eu) la subscription key è ancora obbligatoria.

Si richiede un token inviando una richiesta POST all'endpoint /connect/token dell'Identity Server.

Questo è il flusso consigliato per le integrazioni server-to-server. Si inviano solo il proprio clientId e clientSecret.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=il-suo-client-id
&client_secret=il-suo-client-secret
&scope=ap

Con questo flusso, si forniscono anche un nome utente e una password. È utile quando i permessi sono legati a un utente finale specifico.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=il-suo-client-id
&client_secret=il-suo-client-secret
&username=il-suo-nome-utente
&password=la-sua-password
&scope=ap

In caso di richiesta riuscita, si riceve un oggetto JSON contenente l'access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "ap"
}

Il campo expires_in indica per quanti secondi il token è valido. Il valore predefinito è 3600 secondi (1 ora).

Includa il Bearer token nell'header Authorization di ogni richiesta API alla PSB:

GET /api/v1/me HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

La PSB valida il token a ogni richiesta. Se il token è invalido o scaduto, si riceve una risposta 401 Unauthorized.

Un Bearer token è valido per 3600 secondi. Dopo la scadenza, è necessario richiedere un nuovo token tramite lo stesso endpoint /connect/token. Non esiste un flusso di aggiornamento separato: si ripete semplicemente la richiesta del token.

In pratica, è consigliabile richiedere un nuovo token poco prima della scadenza dell'attuale, ad esempio dopo 3500 secondi. Così si evita che una chiamata API fallisca a causa di un token scaduto mentre la richiesta è in transito.

1. Token richiesto              → valido fino a t+3600s
2. Dopo ~3500s: nuovo token     → token precedente ancora ~100s valido
3. Passare al nuovo token

Conservi il token nella Sua applicazione e lo riutilizzi per più richieste. Non richieda un nuovo token a ogni chiamata API, poiché ciò genera un carico inutile sull'Identity Server.

Per impostazione predefinita, un partner software utilizza un unico set clientId/clientSecret per tutti i clienti finali. In alcune situazioni è consigliabile utilizzare più set:

• Separare test e produzione. Utilizzi un clientId distinto per l'ambiente di accettazione (accp-identity.econnect.eu) e per la produzione (identity.econnect.eu). Così si evita che credenziali di test finiscano accidentalmente in produzione.
• Installazioni on-premise. Se il software viene eseguito presso il cliente finale e questi ha accesso alla configurazione, un clientSecret condiviso può rappresentare un rischio di sicurezza. Con un clientId distinto per cliente, si limita il danno in caso di divulgazione delle credenziali.
• Permessi separati per integrazione. Se si sviluppano più applicazioni autonome, ciascuna con esigenze API diverse (ad esempio un modulo fatturazione e un modulo ordini), è possibile utilizzare un clientId proprio per applicazione con solo i permessi necessari.

La revoca di un clientSecret riguarda solo il clientId corrispondente. Gli altri clienti o integrazioni non sono coinvolti.

Se riceve un 401 durante una chiamata API alla PSB, verifichi innanzitutto se il token è ancora valido. Nella maggior parte dei casi è scaduto e basta richiederne uno nuovo.

Il diagramma seguente mostra come un'applicazione richiede un token all'Identity Server e poi utilizza quel token per chiamare l'API PSB.

Il riferimento API completo, comprensivo di tutti gli endpoint e i formati di richiesta/risposta, è disponibile nella documentazione Swagger interattiva.