Cos'è Peppol BIS 3.0? Un'introduzione pratica per sviluppatori

Se sviluppi software di fatturazione in Europa, prima o poi incontrerai Peppol.

Per molti sviluppatori, il primo incontro è disorientante: XML ovunque, identificatori strani, discovery SMP e SML, fatture UBL, regole EN16931, errori di validazione con messaggi criptici.

Questo articolo spiega Peppol BIS Billing 3.0 da una prospettiva tecnica pratica. Niente gergo aziendale. Solo le parti che gli sviluppatori devono davvero capire.

Cos’è Peppol?

Peppol è una rete di interoperabilità europea per lo scambio di documenti aziendali elettronici. Il caso d’uso più comune è la fatturazione elettronica.

Invece di inviare PDF via e-mail, i fornitori inviano documenti fattura strutturati direttamente tra sistemi. Una fattura Peppol è leggibile dalla macchina, standardizzata, validata ed elaborabile automaticamente.

Questo consente ai sistemi contabili e alle piattaforme ERP di elaborare le fatture con un intervento manuale minimo.

Cosa significa BIS 3.0?

BIS sta per Business Interoperability Specifications. Peppol BIS Billing 3.0 definisce:

• la struttura della fattura
• i campi obbligatori
• le regole di validazione
• le liste di codici consentiti
• le aspettative di trasporto

La sintassi è basata su UBL 2.1 ed EN16931. In pratica: EN16931 definisce il modello semantico della fattura, UBL definisce la sintassi XML, e Peppol aggiunge regole di interoperabilità sopra. Puoi leggere di più sul modello semantico EN16931 in Capire EN16931.

Perché l’Europa si sta muovendo verso la fatturazione elettronica obbligatoria

Diversi paesi UE si stanno orientando verso la fatturazione elettronica obbligatoria. Esempi includono Belgio, Germania, Francia, Polonia e Italia. I governi vogliono ridurre le frodi IVA, elaborazione fiscale automatizzata, appalti interoperabili e scambio standardizzato di fatture.

Questo significa che la conoscenza di Peppol sta diventando una conoscenza di infrastruttura.

Come appare una fattura Peppol?

Una fattura Peppol è un documento XML UBL 2.1.

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">

  <cbc:CustomizationID>
    urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1
  </cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
  <cbc:ID>INV-2025-001</cbc:ID>
  <cbc:IssueDate>2025-11-12</cbc:IssueDate>

  <cac:AccountingSupplierParty>
    <!-- seller details -->
  </cac:AccountingSupplierParty>

  <cac:AccountingCustomerParty>
    <!-- buyer details -->
  </cac:AccountingCustomerParty>

  <cac:LegalMonetaryTotal>
    <!-- totals -->
  </cac:LegalMonetaryTotal>
</Invoice>

A differenza dei PDF, questi documenti sono pensati per essere consumati dal software. Un singolo campo non valido può causare il rifiuto.

Il ruolo di EN16931

EN16931 è lo standard semantico europeo per le fatture. Definisce concetti come numero di fattura, importo IVA, identificatore dell’acquirente, termini di pagamento e dettagli fiscali. Peppol BIS 3.0 si costruisce sopra questo modello semantico.

Per questo motivo gli sviluppatori vedono spesso riferimenti come BT-10, BT-49 e BR-CO-10. Questi sono termini aziendali e regole aziendali definiti da EN16931.

I problemi comuni degli sviluppatori

La maggior parte delle implementazioni Peppol incontra prima o poi gli stessi problemi.

Problemi di namespace. UBL usa molti namespace XML. Sbagliare le dichiarazioni produce errori criptici del parser prima che venga eseguita qualsiasi logica aziendale.

Errori di validazione. Gli errori di validazione Schematron possono essere difficili da debuggare. I messaggi di errore fanno riferimento a codici BR che richiedono la lettura della specifica EN16931 per essere interpretati.

Formati degli identificatori. Gli ID dei partecipanti e degli endpoint sono rigidi. Un’azienda belga che utilizza lo schema del numero d’impresa 0208 deve anteporre esattamente quel codice schema.

Firme XML. I problemi di canonicalizzazione spesso rompono la validazione della firma. Questa è una categoria di bug particolarmente insidiosa perché l’XML sembra corretto quando lo si legge, la firma è valida, ma i due non si verificano l’uno rispetto all’altro. Vedi Insidie della validazione della firma XML in Peppol per i dettagli.

Profili specifici per paese. Germania, Belgio e Francia applicano ciascuno requisiti aggiuntivi rispetto alla specifica base Peppol BIS 3.0. Un documento valido per un paese potrebbe non essere valido per un altro.

Discovery SMP e SML

Peppol utilizza un meccanismo di discovery simile al DNS. Il flusso funziona approssimativamente così:

1. Hash dell’identificatore del partecipante
2. Costruzione di un hostname DNS dall’hash
3. Query all’SML (Service Metadata Locator) per trovare l’SMP del partecipante
4. Query all’SMP (Service Metadata Publisher) per recuperare i metadati del servizio
5. Determinazione dei tipi di documento supportati e degli URL degli endpoint
6. Consegna del documento tramite un Access Point

La risposta SMP è a sua volta un documento XML firmato. Quella firma è ciò che causa i problemi di canonicalizzazione menzionati sopra.

Perché le fatture PDF non sono sufficienti

Le tradizionali fatture PDF sono leggibili dall’uomo. Le fatture Peppol sono leggibili dalla macchina. Molti sistemi moderni combinano entrambe: PDF/A-3 per la rappresentazione visiva, XML incorporato per l’automazione.

Questa è la base di Factur-X e ZUGFeRD. Vedi Factur-X vs ZUGFeRD vs XRechnung vs Peppol per un confronto su come questi formati si relazionano tra loro.

La parte difficile

Generare XML UBL valido non è la parte difficile. La parte difficile è generare XML che sopravviva all’interoperabilità nel mondo reale:

• Validazione Schematron attraverso più set di regole nazionali
• Discovery SMP con prefissi di namespace dinamici
• Verifica della firma XML su documenti che sono stati ri-serializzati
• Campi obbligatori specifici per paese che non sono nella specifica base
• Regole di arrotondamento che producono risultati diversi a seconda che si arrotondi per riga o per documento

Nei prossimi articoli tratteremo: EN16931 in dettaglio, UBL vs CII, i meccanismi interni della discovery SMP, le insidie della firma XML e gli errori comuni di validazione Peppol.

Il vero costo della parte difficile non è leggere le specifiche. È l’overhead operativo: mantenere aggiornati i set di regole Schematron con ogni release di Peppol BIS, gestire correttamente i fallimenti della discovery SMP, mantenere le variazioni delle regole specifiche per paese tra Germania, Belgio, Francia e Polonia.

SealDoc è un’API che gestisce questo livello. Invii i dati della tua fattura come payload JSON. L’API genera il documento UBL, esegue la validazione Schematron EN16931 e Peppol BIS 3.0, effettua la discovery SMP, racchiude il documento in una busta AS4 e lo consegna all’Access Point del destinatario. Se il destinatario non è raggiungibile o il documento non supera la validazione, ricevi un errore strutturato che indica esattamente quale fase è fallita e perché.

Per il testing e il debug, il validatore pubblico SealDoc accetta file di fattura UBL e CII e restituisce un report in linguaggio semplice di ogni regola EN16931 e Peppol BIS 3.0 violata, con il numero BT e il codice della regola aziendale. Non è richiun account.