Prima di poter utilizzare la legacy SOAP API, sono necessarie le App Key e bisogna ottenere un SecurityToken tramite l'endpoint Login. Questo articolo spiega passo dopo passo come funziona.

Importante: Questa è la legacy SOAP API. Per nuove integrazioni si consiglia la REST API, che utilizza OAuth 2.0.

Le App Key sono composte da una Consumer Key e un Consumer Secret. Si creano nella piattaforma eConnect nel menu Connessioni. Per questo è necessario un ruolo di amministratore.

Sono disponibili due tipi di app:

Per la variante commercialista si utilizzano le App Integration Request: il cliente concede tramite la piattaforma l'autorizzazione all'accesso alla propria amministrazione. Questo è rilevante per i fornitori di software che operano per conto di più clienti.

L'autenticazione avviene in due fasi:

Fase 1: Login

Chiamare l'endpoint Login con la propria Consumer Key e Consumer Secret. Si riceve un SecurityToken in risposta.

<Login>
  <ConsumerKey>jouw-consumer-key</ConsumerKey>
  <ConsumerSecret>jouw-consumer-secret</ConsumerSecret>
</Login>

Fase 2: fornire il SecurityToken

Fornire il SecurityToken nell'header SOAP per tutte le chiamate successive. Il token è valido per 4 ore. È anche possibile richiedere un nuovo token per ogni sessione.

<soap:Header>
  <SecurityToken>ontvangen-security-token</SecurityToken>
</soap:Header>

Fase 3: ottenere le informazioni dell'account

Dopo un login riuscito, chiamare GetAccountParties per ottenere il proprio EConnectPartyId (numero XCNL). Questo ID è necessario per l'invio e la ricezione dei documenti.

Il WSDL contiene la specifica completa di tutti gli endpoint, i tipi di dato e i codici di errore disponibili. È possibile importare il WSDL in strumenti come SoapUI o Visual Studio per generare automaticamente il codice client.

Transfer-Encoding=chunked: la SOAP API non supporta il chunked transfer encoding. Assicurarsi che il proprio client HTTP invii l'header content-length anziché utilizzare il chunked encoding. Questo è uno degli errori di implementazione più comuni.

Token scaduto: se il SecurityToken è più vecchio di 4 ore, si riceve un errore di autenticazione (serie codice errore 600). Richiedere un nuovo token tramite Login.

Mancata subscriptionKey: senza una subscriptionKey valida nell'URL dell'endpoint, tutte le richieste vengono rifiutate. Verificare che la key sia corretta e ancora attiva.

La SOAP API restituisce codici di errore strutturati nel formato ERR + opcode + serie + ID. Le serie di codici di errore indicano il tipo di errore:

Si sta valutando il passaggio a OAuth2 e alla REST API? Consultare la documentazione PSB su psb.econnect.eu per il flusso di autenticazione moderno.

• SOAP API: panoramica ed endpoint
• SOAP: invio fatture (SendDocument)
• SOAP: ricezione fatture
• Panoramica PSB REST API