eTIMS E Invoicing

1. Overview

eTIMS OSCU is KRA's online fiscalisation path for businesses registered on the eTIMS portal. Tracksales acts as your invoicing system of record and submits transactions to KRA using OSCU API endpoints such as item master, customer master, sales, and stock updates.

At a high level, the workflow is:

1. Enable e-Invoicing and choose eTIMS OSCU as the transmission type.
2. Connect each business location (branch) to KRA with a generated device serial.
3. Fetch KRA code lists and configure products with the correct classification and unit codes.
4. Push products and customers to KRA (manually or automatically before sales).
5. Push or auto-submit finalized invoices and credit notes.
6. Optionally sync stock levels on a schedule or on demand.

Each entity (product, customer, invoice, credit note) has an eTIMS push status in Tracksales: not pushed, pushed, marked pushed (manually entered CU details), failed, or voided.

2. Prerequisites

• Kenya organization — Country must be KE/Kenya in your organization profile.
• KRA PIN — Enter your business Tax Identifier (PIN) under Settings → Preferences → Tax.
• eTIMS portal registration — Your business must be onboarded on the KRA eTIMS portal and have OSCU credentials for sandbox or production.
• Locations — Each branch/location that will fiscalise sales needs its own OSCU connection (device serial + branch ID).
• Permissions — Users need Settings access to configure e-Invoicing; item, customer, and invoice edit permissions to push entities.
• Queue worker (for automatic invoice push) — If automatic submission is enabled, a queue worker must be running on the server (php artisan queue:work).

3. Enable e-Invoicing

Go to Settings → Preferences → e-Invoicing (under the Tax section in the sidebar).

1. Turn on Activate e-invoicing.
2. Select eTIMS OSCU as the e-invoicing type. (Choose TIMS only if you use a Tremol G03 device instead.)
3. Optionally enable Automatic submission to queue invoice pushes when invoices are finalized.
4. Click Save Settings.

Tax rates and your business PIN remain on the Tax preferences page. KRA transmission type is controlled entirely from e-Invoicing.

4. Connect a Branch to KRA

Each location must be connected individually on the e-Invoicing page.

1. Find the branch in the Branch connections list.
2. Click Generate serial to create a unique device serial for that branch.
3. Click Connect and complete the modal:
   • Environment — Sandbox (testing) or Production.
   • Branch ID (bhfId) — Usually 00 for head office; use the branch code from KRA if you have multiple branches.
   • Integration token (optional) — From the KRA eTIMS portal if required for your setup.
   • Stock update time (optional) — Preferred time for scheduled stock sync (HH:MM).
4. On success, the branch status changes to connected and KRA returns a communication key (cmcKey) stored securely for API calls.

Available branch actions when connected:

• Fetch code lists — Downloads KRA reference codes (item classification, units, countries, etc.).
• Sync stock — Pushes current inventory quantities for all pushed products at that branch.
• Disconnect — Removes the OSCU connection for that branch (does not delete historical submissions).

5. KRA Code Lists

After connecting a branch, click Fetch code lists. Tracksales stores the returned codes in your organization and uses them on the product edit page as dropdown options for:

• Item classification code
• Packaging unit
• Quantity unit
• Origin country

If code lists have not been fetched, you can still enter codes manually. Re-fetch after KRA publishes updates.

6. Products

Open a product → eTIMS Information section (visible when eTIMS is enabled).

• Fill in classification code, packaging unit, quantity unit, product type (finished product / raw material / service), and origin country.
• Save the product before pushing if you changed any eTIMS fields.
• Click Push to eTIMS to register the item with KRA via /saveItem.
• Status badge shows pushed or failed. Retry after fixing validation errors.

When an invoice or POS sale is pushed, Tracksales automatically pushes any line-item products that are not yet registered with KRA.

7. Customers

On the customer edit form:

• Set eTIMS Branch Code (default 00) if the customer belongs to a specific KRA branch.
• Ensure address, phone, and tax identifier (KRA PIN) are complete—these are sent to KRA.
• Use Push to eTIMS in the eTIMS customer sync panel to register the customer via /saveBhfCustomer.

Customers are also auto-pushed when you create or update a customer (non-blocking) and when a sale is submitted if the customer is not yet registered.

8. Invoices

Invoices are submitted to KRA when:

Trigger	Behaviour
Manual push	Open invoice details → Push to eTIMS
Automatic submission (enabled)	Queued when invoice is finalized (Mark as Finalized)
POS sale completion	Submitted when eTIMS is the active transmission type

Before pushing a sale, Tracksales:

1. Resolves the sale's location and verifies the branch is connected.
2. Pushes the customer if not already registered.
3. Pushes each product on the invoice if not already registered.
4. Submits the transaction via /saveTrnsSalesOsdc.
5. Stores CU metadata (invoice number, serial, QR code, signature) on the sale record.

Draft/open invoices are not pushed until finalized (except manual push on non-open invoices).

9. Enter CU Details Manually

If an invoice was fiscalised outside Tracksales (e.g. on a separate CU device or portal), you can record the Control Unit details without an API push:

1. Open the invoice details panel.
2. Click Enter CU details.
3. Fill in CU invoice number (required), serial, internal data, receipt signature, date/time, PIN, and QR code as available.
4. Save. Status becomes marked pushed.

This is useful for migration, reconciliation, or when a push succeeded on KRA's side but failed to persist locally.

10. Credit Notes

Credit notes linked to a fiscalised invoice can be pushed to KRA as reversals:

• Created from an invoice that was pushed to eTIMS (or marked pushed).
• Auto-pushed on creation when eTIMS is enabled and the source invoice has fiscal metadata.
• Manually pushed from the credit note details panel → Push to eTIMS.

11. Voiding Invoices and Credit Notes

When you void an invoice or credit note that was previously pushed to eTIMS:

• Tracksales submits a reversal transaction to KRA (credit-note style via OSCU).
• The entity's eTIMS status is updated to voided.

Voiding also applies to POS sale cancellations when eTIMS is the active transmission type. Entities that were never pushed do not trigger a KRA reversal.

12. Stock Sync

KRA expects stock master updates for registered items. Tracksales supports:

• Manual sync — Sync stock on a connected branch in e-Invoicing settings.
• Scheduled sync — Hourly command etims:sync-stock runs for branches with a configured stock update time.

Only products already pushed to eTIMS are included. Quantities come from per-location inventory (location_items).

13. Activity Log & Retry

The eTIMS activity log on the e-Invoicing page lists recent API submissions: entity type, action, status, and timestamp.

• Refresh — Reload the latest 100 submissions.
• Retry — Re-attempt a failed submission (connect, push item, push customer, push sale, stock sync, etc.).

Use the log to diagnose KRA validation errors without checking server logs.

14. Point of Sale

When eTIMS OSCU is the active transmission type (not Tremol TIMS), POS sales, returns, exchanges, and voids use the same OSCU sale endpoints as invoices. Completed sales are pushed through EtimsOscuService instead of the Tremol device driver.

Ensure the POS register's location is connected to eTIMS before completing sales. Products and customers are auto-pushed as needed.

15. CU Metadata on Documents

Successful pushes store Control Unit data in the sale's metadata JSON under etims and tims keys (for compatibility with existing print templates). Fields include:

• CU date and time
• CU invoice number
• CU serial number
• CU PIN
• Internal data and receipt signature
• QR code

Credit notes store return metadata under timsReturn as well.

16. Testing Checklist (Sandbox)

Use KRA's sandbox environment before going live. Complete this checklist in order:

16.1 Environment setup

• Confirm organization country is Kenya.
• Enter a valid test PIN under Tax settings.
• Enable e-Invoicing → eTIMS OSCU → Save.
• Ensure queue worker is running if testing automatic invoice push: php artisan queue:work

16.2 Branch connection

• Generate device serial for a test location.
• Connect with environment = Sandbox, bhfId = 00.
• Verify branch status = connected and no error in activity log.
• Click Fetch code lists — confirm product edit page shows dropdown options.

16.3 Master data

• Create or edit a test product with eTIMS fields → Push to eTIMS → status pushed.
• Create or edit a test customer with PIN and address → Push to eTIMS → status pushed.
• Intentionally use an invalid classification code → confirm failed status and error in activity log → fix and retry.

16.4 Invoices

• Create a draft invoice with the test customer and products at a connected location.
• Finalize with automatic submission off → manually Push to eTIMS → verify CU metadata and pushed status.
• Enable automatic submission → finalize another invoice → confirm job runs (queue) and status becomes pushed.
• Use Enter CU details on a test invoice → verify marked pushed status.

16.5 Credit notes & voids

• Create a credit note from a fiscalised invoice → confirm auto-push or manual push succeeds.
• Void a fiscalised invoice → confirm reversal in activity log and voided status.
• Void a fiscalised credit note → confirm reversal submission.

16.6 Stock & POS

• Click Sync stock on a connected branch → check activity log for stock master submissions.
• Run php artisan etims:sync-stock manually and confirm scheduled behaviour.
• Complete a POS sale at a connected location → verify eTIMS push (when eTIMS is active, not Tremol).

16.7 Disconnect & permissions

• Disconnect a test branch → confirm status changes and pushes are blocked until reconnected.
• Verify users without invoice edit permission cannot push sales (403 response).
• Verify non-Kenya orgs cannot access e-Invoicing settings (403).

17. Troubleshooting

• "Generate a device serial number first" — Click Generate serial before Connect.
• "Business PIN is required" — Add Tax Identifier on the Tax settings page.
• "Sale location is required" — Invoice/sale must have a location_id matching a connected branch.
• Branch not connected — Reconnect or check sandbox vs production environment.
• Product/customer push failed — Check activity log for KRA validation message; verify code lists are fetched and fields match KRA requirements.
• Automatic push not running — Confirm automatic submission is on, queue worker is running, and invoice finalized successfully.
• Credit note push failed — Source invoice must be pushed or marked pushed with a valid CU invoice number.
• e-Invoicing page not visible — Organization must be Kenya; link is hidden for other countries.