Filing Is Not Fiscalisation, and Your Till Knows the Difference

A shopkeeper in Kampala, one in Dar es Salaam, one in Kigali and one in Nairobi are all told by their software vendor that the product "handles e-invoicing". All four are being told something true. No two of them are being told the same thing, and at least one of them is going to find that out on a Tuesday afternoon when the internet goes down and a queue forms.

The word doing the damage is e-invoicing, which has been stretched to cover two mechanisms that have almost nothing in common. One of them sends a document to a revenue authority after the document exists. The other requires the authority, or a device the authority has approved, to authorise the document before it can be issued at all. Those are not two grades of the same feature. They are opposite architectures, and a system built for the first cannot be persuaded into the second by configuration.

This matters more at a till than anywhere else in a business, because a till is the one place where a document and a human being meet in real time. An invoice can be raised on Tuesday and transmitted on Wednesday and nobody is standing there. A customer at a counter is standing there.

The question that separates the two

There is a single diagnostic, and it is short enough to ask in a demo.

Cut the connection to the revenue authority. Now sell something. Did the sale complete?

If the sale completed, you are looking at a filing pipeline. The transaction is the business's own act; the authority is told about it afterwards. Reliability is a queue problem, and queues are a solved problem — retry, back off, alert somebody when the backlog grows.

If the sale refused to complete, you are looking at fiscalisation in the strict sense. The authorisation is not a notification about the transaction, it is a component of it, and the software is not permitted to produce a valid document without it. A vendor who has built this will tell you about it immediately, because it is the hard part and it is expensive.

Our own codebase already draws this line, in a place most people will never read. The text we publish for South Sudan says that the authority's platform there "is registration, filing and payment, not a requirement that each invoice be validated before it can be issued, so this is a filing pipeline rather than a fiscalisation one and the two are often confused." That distinction was written for one market. It is the whole subject of this post.

Four neighbours, four interfaces

The East African Community harmonises a great deal. It does not harmonise this. Each of these is a separate authority running a separate scheme against a separate technical interface, and each one is a separate build for any vendor serving the region.

What we can state without qualification is the second column of that table, because it describes our own code rather than anybody's statute. One of those four is implemented. The other three are not, and no amount of settings will make them appear.

What we actually built, described precisely

A tenant connects by supplying their KRA PIN, a branch identifier and a device serial number, then initialising the device to obtain a communication key. That key is stored encrypted and every subsequent call carries it. There is a sandbox toggle, so the connection can be proved end to end before anything real goes through it. This is a device-registration model, and it is a reasonable one.

Then a sale happens, and here is the design decision that this whole post is about. Filing is dispatched after the database transaction commits, onto a queue. The job's own comment says it plainly: recording a sale is never blocked or delayed, the sale completes immediately, and filing happens in the background. Three attempts, backing off thirty seconds, then two minutes, then five.

For Kenya that is the right call, and it is the call we would make again. It means a network problem at the revenue authority is not a network problem at your counter. It means the queue absorbs an outage instead of your customers absorbing it. It is the correct architecture for a filing regime.

It also has a consequence that we have never written down anywhere until now.

The receipt in the customer's hand

The receipt template renders the fiscal block — the authority's receipt number, the receipt signature, the QR code drawn in vector from the stored payload — inside a condition. The condition is that the sale's filing status equals filed. Everything in that block is real, it is production code, and it works.

But at the moment the receipt prints, the filing has not happened yet. It was queued a fraction of a second ago and it is going to complete somewhere between a moment and several minutes from now, depending on the queue and the authority. The status at print time is not filed. So the condition is false, and the block is absent.

The data is not lost. It is on the sale record, it is on the reprint, it is on the screen, and it is in every report. The system is doing what it was designed to do. But the printed artefact that a person carried out of the shop is not the artefact that carries the fiscal reference, and if you are in a jurisdiction where the customer's copy is required to bear that reference at the moment of handover, this design does not satisfy your regime and cannot be configured into satisfying it.

A queue is the right answer to an outage and the wrong answer to a legal precondition. Which one you have is decided by your statute, not by your vendor.

And the one we found while writing this

Auditing our own code for this post turned up something we did not know, which is the usual reason these posts are worth writing.

A filing that fails is marked failed, with the authority's error message stored against the sale, and the job raises so the queue can retry it. After three attempts it stops. For a customer invoice that is fine, because the invoice screen carries a button that reads "Retry eTIMS filing" and an operator can push it.

There was no such button for a point-of-sale sale. No route, no control in the interface, and no scheduled task that swept up failures and tried again. A POS sale that failed three times was stranded in the failed state permanently, and the only thing that would have surfaced it was somebody querying the database. The mechanism that files POS sales was modelled on the invoice one and the recovery half was not carried across.

What a buyer in the region should actually do

The useful move is not to ask whether a system supports your country. Every vendor says yes to that, and most of them are describing a filing pipeline while you are picturing a fiscal device. Ask the questions that have factual answers instead.

The last of those is the one that catches regional groups. A business with branches in Nairobi and Kampala is not running one compliance obligation with a country field on it. It is running two schemes, against two authorities, with two technical interfaces, and any vendor who describes that as a setting has not built either of them.