UBL 2.1 e-invoicing in Morocco: your invoices as structured XML

What is the UBL 2.1 format?

UBL, short for Universal Business Language, is an open XML standard for business documents, maintained by OASIS, an international standards consortium. It describes the order, the delivery note, the invoice and the credit note as elements whose meaning is fixed in advance: one element carries the invoice number, another the VAT rate, another the amount payable.

Version 2.1 was also adopted as the ISO/IEC 19845 standard and underpins several e-invoicing schemes, including the Peppol network, which started in Europe. A UBL file is not written for the human eye: it is written so that software can read it without mistakes.

PDF invoice or UBL file: what is the difference?

A PDF is a picture of a document, ideal for a person: logo, layout, amount in words, company stamp. For software it is just characters placed on a page: to find the total or the seller's ICE number, a program has to extract the text and guess what is what, with a risk of error for every different invoice template.

A UBL file holds the same information as data: the receiving system knows exactly where to find the number, the date, the taxable base at 20% or the amount payable. The two formats are not rivals. SOGESTIO produces the PDF for your customer and the UBL file for software, from the same validated invoice.

What does a UBL invoice exported by SOGESTIO contain?

The file reproduces the validated invoice as numbered by the server. Credit notes are exported too, in the document form the standard defines for them, with the reference of the invoice they correct.

The file only contains what your records contain: an ICE number missing from the customer record will be missing from the file. SOGESTIO does not make up any data.

• Seller and buyer with company name, address, ICE, IF and RC
• Number assigned by the server, issue date and due date
• Lines: description, quantity, unit price excl. VAT, VAT rate
• Total VAT, with a subtotal per rate
• Totals excl. and incl. VAT, and amount payable
• Credit notes linked to the original invoice

Worked example: a 25,000 DH invoice as it appears in the file

An IT services company in Rabat invoices a Casablanca customer for annual maintenance at 18,000 DH excl. VAT and the installation of 7 workstations at 1,000 DH excl. VAT each, a total of 25,000 DH excl. VAT. At the standard 20% rate (to be checked for the transaction, as rates change with each finance law), VAT comes to 3,600 DH + 1,400 DH = 5,000 DH, for a total of 30,000 DH incl. VAT.

In the UBL file, these amounts are not formatted text but values placed in specific elements. The VAT block (TaxTotal) holds a 20% subtotal with a taxable base of 25000.00 and tax of 5000.00, in dirhams (code MAD); the totals block shows 25000.00 excluding tax, 30000.00 including tax and 30000.00 payable.

If one workstation was invoiced by mistake, you do not edit the invoice: you issue a credit note for 1,000 DH excl. VAT, that is 200 DH of VAT and 1,200 DH incl. VAT, which is exported to UBL in turn with the reference of the original invoice.

Server numbering, credit notes and SHA-256 fingerprints: why they matter

A structured format is only as reliable as the data it carries. These SOGESTIO rules form the foundation of any e-invoicing system, whatever scheme Morocco finally adopts.

A SHA-256 fingerprint works like a digital seal: it is calculated from the exact content of the document, and changing a single character is enough for it to stop matching. It lets you check that the archived original has not changed since it was validated.

• Sequential numbering assigned by the server, per document type and per year: no duplicates and no gaps, even with several users
• Corrections by credit note, never by deletion: the validated invoice stays as issued
• Original of every validated invoice archived with its SHA-256 fingerprint
• Totals computed by the server, VAT line by line and summed per rate

What is UBL export useful for today?

The DGI has announced electronic invoicing, but its official technical specification has not been published and no software approval scheme exists yet. SOGESTIO exports validated invoices and credit notes in the structured UBL 2.1 format (with ICE, IF and RC), which prepares the move to the e-invoicing system announced by the DGI. A match with the official format can only be checked once it is published.

Meanwhile, the structured file already has practical uses, especially with organised customers who would rather receive data than a PDF to re-type.

• Send structured data to key accounts or foreign principals who ask for it
• Archive your invoices in an open format that can be read without SOGESTIO
• Notify another application each time an invoice is validated, through a signed webhook
• Exchange invoicing data through the documented REST API

What to clean up in your data now

Since the file mirrors your records, preparation starts with your data. It is better to fix an incomplete customer record today than to discover the problem the day a system rejects the invoice.

• ICE number of every business customer: 15 digits, no spaces or letters
• Customer's exact legal name, address and city, without in-house abbreviations
• Your own company record: ICE, IF, RC, professional tax number and address
• An explicit VAT rate on every item, with the exempt rate (0%) kept for transactions that qualify, to be confirmed with your accountant
• No catch-all customer such as “Miscellaneous” for sales to businesses