Skip to content

eTIMS (KRA, Kenya)

A module for companies that sell in Kenya. The Kenya Revenue Authority (KRA) requires every invoice and every till receipt to be registered in its eTIMS system and to carry its receipt: the CU invoice number, the signature and the QR code the customer uses to verify the document. Without that receipt a business customer cannot claim the input VAT.

ERPJS sends the document to eTIMS by itself, right after approval, through the eTIMS intermediary service. Nobody has to click anything: approve an invoice, and usually a second later it has a KRA receipt. The till receipt prints it by itself; the invoice form prints it if the eTIMS variables are added to its template.

The route: from approval to a KRA receipt in print

eTIMS account (intermediary URL, key, VAT and unit mappings)
        ↓
eTIMS codes for items and item groups (KRA classification, type, packaging, unit, country)
        ↓
Invoice or till receipt approved → record in «eTIMS Receipts» → sending
        ↓
KRA receipt (CU invoice, signature, QR) → on the till receipt and on the printed invoice
        ↓
eTIMS Exchange Log — what was sent and what came back
  1. eTIMS account — which intermediary service and which key to send with, which KRA tax type each VAT code has, which KRA codes the units have, and which KRA payment type invoices get when nothing else sets it. The KRA payment type of each till payment method is set not here but in payment methods. The "default" account sends the company's invoices; a till can have its own.
  2. eTIMS Item Codes and eTIMS Item Group Codes — what KRA wants to know about an item that the item card does not hold: the classification code, the item type, the packaging and unit codes, the country of origin. A group's code applies to all its items; an item's own code is more specific.
  3. eTIMS Receipts — one record per approved document: whether it was sent, how many attempts there were, the last error and the KRA receipt.
  4. eTIMS Exchange Log — every request to the intermediary and its response, without the key.
  5. eTIMS guide — step-by-step setup and what to do when a document has not been sent.

What is worth understanding

The document is always approved — even when eTIMS is unavailable. Sending happens after approval, not as part of it. If the eTIMS server does not answer, the user sees «eTIMS server is busy — invoice 77 will be validated later», and the system retries by itself, with a growing pause. Meanwhile the printout shows a note instead of the QR code: the invoice form — «eTIMS validation pending — the document will be validated later», the till receipt — «eTIMS validation pending — the receipt will be validated later».

A fiscalised document cannot be unapproved. It is already in KRA, and unapproving it in ERPJS would put the books out of step with the tax authority. The correction is a credit note. The same applies while the document is being sent, and when the eTIMS response is lost (a timeout, a dropped connection): the document may already be in KRA, and unapproving is blocked until the result is resolved.

A credit note follows its invoice. It is sent through the same account as the invoice, with the invoice's CU number, so the credit note must name its original invoice. While the invoice is in the eTIMS queue, the note waits. If the invoice is not in eTIMS (an error, unapproved, approved before eTIMS was connected), the note gets an error. The credit notes together cannot exceed what is left of the invoice in eTIMS.

The customer PIN comes from the card. If the invoice has no number, KRA receives the «Tax Number» from the contact card. A credit note carries the PIN its invoice was sent with.

Errors are in the language of whoever approved the document. Retries run without a person, so the language is remembered at approval.

The module exists only in the Kenya edition of ERPJS. The Ukrainian edition has none of its registers, fields or print variables. The edition is set by the ERPJS server's configuration, not by role rights or company settings. In the Kenya edition the module works only with an open eTIMS account: without a «Company default» account (and without a till account) the eTIMS registers and fields are visible, but documents are approved as before — with no fiscalisation record, no notifications, no QR code and no ban on unapproving.

Where to start in a new database

  1. eTIMS account — the intermediary's URL and key, the «Company default» flag, the mapping of VAT codes to KRA tax types, «Test Connection».
  2. eTIMS Item Group Codes — groups first: that way all the items get codes at once.
  3. eTIMS Item Codes — for items that differ from their group.
  4. The «eTIMS payment type» column in the Payment Methods setting and the till's account — if you sell through the till.
  5. Approve a test invoice and look at its record in eTIMS Receipts.

Common tasks

You need Where to go
connect the company to eTIMS eTIMS Accounts
give items KRA codes eTIMS Item Group Codes · eTIMS Item Codes
find out whether an invoice was sent, and why not eTIMS Receipts
send a document again eTIMS Receipts → «Send again»
the eTIMS response was lost — is the document in KRA or not eTIMS Receipts → «Resolve unknown result»
see what was sent to eTIMS and what came back eTIMS Exchange Log
print the KRA QR code on an invoice eTIMS guide, the section on printing