Recuperare fatture tramite la legacy SOAP API: GetInboxDocuments, GetInboxDocument, gestione stato e download PDF.
Con la legacy SOAP API si recuperano i documenti ricevuti tramite polling. Si verifica periodicamente se ci sono nuovi documenti nella inbox, li si scarica e si aggiorna lo stato. Questo articolo descrive il flusso di ricezione completo.
Importante: Questa è la legacy SOAP API. Per nuove integrazioni si consiglia la REST API. La REST API offre webhook, evitando la necessità di polling.
Chiamare GetInboxDocuments con il filtro CreatedOn.From per recuperare solo i nuovi documenti. Dopo ogni chiamata salvare il valore CreatedOn più alto e utilizzarlo come punto di partenza per il controllo successivo.
<GetInboxDocuments>
<Filter>
<CreatedOn>
<From>2026-03-01T00:00:00</From>
</CreatedOn>
</Filter>
</GetInboxDocuments>
La risposta contiene i metadati di tutti i documenti nella inbox. Filtrare per Template/MasterId per selezionare solo il tipo di documento corretto. Per fatture standard utilizzare il MasterTemplateId:
GLDT9223370666504283001RA000000006DTP2000001
Utilizzare sempre il MasterTemplateId e non un ID specifico di versione, poiché non cambia con gli aggiornamenti del template.
Recuperare per ogni documento il payload completo con GetInboxDocument, utilizzando l'ExternalId dalla lista dei metadati:
<GetInboxDocument>
<ExternalId>het-external-id-uit-stap-1</ExternalId>
</GetInboxDocument>
Utilizzare GetDocumentPdf per recuperare la versione PDF del documento. Il PDF viene restituito come stringa codificata in base64.
Nota: se il PDF è ancora in fase di generazione, l'API restituisce il codice errore ERRDMN8000003. In tal caso attendere qualche secondo e riprovare.
Aggiornare lo stato del documento con SetInboxDocumentStatus. Questo è importante per il flusso di elaborazione e per la visibilità dello stato nella piattaforma.
La inbox utilizza i seguenti codici di stato. Utilizzare sempre il codice (non il nome) per filtrare e aggiornare.
Nel recupero dei documenti è possibile utilizzare diversi filtri per limitare i risultati:
ExternalIdCreatedOnModifiedOnSender / ReceiverTemplate/MasterIdStatusOltre ai documenti inbox è possibile recuperare anche i propri documenti inviati. Utilizzare GetOutboxDocuments e GetOutboxDocument. Il funzionamento è simile agli endpoint inbox, ma per i documenti inviati.
Per i documenti non ancora inviati (bozze) utilizzare GetDocuments e GetDocument. Questi endpoint funzionano con un DocumentId anziché un ExternalId. Le bozze hanno i propri codici di stato:
Intervallo: non effettuare polling più frequentemente di una volta al minuto. Per la maggior parte delle integrazioni una volta ogni 5-15 minuti è sufficiente.
Recupero incrementale: salvare sempre il valore CreatedOn più alto e utilizzarlo come filtro From alla chiamata successiva. In questo modo si evita di recuperare ripetutamente gli stessi documenti.
Rilevamento modifiche di stato: utilizzare il filtro ModifiedOn per rilevare quando lo stato di documenti esistenti è stato modificato, ad esempio dopo approvazione o pagamento.
Con la REST API non è necessario il polling: i webhook inviano automaticamente una notifica non appena arriva un nuovo documento. Consultare psb.econnect.eu per l'approccio moderno.
Passi alla REST API