In questo articolo si percorrono i primi passi per lavorare con la PSB API: dalla richiesta di un account all'esecuzione della prima chiamata API. Al termine avrà una connessione funzionante con l'ambiente di test e saprà come è strutturata l'API.

Per utilizzare la PSB API sono necessarie delle credenziali. Può richiederle tramite l'assistente sandbox. Dopo la registrazione riceverà tre informazioni:

Suggerimento: richieda direttamente le credenziali sia per l'ambiente di accettazione che per quello di produzione. In questo modo può testare in sicurezza senza il rischio di inviare accidentalmente fatture reali.

A seconda del flusso OAuth2 scelto, potrebbe ricevere anche un username e una password per il flusso Resource Owner Password Credentials. Per le integrazioni server-to-server si raccomanda il flusso Client Credentials, per il quale sono necessari solo clientId e clientSecret.

La PSB dispone di due ambienti. Utilizzi l'ambiente di accettazione per lo sviluppo e i test, e l'ambiente di produzione per le transazioni reali.

L'ambiente di accettazione funziona in modo identico alla produzione: richieste di token, chiamate API e webhook si comportano allo stesso modo. La differenza è che i documenti non vengono inviati alla rete Peppol reale.

Attenzione: utilizzi credenziali separate per accettazione e produzione. In questo modo evita che le credenziali di test finiscano accidentalmente in un ambiente di produzione.

Ogni richiesta API alla PSB richiede un Bearer token. Il token viene richiesto all'Identity Server tramite una richiesta POST a /connect/token.

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

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

In caso di successo riceverà una risposta JSON contenente l'access token:

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

Il token è valido per 3600 secondi (1 ora). Dopo la scadenza è sufficiente richiedere un nuovo token. Il processo di autenticazione completo, incluso il flusso Resource Owner Password Credentials e il rinnovo dei token, è descritto nell'articolo sull'autenticazione.

Con un token valido può effettuare chiamate all'API. Un buon punto di partenza è l'endpoint GET /api/v1/me, che restituisce informazioni sul Suo account e le organizzazioni (party) ad esso collegate.

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

Una risposta riuscita contiene i dati del Suo account e un elenco delle party per le quali è autorizzato. Ogni party ha un PartyId (ad esempio un numero di Camera di Commercio o OIN) e permessi che determinano cosa può fare: inviare documenti, riceverli, eliminarli o gestire gli hook.

I documenti possono essere forniti in qualsiasi formato supportato dalla PSB: UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA e più di 20 altri standard. La PSB rileva automaticamente il formato e lo trasforma nel formato atteso dal destinatario. Non è quindi necessario sapere quale formato utilizza il destinatario.

La PSB API restituisce tutte le risposte in formato JSON. I documenti stessi (fatture, ordini) vengono inviati e ricevuti come XML.

I codici di stato HTTP seguono le convenzioni REST standard:

In caso di errore 4xx, la risposta contiene un messaggio di errore che indica il problema. Per errori 5xx è consigliabile ritentare la richiesta con exponential backoff.

La PSB prevede due ruoli che determinano cosa un utente può fare.

ApUser è il ruolo standard. Con questo ruolo è possibile inviare e ricevere documenti e gestire i webhook per le party a cui si è collegati.

ApManager dispone inoltre di diritti di amministrazione: creare e eliminare utenti, registrare organizzazioni nel registro Peppol SMP/SML e utilizzare l'Enrollment API per configurare nuove party.

Per ogni party i permessi vengono impostati separatamente: canSendDocument, canReceiveDocument, canRemoveDocument e canManageHook. Ogni party registrata deve essere collegata ad almeno un account ApUser.

Il riferimento API completo è disponibile come Swagger UI su psb.econnect.eu. Qui può esplorare gli endpoint, visualizzare i formati di request e response e testare le chiamate API con il proprio token. Il swagger.json è anche scaricabile, per generare codice client con strumenti come OpenAPI Generator nella lingua di Sua scelta.