Skip to main content

Set up KRA eTIMS

Open Settings → KRA eTIMS (/admin/settings?tab=etims). This integration uses your business's own KRA registration and branch device. NuSaaS does not offer managed eTIMS, supply taxpayer credentials or confer KRA approval. “eTIMS-ready” describes an integration capability, not certification of your installation.

:::note Image availability The queued product-setup, guided OSCU and fiscal-receipt workflows described here require a public image release newer than 1.0.11. The self-hosted installer is still pinned to 1.0.11. Use matching release notes and published images before expecting these newer controls; changing environment files does not add them. :::

1. Prepare your business​

Enable the KRA eTIMS module and its required ERP modules in your workspace. Use an account with settings permissions; document submission also requires the appropriate eTIMS permission. Have the following information from your own KRA environment:

  • Registered taxpayer name and KRA PIN.
  • Branch ID and branch name.
  • Registered OSCU device serial and any initialization details requested by the application.
  • The ERP company and warehouse represented by that branch.

Start with Sandbox. Sandbox and production registrations, device credentials and fiscal evidence are separate. VSCU records may be retained, but VSCU transmission is not currently enabled. Do not substitute a VSCU serial or token for an OSCU device.

2. Connect in sandbox​

  1. Use the guided setup to enter your taxpayer identity, choose Sandbox, and link the branch to its ERP company/warehouse.
  2. Enter the registered device serial in Branches & devices, then initialize that device. Wait for a confirmed successful response; do not repeatedly initialize a device whose outcome is uncertain.
  3. In the connection/setup controls, sync KRA reference codes and item categories. Review the saved connection result and any reported missing information.
  4. Keep automatic document queuing off until product setup is complete.

KRA service addresses are controlled by the application. There is no need to enter a custom gateway, install VSCU for OSCU, or put communication keys in browser configuration. Saved device credentials stay server-side; preserve APP_KEY and an encrypted backup so they remain recoverable.

3. Map and register products​

In Products, search for the relevant products and choose Map codes. Select the correct KRA item category, product type, packaging unit, quantity unit, tax category and country of origin. The item code is generated from the selected codes and product identity. Use the product's actual origin and tax treatment; “electronics” alone does not determine these values.

Mapping saves the codes locally. Register sends the mapped item to KRA using the selected initialized branch device and environment. A product is ready only when its mapping is complete and its current registration is accepted.

For bulk setup:

  1. Select products with the same classifications. The header checkbox selects the current page; use the explicit all-matching selection control for results across pages. Check the displayed selected count before applying changes.
  2. Apply the shared codes. Product setup progress records background work; closing or collapsing it does not cancel the job.
  3. Review Registration results and per-product errors. Unchanged mappings are skipped; replacing different mappings requires explicit consent.
  4. Select mapped products and register them against the correct device. Accepted unchanged registrations are skipped. Review uncertain outcomes before any further action instead of submitting them again.

A product/price change can make its registration stale. Update its KRA registration and wait for acceptance before submitting a new fiscal document that uses it. Changing an ERP product does not rewrite accepted fiscal documents.

4. Capture and submit ERP documents​

Capture finalized ERP documents records eligible finalized ERP source transactions as local fiscal evidence. It does not mean KRA has accepted them, and it is not a blanket import of historical transactions. Automatically queue new finalized ERP documents additionally schedules eligible new evidence for submission. Device routing, current item registrations and transmission checks still apply. Save the configuration after changing these options.

The API, scheduler and queue worker must be running. Fiscal and product-setup jobs use the database connection's compliance queue; a Redis-only worker does not consume them. See self-hosted integration checks.

In Documents, open a record to inspect its source, attempts and KRA outcome:

  • Queued / Pending: not yet accepted; check worker activity and prerequisites.
  • Needs correction: fix the reported source, mapping, tax or device issue. Prepare corrected source prepares a new validated revision; “saved” alone is not KRA acceptance. Follow the available queue/submission action and refresh status.
  • Accepted: retain the KRA fiscal identity, signature and receipt evidence.
  • Uncertain / Manual review: check the taxpayer portal and record an evidence reference. Do not blindly replay, renumber or delete the transaction.

5. Verify receipts, refunds and stock​

For an authorized sandbox sale, wait for Accepted before expecting a fiscal receipt and KRA QR code. A payment confirmation or “Fiscal receipt not yet available” message is not a fiscal receipt. If acceptance is delayed, inspect Documents rather than repeatedly printing or recreating the sale. Review both 80 mm and 58 mm print layouts with your actual printer.

Process refunds through the normal ERP return/credit-note workflow. The fiscal credit must reference the accepted original sale and an appropriate reason; changing a sale or issuing a cash refund alone does not prove KRA accepted a credit. Check both fiscal status and accounting/inventory results.

The integration captures supported finalized purchases and stock movements, including follow-up stock balances where source data is available. Map and register items first, route the branch/warehouse correctly, and inspect stock/purchase records in Documents. Do not assume every stock operation has been transmitted merely because the connector is enabled. Confirm the scenarios relevant to your business with KRA's current guidance before production.

Production activation​

Finish the applicable KRA sandbox/approval process for your own business and verify your installed image supports the required workflows. A declaration in Business is informational; selecting “certified” does not grant approval. The installation operator must separately authorize the exact workspace through ETIMS_PRODUCTION_ENABLED and ETIMS_APPROVED_PRODUCTION_TENANTS; both default to disabled. See operator checks. Never copy sandbox device keys into production or bypass readiness checks to remove a receipt warning.

Official process reference: KRA system-to-system integration.