UBL 2.1 em português simples: o padrão XML por trás da faturação eletrónica moderna

UBL — Universal Business Language — é o standard da OASIS que sustenta Peppol BIS, EN 16931, ZATCA Fase 2, o perfil PINT dos EAU, o schema IRP/e-invoice da Índia (com extensões) e vários regimes da LATAM. Se a tua estratégia de faturação eletrónica não fizer as pazes com UBL 2.1, vais estar a reimplementar o mesmo XML uma e outra vez.

A forma de uma fatura UBL

Uma fatura UBL é um documento XML com três namespaces principais: cbc (Common Basic Components — tipos primitivos como ID e Amount), cac (Common Aggregate Components — tipos complexos como Party e TaxTotal), e o namespace do próprio documento. Cada documento UBL segue o mesmo padrão:

<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</cbc:CustomizationID>
  <cbc:ID>INV-2026-0001</cbc:ID>
  <cbc:IssueDate>2026-01-15</cbc:IssueDate>
  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
  <cac:AccountingSupplierParty>...</cac:AccountingSupplierParty>
  <cac:AccountingCustomerParty>...</cac:AccountingCustomerParty>
  <cac:TaxTotal>...</cac:TaxTotal>
  <cac:LegalMonetaryTotal>...</cac:LegalMonetaryTotal>
  <cac:InvoiceLine>...</cac:InvoiceLine>
</Invoice>

Cinco conceitos quase sempre mal entendidos

1. TaxTotal vs. LegalMonetaryTotal. O primeiro decompõe o imposto por taxa. O segundo é o montante consolidado a pagar. Não os confundas.
2. AllowanceCharge pode ser um desconto ou um acréscimo — controlado pelo ChargeIndicator (false = desconto, true = acréscimo). Indicador errado → total errado.
3. Os Endpoint IDs precisam de um atributo scheme (schemeID="0088" etc.). Sem isso, os validadores dão erros crípticos sobre identificadores em falta.
4. As quantidades usam um código de unidade do UN/CEFACT (EA = each, KGM = kilograma, HUR = hora). "piece" não é um valor válido.
5. Os códigos TaxCategory são UNCL5305: S = taxa standard, Z = taxa zero, E = isento, AE = reverse charge. Não inventes códigos.

A EUStrategy da Invocie emite UBL 2.1 conforme com BIS Billing 3.0 — o mesmo XML serve para APs de Peppol, o perfil UAE PINT, e qualquer sistema que consuma EN 16931.