In short: UBL 2.1 (Universal Business Language) is an international standard for writing an invoice as a structured XML file, and it is the format JoFotara uses to receive every e-invoice in Jordan.
The full guide: JoFotara-connected POS
Use the tool: JoFotara readiness check
UBL stands for Universal Business Language, an international standard for how business documents such as invoices and credit notes are written in one structured file; 2.1 is the version. XML is the file format itself: text organised with tags, where every piece of the invoice has a fixed name and place, so a computer reads it without guessing.
JoFotara receives every e-invoice as an XML file built on UBL 2.1. That is why both names appear in the department's technical guides and in accountants' questions. A shop owner rarely sees the file, though: the POS or the portal builds it from the sale, sends it and receives the reply.
What the invoice XML carries
| Part | What is in it |
|---|---|
| Header | The invoice number, its unique UUID, the issue date and the currency |
| Invoice type | Code 388 for an invoice and 381 for a credit note, with a code showing cash or receivable, income or sales tax |
| Seller | Tax number, the name registered with the department, and the income source sequence |
| Buyer | Their name, their tax number when required, or a cash customer for an ordinary sale |
| Lines | Each item with its quantity, price, discount and tax rate |
| Totals | The tax, the totals before and after tax, and the amount due |
Once it receives the file, the system returns its own invoice number and the QR code that prints on the receipt.
Who writes the UBL file?
If you issue an invoice by hand on the JoFotara portal, the portal builds the file from the form you fill in. If you use POS or accounting software connected to the system, the software builds the file with each sale and sends it by itself. Either way, you never write XML by hand.
In Ghalleh each invoice's file is built from the sale itself, the items, quantities, prices and tax, together with the business details you entered once when connecting. It is sent to the system and comes back with a QR code that prints on the receipt.
Do I need the JoFotara API?
No, not if your POS is already connected to the system. The API is for the people who build the software, not for the shop owner. What you need is the Client ID and Secret Key from device linking on the portal, entered in your software once.
Why the system sometimes refuses an invoice
- A tax number or registered name that does not match your tax file, even by one letter.
- A wrong income source sequence, or none on your file.
- An invoice type that does not fit your registration, such as a sales tax invoice from a shop not registered for it.
- Line amounts and totals that do not add up, since the system recalculates the tax and the total.
Everything about JoFotara on one page: the JoFotara e-invoicing guide.
A shop example
A supermarket in Shmeisani sells five items for JOD 18.450 including tax. The POS builds an XML file with five lines, the invoice type, the shop's tax number and its income source sequence, and sends it to the system. The reply comes back with the invoice number and a QR code, which prints at the bottom of the receipt; the cashier never sees the file itself.
Common questions
Do I have to write the XML file myself?
No. The portal builds it when you issue an invoice by hand, and a connected POS builds it with every sale. You deal with the invoice, not the file.
Do I need the API to connect my shop to JoFotara?
No, if your POS is connected to the system. The API is for the people who build the software. You only need the Client ID and Secret Key from device linking on the portal.
What is the difference between an XML file and a PDF invoice?
The XML file is structured data the system reads and checks, and it is what goes to JoFotara. A PDF is a picture of the invoice for people to read, and on its own it is not an e-invoice.