eTIMS API for developers
Already have an ERP, a billing system or an app? Use NanoPOS as your eTIMS connection: send an invoice, get it back signed by KRA, with webhooks when anything changes.
A simple REST API
Invoices, credit notes and stock reports, with idempotency keys so nothing is sent twice.
Test and live keys
Build against the simulated KRA with test keys, then switch to live.
Webhooks
Signed notifications when an invoice is signed or refused, retried for 24 hours.
In the back office
Apps, keys, connections and the delivery log under Configuration, Developers.
Your first signed invoice
Send a plain sale. NanoPOS works out the tax bands, totals, item codes and KRA's format, numbers it and signs it. Wait up to 10 seconds for the answer, or get it by webhook.
curl -X POST "$NANOPOS_API/v1/invoices?wait=3" \
-H "Authorization: Bearer $NANOPOS_KEY" \
-H "Idempotency-Key: sale-7F3A-000123" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "con_…",
"reference": "7F3A-000123",
"payment": "mpesa",
"lines": [
{ "sku": "MF-2KG", "name": "Maize flour 2 kg",
"qty": 2, "unitPrice": 185, "tax": "VAT16" },
{ "sku": "BAN-KG", "name": "Bananas", "qty": 1.245,
"unit": "KG", "unitPrice": 160, "tax": "EXEMPT" }
]
}'What the API covers
Version 1, the same for OSCU and VSCU.
- Connections to KRA, with the taxpayer's consent
- Items and their KRA classification
- Invoices, receipts as PDF and credit notes
- Customer PIN lookup
- Stock movements and stock reports
- Incoming supplier invoices to confirm
- Sandbox switches: normal, slow, refusing or down
Questions
Is there a sandbox?
Yes. Test keys talk to a simulated KRA that can be switched to slow, refusing or down.
Which KRA connections are supported?
OSCU and VSCU, through the same endpoints. You choose the mode when you create a connection.
How are retries handled?
Every write takes an Idempotency-Key, so a retry never signs an invoice twice. NanoPOS queues and retries the send to KRA for you.
Building on eTIMS?
Tell us what you are integrating and we will set you up with test keys and a walkthrough.