EFRIS Integration for Ugandan Businesses: A Developer's Guide

If you sell to VAT-registered customers in Uganda, your invoices increasingly need to carry a URA fiscal number and QR code. That is EFRIS — the Electronic Fiscal Receipting and Invoicing Solution — and bolting it onto an existing POS, ERP, or billing system is one of the most common integration requests we get at Desishub.

This guide explains how EFRIS integration actually works, what trips teams up, and how to add it to your system without breaking the way you already invoice.

Table of Contents

1. What EFRIS actually is
2. The architecture behind an EFRIS integration
3. The invoice lifecycle
4. Credit notes, Z-reports and stock
5. Where integrations go wrong
6. How we approach an EFRIS build
7. FAQs

What EFRIS actually is

EFRIS is URA's system for fiscalising every tax invoice in real time. When you issue an invoice, a copy of it is sent to URA, which stamps it with a fiscal document number, a verification code, and a QR code that anyone can scan to confirm the invoice is genuine. For VAT-registered taxpayers this is not optional — an invoice without a valid fiscal stamp is not a valid tax invoice.

The practical consequence for software: your system can no longer be the sole source of truth for an invoice. URA has to see it and sign it before you hand it to the customer.

The architecture behind an EFRIS integration

Most integrations do not talk to URA's cloud directly. Instead URA provides an offline enabler — a local component you install that exposes an HTTP endpoint (commonly on a port such as 9880). Your application posts a signed JSON payload to that local base URL, the enabler handles encryption, keys and transmission to URA, and returns the fiscal result.

That means three moving parts:

• Your system — builds the invoice payload from its own data.
• The offline enabler — the local bridge that signs and transmits.
• URA EFRIS — issues the fiscal number, verification code and QR.

A clean integration treats the enabler as an external service behind an adapter, so your core invoicing logic never hard-codes URA's payload shape.

The invoice lifecycle

A typical fiscalised sale runs like this:

1. The user finalises a sale in your POS/ERP.
2. Your backend assembles the EFRIS payload — buyer details (or "walk-in"), line items, tax categories, and totals.
3. You post it to the enabler; URA returns the fiscal document number, verification code and QR data.
4. You write those values back onto your own invoice record and render them (with the QR) on the printed or PDF invoice.
5. Only now is the document a valid tax invoice.

The golden rule: store what URA returns. Those three fields are your proof of fiscalisation and you will need them for reconciliation, reprints and audits.

Credit notes, Z-reports and stock

A real EFRIS integration is more than the happy-path invoice:

• Credit notes must be requested, approved and sometimes cancelled through EFRIS — you cannot simply reverse an invoice in your own database.
• Z daily reports summarise the day's fiscal activity and are pulled from EFRIS.
• Goods/stock registration and the system dictionary (tax categories, units, commodity codes) have to be kept in sync, or line items are rejected.
• Exchange rates for foreign-currency invoices are looked up through EFRIS rather than your own table.

Where integrations go wrong

The failures we see most often:

• Trusting a 200 response. The enabler can accept a request and URA still reject the document. Always read the returned status and persist the fiscal fields before telling the user "done".
• Commodity-code mismatches. Line items whose tax category or unit does not match URA's dictionary silently fail. Sync the dictionary and validate before sending.
• No offline story. Connectivity in Uganda is not guaranteed. Queue fiscalisation so a sale can complete locally and fiscalise when the enabler is reachable, rather than blocking the till.
• Floating-point money. Compute tax server-side in integer units, never as JavaScript floats, so your totals match URA's to the shilling.

How we approach an EFRIS build

At Desishub we add EFRIS to systems the way we add any payment rail — behind a verified adapter. The invoice engine computes money server-side in integer units, an adapter translates to the enabler's payload, and a background job retries fiscalisation so a network blip never costs a sale. The fiscal number, verification code and QR are stored on the invoice and reprinted from there. If you already run a POS or ERP, we integrate EFRIS into it rather than asking you to switch systems.

We build exactly this kind of local-rail integration — URA, MTN MoMo, Airtel Money and regional SMS — into custom software and billing products for Ugandan businesses.

FAQs

Is EFRIS mandatory? For VAT-registered taxpayers, yes — their tax invoices must be fiscalised. Talk to a tax advisor about your specific obligation.

Can EFRIS be added to my existing system? Almost always. EFRIS is an integration, not a new product — we wire it into your current POS, ERP or billing app behind an adapter.

What happens when the internet is down? A well-built integration lets the sale complete and queues fiscalisation to run when connectivity returns, so the till never waits.

How long does an EFRIS integration take? A focused integration into an existing system is typically a few weeks, most of it spent on dictionary mapping, credit notes and the offline queue rather than the happy-path invoice.

Need EFRIS wired into your POS or billing system? Request a quote and we'll scope it against your current stack.