POS: Tremol TIMS & KRA Integration

1. What is Tremol TIMS?

TIMS (Tax Invoice Management System) is Kenya's KRA-compliant system for recording sales and tax data. The Tremol G03 Type C is a fiscal device (Control Unit) that connects to your POS and transmits transaction data to KRA. Tracksales sends each sale, return, exchange, and void to the Tremol device, which then reports to KRA.

2. Setup & Configuration

To enable Tremol TIMS:

1. Go to Settings → Preferences → Tax.
2. Under KRA Tax Transmission, select TIMS.
3. In the TIMS Setup section, enter:
   • Device Type — Tremol G03 Type C
   • Url — The Tremol service URL
   • Ip Address — Your Tremol device IP
   • Port — Connection port (e.g. 34952)
   • Password — Device password
4. Save your settings.

Ensure your Tremol device is powered on, connected to the network, and reachable from the server running Tracksales. If any field is missing or the device is unreachable, transmission will fail and the sale will not complete.

3. When Tremol Transmission Happens

Transmission occurs automatically when you complete certain actions at the Point of Sale. It does not run for suspended sales, training-mode sales, or when TIMS is disabled.

4. Sales

When you complete a regular sale (not a return or exchange), Tracksales:

• Opens an invoice on the Tremol device
• Adds each line item with price, quantity, tax class, and tax rate
• Closes the receipt and receives the Control Unit invoice number, serial number, PIN, and QR code
• Stores this metadata in the sale record for audit and for linking future returns

If the customer has a tax identifier (KRA PIN), it is sent to the device for inclusion on the receipt.

5. Returns

When you process a return against an original sale:

• Tracksales looks up the original sale's Control Unit invoice number (stored in metadata)
• Opens a credit note on Tremol linked to that original invoice
• Adds the returned items (as positive quantities on the credit note)
• Closes the receipt and stores the credit note metadata

6. Exchanges

An exchange is when a customer returns some items and receives new items in the same transaction. Tracksales sends both parts to Tremol for full KRA compliance:

1. Credit note — For the returned items (negative quantities), linked to the original sale
2. New invoice — For the new items (positive quantities)

Both receipts are issued on the Tremol device, and the sale record stores metadata for both the credit note and the new invoice.

7. Voiding Sales

When you void a completed sale:

• Tracksales checks that the sale has TIMS metadata (was transmitted)
• Opens a credit note on Tremol to reverse the original invoice
• Adds all original line items with the same quantities and prices
• Closes the receipt and updates the sale metadata

You cannot void a sale that has returns. Void the associated returns first, then void the original sale. Suspended sales are not transmitted to Tremol, so voiding a suspended sale does not trigger any Tremol transmission.

8. Metadata Stored

Each sale record stores TIMS metadata in the metadata column. This includes:

• cuInvoiceNum — Control Unit invoice number (required for returns and voids)
• cuSerialNumber — Device serial number
• cuPINnumber — Receipt PIN
• cuQRcode — QR code for verification
• cuDateTime — Timestamp from the device

For returns and voids, timsReturn metadata is also stored with the credit note details.

9. Tax Classes

Tremol uses VAT tax class codes (A, B, C, etc.). Tracksales maps your tax classes to these codes. If your tax classes have a code field, that value is used. Otherwise, the default A is used.

10. Troubleshooting

Common errors and solutions:

• "Socket connect FAILED" — The Tremol ZFP Lab proxy is reachable, but it cannot connect to the fiscal device. The machine running the proxy must be able to reach the device on the configured IP and port. Check: device is powered on and on the network; IP and port in Settings → Tax → TIMS Setup are correct; no firewall blocking the connection; the proxy runs on the same network as the device (or has a route to it).
• "Your KRA Control Unit is down or misconfigured" — Check that the Tremol device is powered on, connected to the network, and that the URL, IP, port, and password in Tax settings are correct. Ensure the device is reachable from your server.
• "Original sale has no CU invoice number for return" — The original sale was not transmitted to Tremol (e.g. made before TIMS was enabled). You cannot process a return through Tremol for that sale.
• "This sale has returns. Void the associated returns first." — You must void each return sale before voiding the original sale.
• "Failed to open Tremol invoice" / "Failed to close Tremol receipt" — The device may be busy, out of paper, or in an error state. Check the device status and try again.
• "Command: Illegal" (returns/refunds) — The Tremol device rejected the credit note command. The error message now includes decoded status (e.g. "Illegal command", "Invoice number not found!", "Item amount too large!"). Check storage/logs/laravel.log for detailed debug info: Tremol OpenCreditNote failed, Tremol SellPLU failed on return, Tremol CloseReceipt failed on return. Each log includes STE1/STE2 status bytes and decoded descriptions. Ensure the original sale was transmitted to Tremol and has a valid 19-character CU invoice number. If the error persists, verify the Tremol device firmware is up to date and contact your device supplier or KRA support.