SOAP invio | eConnect

Con l'endpoint SendDocument della legacy SOAP API si inviano fatture e altri documenti tramite la piattaforma eConnect. La piattaforma determina automaticamente il percorso migliore: tramite la piattaforma eConnect stessa, tramite Peppol o come fallback via e-mail.

Importante: Questa è la legacy SOAP API. Per nuove integrazioni si consiglia la REST API.

Come funziona SendDocument

Alla chiamata di SendDocument si fornisce il documento sorgente insieme ai dati del mittente e del destinatario. La piattaforma cerca quindi il destinatario in tre fasi:

Piattaforma eConnect: il destinatario è anch'egli un utente della piattaforma? Allora il documento viene consegnato direttamente nella inbox.
Peppol: il destinatario è reperibile sulla rete Peppol? Allora il documento viene instradato tramite Peppol.
E-mail (fallback): se nessuna delle due opzioni è possibile e un indirizzo e-mail è stato fornito, il documento viene inviato via e-mail.

Parametri obbligatori

Parametro

Descrizione

Via/ReferenceId

Identificazione del mittente (il proprio EConnectPartyId, numero XCNL)

To/ReferenceId

Identificazione del destinatario (EConnectPartyId o identificativo Peppol come 0106:numero-KvK)

To/EmailAddress

Indirizzo e-mail del destinatario (utilizzato come fallback quando il routing tramite piattaforma e Peppol non è possibile)

Subject

Oggetto del documento

Payload

Il documento stesso, come UBL-XML. Nota: inviare l'XML senza prologo XML (<?xml ...?>)

TemplateId

L'ID template che indica il tipo di documento

Esempio di chiamata

<SendDocument>
  <Document>
    <Via>
      <ReferenceId>XCNL-123456</ReferenceId>
    </Via>
    <To>
      <ReferenceId>0106:12345678</ReferenceId>
      <EmailAddress>facturatie@voorbeeld.nl</EmailAddress>
    </To>
    <Subject>Factuur 2026-001</Subject>
    <Payload><!-- UBL-XML zonder prolog --></Payload>
    <TemplateId>GLDT9223370666504283001RA000000006DTP2000001</TemplateId>
  </Document>
</SendDocument>

Il TemplateId GLDT9223370666504283001RA000000006DTP2000001 è il MasterTemplateId per una fattura standard. Utilizzare sempre il MasterTemplateId (non un codice versione), poiché rimane stabile tra le versioni del template.

Risposta e ExternalId

Dopo una chiamata riuscita, l'API restituisce un ExternalId. Questo è l'ID univoco del documento inviato nella piattaforma eConnect. Se la risposta non contiene un ExternalId, il documento non è stato inviato. In tal caso verificare il messaggio di errore nella risposta.

Conservare sempre l'ExternalId: è necessario per richiedere successivamente lo stato del documento.

DeliveryMethod

L'API restituisce nella risposta anche il DeliveryMethod, in modo da sapere tramite quale canale il documento è stato consegnato:

Valore

Significato

ToInbox

Consegnato nella inbox del destinatario sulla piattaforma eConnect

ToPeppol

Inviato tramite la rete Peppol

ToEmail

Inviato via e-mail

OutboxOnly

Salvato solo nella propria outbox (non consegnato)

None

Nessuna consegna possibile

Monitoraggio stato

Dopo l'invio è possibile seguire lo stato del documento con due endpoint:

Endpoint

Funzione

GetOutboxDocuments

Ottenere la lista dei documenti inviati. Filtrare per ModifiedOn per vedere solo i documenti modificati di recente.

GetOutboxDocument

Richiedere un documento specifico in base all'ExternalId.

GetOutboxDocumentStatus

Richiedere solo lo stato, senza il documento completo.

Suggerimenti

UBL-XML senza prologo: il Payload deve contenere UBL-XML senza la dichiarazione <?xml version="1.0" encoding="UTF-8"?>. Se si include il prologo, il documento potrebbe non essere elaborato correttamente.

Utilizzare MasterTemplateId: filtrare sempre per Template/MasterId anziché per un ID template specifico. Il MasterTemplateId non cambia con gli aggiornamenti di versione del template.

Gestione errori: verificare la risposta per i codici di errore. Le serie di errore 400 (validazione) e 200 (funzionale) sono le più comuni per gli errori di invio. Consultare la pagina di autenticazione per la panoramica completa delle serie di codici di errore.

La REST API offre per l'invio funzionalità aggiuntive come webhook per notifiche di stato e retry automatici in caso di errori. Consultare psb.econnect.eu per l'approccio moderno.

Migri alla REST API

Correlati