KRA eTIMS, Tax Compliance & Custom ERP Integration: Automating Real-Time Fiscal Invoice Signing in Python

Why Real-Time Tax Compliance Breaks Naive ERPs and POS Systems

Across East Africa and global markets adopting mandatory real-time electronic fiscal invoicing (such as the Kenya Revenue Authority's eTIMS OSCU and VSCU architectures), businesses face a strict operational mandate: every commercial invoice, receipt, and credit note must be cryptographically signed, assigned a fiscal control unit invoice number, and stamped with a verifiable QR code—or the expense is disallowed for corporate tax deduction.

For companies running custom ERPs, wholesale distribution portals, SaaS billing engines, or multi-branch point-of-sale (POS) systems, two expensive problems emerge: either accounting staff waste hours manually re-typing invoices into a web tax portal, or a developer wires a synchronous HTTP call directly into the checkout button—causing the entire checkout counter or web app to freeze whenever the upstream tax authority server experiences latency or maintenance windows. At devManue API Engineering, we architect fault-tolerant fiscal middleware that guarantees 100% tax compliance with zero checkout downtime.

1. Comparing eTIMS Integration Architectures: OSCU vs. VSCU vs. Middleware

Selecting the right integration topology depends on your transaction volume, offline branch requirements, and existing software stack:

2. The 4 Production Edge Cases Every Tax Integration Must Handle

1. Item & HS/UNSPSC Classification Sync: Before an invoice can be signed, every SKU or service item in your database must be mapped to a registered tax classification code (Tax Type A, B, C, D, or E) and synchronized with stock movement ledgers.
2. Idempotent Retry Without Double-Taxation: If your ERP sends Invoice #8042 and the network drops before receiving the response, a naive retry without strict invoice sequence locking will register the same sale twice with the tax authority—doubling your VAT liability!
3. Credit Notes & Partial Refunds: Tax authorities forbid deleting or editing a signed invoice. Canceling an order or issuing a partial discount requires an automated workflow that references the original orgInvcNo and transmits a linked fiscal Credit Note.
4. Buyer PIN Pre-Validation: For B2B invoices where corporate buyers require input VAT deductibility, our middleware validates the buyer's KRA PIN format and status before generating the PDF.

# Fault-Tolerant Fiscal Invoice Signing Task with Idempotency & QR Stamp Generation
import httpx
from django.db import transaction
from celery import shared_task
from .models import CommercialInvoice, FiscalSubmissionLog

@shared_task(bind=True, max_retries=8, default_retry_delay=30)
def sign_invoice_with_etims_oscu(self, invoice_id: int) -> dict:
    """Signs an approved invoice asynchronously so customer checkout never blocks on government API lag."""
    with transaction.atomic():
        invoice = CommercialInvoice.objects.select_for_update().get(id=invoice_id)
        if invoice.fiscal_receipt_signature:
            return {"status": "ALREADY_SIGNED", "cu_inv_no": invoice.cu_invoice_number}

        payload = invoice.to_oscu_trns_sales_payload()

    try:
        with httpx.Client(timeout=12.0) as client:
            resp = client.post(f"{invoice.tenant.oscu_base_url}/trnsSales/saveSales", json=payload)
            resp.raise_for_status()
            data = resp.json()
    except httpx.HTTPError as exc:
        FiscalSubmissionLog.objects.create(invoice=invoice, status="RETRYING", error_detail=str(exc))
        raise self.retry(exc=exc, countdown=min(600, 30 * (2 ** self.request.retries)))

    if data.get("resultCd") == "000":
        res_data = data["data"]
        with transaction.atomic():
            invoice.cu_invoice_number = res_data["invcNo"]
            invoice.fiscal_receipt_signature = res_data["rcptSign"]
            invoice.fiscal_internal_data = res_data["intrlData"]
            invoice.qr_verification_url = invoice.build_kra_qr_url(res_data["rcptSign"])
            invoice.save(update_fields=[
                "cu_invoice_number", "fiscal_receipt_signature", "fiscal_internal_data", "qr_verification_url"
            ])
        invoice.render_and_email_stamped_pdf()
        return {"status": "SIGNED", "cu_inv_no": invoice.cu_invoice_number}

    FiscalSubmissionLog.objects.create(invoice=invoice, status="REJECTED", error_detail=data.get("resultMsg", ""))
    raise ValueError(f"Fiscal signing rejected ({data.get('resultCd')}): {data.get('resultMsg')}")

Need to connect your ERP, POS, or SaaS billing system to eTIMS without disrupting sales? Check your worker throughput requirements with our Celery & Queue Capacity Planner or book an eTIMS & ERP Integration Consultation.

3. Frequently Asked Questions (FAQ)