L'invio di una e-fattura tramite l'API PSB è l'endpoint più utilizzato. Si invia un documento XML all'API nel formato prodotto dal proprio software, e la PSB si occupa di validazione, trasformazione automatica nel formato atteso dal destinatario, routing e consegna attraverso la rete appropriata.

POST /api/v1/{partyId}/salesInvoice/send

Il {partyId} nell'URL è l'identificativo Peppol dell'organizzazione mittente (il fornitore). La richiesta contiene il documento XML come body (content-type application/xml). La PSB rileva automaticamente il formato del documento e lo valida. Si può fornire qualsiasi formato supportato: UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA, ebInterface, Svefaktura, DICO, SETU e altri. La PSB trasforma automaticamente il documento nel formato atteso dal destinatario.

1. Upload: invii il documento XML all'endpoint
2. Validazione: la PSB valida il documento rispetto allo schema XSD e alle regole di business
3. Routing: la PSB cerca tramite SML/SMP come raggiungere il destinatario
4. Consegna: il documento viene consegnato attraverso il canale appropriato (Peppol, e-mail o altra rete)
5. Aggiornamento stato: si riceve una notifica webhook con lo stato di consegna

Attenzione: la PSB determina il destinatario in base all'EndpointID nel documento XML. Se questo elemento è assente o contiene un identificativo errato, l'invio fallisce con lo stato InvoiceSentError. Si assicuri che il sistema di origine compili correttamente l'EndpointID. Maggiori informazioni sugli identificativi e sul routing nell'articolo sugli identificativi Peppol.

La PSB supporta l'idempotency tramite l'header di richiesta X-EConnect-DocumentId. Includendo un proprio UUID con ogni richiesta di upload, si previene l'elaborazione duplicata:

X-EConnect-DocumentId: 550e8400-e29b-41d4-a716-446655440000

Se si invia lo stesso documentId nuovamente, l'API restituisce 409 Conflict, indicando al mittente che il documento è già stato elaborato.

Attenzione: Utilizzi sempre un UUID/GUID come documentId. Non utilizzi mai il numero di fattura, poiché questo causa problemi se si desidera reinviare una versione corretta della stessa fattura.

Prima di inviare una fattura, è possibile verificare tramite queryRecipientParty se e come il destinatario è raggiungibile:

POST /api/v1/{partyId}/salesInvoice/queryRecipientParty

Nel corpo della richiesta si passa un elenco di identificativi, ad esempio ["0106:12345678"], oppure un oggetto con partyIds e metaAttributes. I parametri di query opzionali sono ?preferredDocumentTypeId e ?includeOptions.

La risposta contiene informazioni su:

• Se il destinatario è registrato su Peppol
• Quali tipi di documento il destinatario può ricevere
• Tramite quale Access Point il destinatario è raggiungibile
• Quale canale la PSB utilizzerà per la consegna

Per lookup avanzati che includono l'URL dell'Access Point e il certificato AP, è disponibile una route separata:

GET /api/v1/peppol/deliveryOption?partyIds={id}&documentFamily=Invoice&isCredit=false

In caso di consegna fallita, la PSB applica automaticamente un meccanismo di retry:

• Fino a 8 tentativi distribuiti su circa 35 ore
• Solo per errori server 5xx (errori temporanei lato destinatario)
• Per ogni tentativo viene pubblicato un evento InvoiceSentRetry
• In caso di fallimento definitivo, si riceve un evento InvoiceSentError tramite il webhook

Errori comuni durante l'invio:

Nota: SI-UBL 1.2 (Simpler Invoicing 1.2) non è più ammesso sulla rete Peppol dal 1 gennaio 2024. Le fatture in questo formato risultano in un InvoiceSentError. Utilizzi NLCIUS (SI-UBL 2.0) o Peppol BIS Billing V3. Verifichi il CustomizationID nel documento XML se riscontra questo errore.

Un upload riuscito restituisce 200 OK con l'identificativo del documento nella PSB. Utilizzi questo identificativo per monitorare lo stato del documento tramite l'API o tramite i webhook.

A differenza di purchaseInvoice, l'endpoint salesInvoice non prevede DELETE. È una scelta deliberata, perché una fattura di vendita inviata o rifiutata è un evento rilevante per l'audit: il documento rimane tracciabile nell'audit trail, anche dopo il fallimento dell'invio.

I clienti a volte chiedono se una fattura di vendita rifiutata possa essere fermata o eliminata, ad esempio dopo aver già stornato internamente la fattura. La risposta è:

• Errore di validazione (4xx, ad esempio Invalid payload): la PSB porta il documento allo stato finale InvoiceSentError. Non viene eseguito alcun retry (solo gli errori 5xx vengono ritentati). Il documento non viene comunque consegnato al destinatario. Non è richiesta alcuna azione sulla PSB; il documento è nel suo stato finale e viene conservato 90 giorni a fini di audit.
• Nessun endpoint DELETE necessario: poiché il documento non è più attivo e non viene ritentato, non è necessario eliminarlo esplicitamente per fermare l'invio.
• Inviare una correzione tramite un nuovo documento: se la fattura originale era errata ed era già stata (parzialmente) consegnata, utilizzi una nota di credito o una fattura di correzione secondo il flusso contabile standard. Il documentId originale rimane come riferimento nell'audit trail.

Questa differenza nel ciclo di vita tra salesInvoice (senza DELETE) e purchaseInvoice (con DELETE) deriva dal ruolo: una fattura in uscita è un'azione commerciale registrata dall'emittente che deve essere legalmente tracciabile; una fattura in entrata può essere rimossa dal sistema del destinatario dopo un download riuscito.

All'invio di una fattura, la PSB gestisce anche la reportistica fiscale. Nell'ambito della direttiva ViDA (VAT in the Digital Age), la PSB genera automaticamente un DRR (Digital Reporting Requirement) sulla base dei dati della fattura e lo trasmette all'autorità fiscale competente. Come integratore non è necessario fare nulla di aggiuntivo: il DRR viene derivato dalla stessa fattura inviata tramite il normale endpoint. I messaggi di stato e di reportistica CTC sono inclusi nel prezzo del documento.

Per impostazione predefinita, la PSB seleziona automaticamente il canale migliore. Con il parametro di query ?channel={hookId}, è possibile forzare un canale di consegna specifico (ad es. una rete specifica o un fallback e-mail).

Gli allegati (PDF, immagini) possono essere incorporati come base64 nel documento UBL come AdditionalDocumentReference. La PSB elabora correttamente gli allegati incorporati e li consegna insieme alla fattura.

Nota: L'endpoint di invio accetta un massimo di 24 MB per richiesta (overhead HTTP incluso). Con allegati codificati in base64, il payload cresce di circa il 33%, quindi un PDF di 18 MB produce una richiesta di circa 24 MB. I payload che superano il limite vengono rifiutati dal web server con HTTP 500 (non 413), prima che avvenga la validazione applicativa. Riduca gli allegati voluminosi o li invii tramite un canale separato.

Suggerimento: L'attuale standard Peppol BIS Billing 3.0 supporta un massimo di un OrderReference per fattura. Se una fattura si riferisce a più ordini, devono essere inviate più fatture.

Suggerimento: Alcuni destinatari segnalano errori per fatture con un prefisso di namespace XML (ad es. <urn:Invoice> invece di <Invoice>). Entrambe le forme sono XML tecnicamente valido secondo la specifica W3C. Se un destinatario lo cita come motivo di rifiuto, non è un rifiuto valido all'interno della rete Peppol. Il destinatario deve utilizzare un parser XML che gestisca correttamente sia i namespace con prefisso sia quelli predefiniti.

Desidera prima verificare se il documento è valido? Utilizzi la Validate API.