Wat is UBL (Universal Business Language)?

UBL in twee zinnen

UBL, voluit Universal Business Language, is een verzameling XML-schema's voor handelsdocumenten, beheerd door de standaardenorganisatie OASIS. Elk document, van offerteaanvraag tot creditnota, heeft een vaste structuur met vaste elementnamen, zodat het systeem van de ontvanger weet waar het factuurnummer, het bedrag en het ordernummer staan.

UBL 2.1 is ook vastgelegd als ISO/IEC 19845. Die versie is de basis van de Nederlandse e-factuur SI-UBL 2.0 en van Peppol BIS Billing 3.0. Hoe die twee zich tot elkaar en tot de Europese norm verhouden, staat in wat is e-facturatie. Deze pagina gaat over UBL zelf.

Versies en documenten

UBL is achterwaarts compatibel binnen versie 2: een document dat geldig is onder 2.1, is ook geldig onder 2.5. Nieuwe versies voegen documentsoorten en elementen toe, en maken soms een verplicht element optioneel. UBL 2.5 voegde acht documenten toe, waaronder DeliveryNote, InvoiceStatusRequest en InvoiceStatusResponse.

Voor facturen in Nederland en over Peppol telt alleen 2.1. Peppol BIS Billing 3.0 waarschuwt bij elke UBLVersionID die niet 2.1 is (regel UBL-CR-002). Een factuurmodule die "UBL 2.3" of "UBL 2.5" als pluspunt noemt, maakt de factuur daarmee niet beter geschikt voor Peppol.

Hoe een UBL-document is opgebouwd

Een UBL-factuur is een XML-bestand met het element Invoice als wortel. Daaronder staan twee soorten elementen, elk met een eigen namespace:

• cbc: (common basic components): één waarde, zoals cbc:ID, cbc:IssueDate of cbc:PayableAmount.
• cac: (common aggregate components): een groep elementen, zoals cac:AccountingCustomerParty met naam, adres en identificatie van de koper.

UBL zelf is ruim. Peppol BIS maakt er een smal profiel van:

De zes elementen die UBL 2.1 zelf verplicht stelt, zijn ID, IssueDate, AccountingSupplierParty, AccountingCustomerParty, LegalMonetaryTotal en minstens één InvoiceLine. Een bestand met alleen die zes is geldige UBL en wordt door elk Peppol-access point afgekeurd. Daarom zegt "we leveren UBL" weinig zonder de naam van het profiel erbij, en dat profiel staat in CustomizationID.

Elk bedrag heeft een verplicht attribuut currencyID; dat eist het UBL-schema zelf. Peppol voegt eraan toe dat alle bedragen dezelfde valuta hebben als de factuur (regel PEPPOL-EN16931-R051). Bedragen en datums volgen XML: 302.28 met een punt, 2026-10-02 als datum.

Rekenvoorbeeld: de totalen van een vooraf betaalde webshoporder

Een zakelijke klant bestelt in een webshop 12 × 17,08 en 3 × 10,12, gebruikt een kortingscode van 10,00, betaalt 14,50 verzendkosten en rekent bij de checkout af met iDEAL. De factuur volgt later uit de boekhouding. In UBL komen korting en verzendkosten op documentniveau in cac:AllowanceCharge, met ChargeIndicator false voor een korting en true voor een toeslag:

<cac:AllowanceCharge>
  <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
  <cbc:AllowanceChargeReason>Kortingscode</cbc:AllowanceChargeReason>
  <cbc:Amount currencyID="EUR">10.00</cbc:Amount>
  <cac:TaxCategory>
    <cbc:ID>S</cbc:ID><cbc:Percent>21</cbc:Percent>
    <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme>
  </cac:TaxCategory>
</cac:AllowanceCharge>
<cac:LegalMonetaryTotal>
  <cbc:LineExtensionAmount currencyID="EUR">235.32</cbc:LineExtensionAmount>
  <cbc:TaxExclusiveAmount currencyID="EUR">239.82</cbc:TaxExclusiveAmount>
  <cbc:TaxInclusiveAmount currencyID="EUR">290.18</cbc:TaxInclusiveAmount>
  <cbc:AllowanceTotalAmount currencyID="EUR">10.00</cbc:AllowanceTotalAmount>
  <cbc:ChargeTotalAmount currencyID="EUR">14.50</cbc:ChargeTotalAmount>
  <cbc:PrepaidAmount currencyID="EUR">290.18</cbc:PrepaidAmount>
  <cbc:PayableAmount currencyID="EUR">0.00</cbc:PayableAmount>
</cac:LegalMonetaryTotal>

De som, stap voor stap, met de regel die hem controleert:

• Regels: 204,96 + 30,36 = 235,32 (BR-CO-10).
• Exclusief btw: 235,32 - 10,00 + 14,50 = 239,82 (BR-CO-13).
• Btw: 239,82 × 0,21 = 50,3622, afgerond 50,36.
• Inclusief btw: 239,82 + 50,36 = 290,18 (BR-CO-15).
• Te betalen: 290,18 - 290,18 vooraf betaald = 0,00 (BR-CO-16).

Twee dingen gaan hier in de praktijk mis. Een boekhoudpakket dat de webshopbetaling niet kent, zet PayableAmount op 290.18 en de klant krijgt een factuur voor een bedrag dat al betaald is, met een aanmaning erachteraan. En een korting zonder reden wordt afgekeurd: elke korting op documentniveau heeft een reden of redencode nodig (BR-33) en een btw-categorie (BR-32). Hoe btw per regel of per totaal wordt afgerond, staat in bedragen en btw mappen.

UBL of EDIFACT

UBL en EDIFACT doen hetzelfde werk in een andere vorm. Een factuur kan als UBL-XML of als EANCOM-INVOIC worden verstuurd:

De velden zijn grotendeels dezelfde: ordernummer, GLN of KVK-nummer, GTIN, aantallen, bedragen. Een koppeling die een EANCOM-factuur kan opbouwen, heeft de gegevens voor een UBL-factuur dus al. Het verschil zit in de regels: welke velden verplicht zijn en hoe bedragen moeten optellen. Hoe EDIFACT-berichten zijn opgebouwd, staat in EDIFACT-berichten.

Waar een UBL-bestand op wordt afgekeurd

De eerste twee komen bij zelfgebouwde exports het vaakst voor: een sjabloon dat bedragen met de Nederlandse komma schrijft, of de valuta alleen bovenaan vermeldt. Een waarschuwing houdt de factuur niet tegen, een afkeuring wel.

Wat betekent dit voor je koppeling?

UBL is de vorm; wat erin moet staan, bepaalt het profiel. Voor een Nederlandse afnemer of over Peppol is dat UBL 2.1 met de regels van SI-UBL 2.0 of Peppol BIS, en die regels raken gegevens die uit je webshop en je ERP moeten komen: de betaling bij de checkout, de korting met een reden, de verzendkosten als toeslag en het ordernummer van de klant.

Wij bouwen de koppeling die die gegevens bij elkaar brengt, zodat je boekhoudpakket of ERP een factuur maakt die bij de eerste validatie door komt, en we bewaken hem daarna. Een afgekeurde factuur staat met het nummer van de regel in het dashboard. Meer op Peppol koppeling. Vertel vanuit welk pakket je factureert, dan hoor je wat er voor UBL en Peppol nog ontbreekt.