Quando una fattura per la Sua organizzazione arriva tramite Peppol o un'altra rete, la PSB salva il documento e invia una notifica al Suo webhook. In questo articolo scoprirà come ricevere la notifica, scaricare il documento e configurare la gestione dello stato.

La ricezione di una fattura avviene in quattro passaggi:

1. Notifica: la PSB invia un evento webhook InvoiceReceived al Suo endpoint
2. Download: recupera il documento tramite l'endpoint PurchaseInvoice
3. Elaborazione: elabora la fattura nel Suo sistema
4. Pulizia (opzionale): elimina il documento dalla PSB

Per ricevere fatture è necessario un webhook in ascolto sul topic InvoiceReceived. Lo registri tramite la Hook API:

POST /api/v1/hook

{
  "action": "https://mijn-systeem.nl/webhook/invoices#mijnSecretKey",
  "topics": ["InvoiceReceived"]
}

Non appena una fattura arriva, il Suo endpoint riceve una richiesta POST con un payload JSON. Questo payload contiene, tra l'altro, il documentId e il partyId con cui può recuperare il documento.

Suggerimento: configuri anche un webhook sul topic InvoiceReceivedError per ricevere notifiche in caso di problemi nella ricezione.

Utilizzi il documentId dal payload del webhook per recuperare la fattura:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

La risposta contiene il documento XML (per impostazione predefinita nel formato originale). Desidera ricevere il documento in un altro formato? Utilizzi il parametro targetDocumentTypeId:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download?targetDocumentTypeId={URN}

La PSB trasforma automaticamente il documento nel formato specificato prima di restituirlo.

La PSB conserva i documenti ricevuti secondo questo schema:

Si raccomanda di recuperare i documenti immediatamente dopo la ricezione e di salvarli nel proprio sistema. Non faccia affidamento sulla PSB come archivio a lungo termine.

Dopo l'elaborazione può eliminare il documento manualmente:

DELETE /api/v1/{partyId}/purchaseInvoice/{documentId} HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Questo elimina definitivamente il documento dalla PSB. L'audit trail rimane disponibile.

Dopo la ricezione può aggiornare lo stato di elaborazione di una fattura d'acquisto. Questo è particolarmente rilevante se desidera inviare Invoice Response (messaggi di stato) al mittente. Per maggiori dettagli, consulti l'articolo Inviare un Invoice Response.

La PSB invia automaticamente un messaggio MLS (Message Level Status) alla parte mittente dopo la ricezione di un documento. Questo conferma che il documento è stato ricevuto e consegnato. Come integratore non deve configurare nulla per questo: la PSB lo gestisce completamente. Se invia documenti Lei stesso, riceve feedback MLS tramite il topic webhook MessageLevelStatusReceived. Consulti Configurare i webhook per la configurazione.

Se non è possibile configurare webhook (ad esempio in un ambiente on-premise senza traffico internet in ingresso), può anche recuperare le fatture tramite polling:

GET /api/v1/{partyId}/purchaseInvoice HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Questo endpoint restituisce un elenco delle fatture d'acquisto disponibili. I webhook sono tuttavia sempre il metodo preferito grazie all'elaborazione in tempo reale e al minor carico sull'API.

Attenzione: per le integrazioni on-premise consideri anche il reverse webhook (HTTPS inbound hook), con cui la PSB invia i documenti senza che il Suo sistema debba essere direttamente raggiungibile da internet.

• Elabori in modo idempotente: in casi eccezionali la PSB può consegnare un evento più volte. Verifichi dal Suo lato se ha già elaborato un documento prima di reimportarlo.
• Scarichi immediatamente: recuperi i documenti il prima possibile dopo la notifica webhook. La retention di 90 giorni è una rete di sicurezza, non una strategia di archiviazione.
• Registri il documentId: conservi il documentId PSB nel Suo sistema per la tracciabilità e l'eventuale troubleshooting.
• Converti il formato: se necessita di un formato XML specifico, utilizzi targetDocumentTypeId durante il download invece di convertire autonomamente.
• Retry dei webhook: se il Suo endpoint non è temporaneamente raggiungibile, la PSB riprova la consegna della notifica per un massimo di 5 giorni. Periodo di inattività prolungato? Utilizzi i batch hook come fallback per recuperare i documenti persi.

Consulti gli endpoint PurchaseInvoice completi e i modelli di risposta su psb.econnect.eu.