KRA eTIMS

KRA eTIMS Integration for Botble CMS

• Version: 1.1.0 (Full Compliance Edition)
• Compatibility: Botble Ecommerce (Shofy, Farmart, etc.)
• API Standard: KRA OSCU / VSCU (Virtual Sales Control Unit)

Purchase Links

* You can purchase the plugin directly from either of the links below:

* 👉 https://paystack.shop/motion-media-kenya 👉 (KSH)

* 👉 https://paystack.shop/motion-media-storefront 👉 (USD)

1. Executive Overview

The KRA eTIMS Integration plugin is a comprehensive tax compliance solution designed for Kenyan merchants using the Botble CMS platform. It transforms your online store into a Trader Invoicing System (TIS) compliant with KRA's electronic tax requirements. Unlike basic integrations that only handle sales, this version supports the full lifecycle of a transaction required for OSCU Self-Integration Certification:

1. Sales Invoices: Automatic signing and QR code generation for new orders.
2. Credit Notes: Automatic generation of refund receipts (Credit Notes) when an order is returned.
3. Stock Management: Real-time synchronization of inventory changes (Stock In/Out) to KRA servers.

2. Key Features

🛒 Sales & Invoicing

• Instant Transmission: Orders are sent to KRA the moment they are created.
• Smart Tax Mapping: Automatically detects VAT (16%) vs. Zero-rated (0%) items based on product configuration.
• QR Codes: Appends the official KRA verification QR code URL to every transaction record.

↩️ Credit Notes (Returns)

• Seamless Integration: Hooks directly into Botble’s native "Order Return" functionality.
• Compliance: References the Original KRA Invoice Number (orgInvcNo) as required by tax law.
• Auto-Calculation: Handles partial returns and recalculates tax refunds automatically.

📦 Stock Management (Inventory)

• Real-Time Sync: Listens for product quantity updates in the admin panel.
• Stock IO: Reports inventory movements (Stock In/Restocking) to the KRA servers to maintain a balanced ledger.

⚙️ Admin & Reporting

• Transaction Dashboard: A unified view of all Sales and Credit Notes with status indicators.
• Stock Logs: A dedicated audit trail showing every inventory synchronization attempt.
• Dual Environment: One-click switch between Sandbox (Testing) and Production (Live).

Installation & Upgrade Guide

First-Time Installation

1. Upload the etims folder to platform/plugins/.
2. Go to Admin -> Plugins.
3. Click Activate on "KRA eTIMS".

Configuration

1. Navigate to KRA eTIMS -> Settings.
2. Enable eTIMS: Toggle to "Yes".
3. Environment: Select Sandbox for testing or Production for live tax filing.

Credentials:

• KRA PIN: Your registered Tax PIN.
• Branch ID: Usually 00.
• Device Serial Number: The Virtual Device serial provided by KRA (e.g., mb2023...).

Initialization:

• Click "Save Settings & Initialize Device".
• Wait for the page to reload. A successful connection will populate the Communication Key field automatically.

3. Usage Guide (How to Operate)

Scenario A: Processing a Sale

• Action: No manual action required.
• Process: When a customer places an order (or you create one manually in Admin), the plugin sends the data to KRA.
• Verification: Go to KRA eTIMS -> Transactions. You will see a record with Type: SALE and Status: Success.

Scenario B: Processing a Return (Credit Note)

• Action:

1. Go to Ecommerce -> Orders.
2. Open the order you wish to refund.
3. Click the "Return" button (Top right).
4. Select items to return and click Submit.

• Process: The plugin detects this return, finds the Original KRA Invoice Number associated with that order, and sends a "Type R" (Refund) request to KRA.
• Verification: Go to KRA eTIMS -> Transactions. You will see a new record with Type: CREDIT NOTE.

Scenario C: Updating Inventory

• Action:

1. Go to Ecommerce -> Products.
2. Edit a product and change the Quantity (e.g., add 10 items).
3. Click Save.

• Process: The plugin detects the quantity change and sends a "Stock IO" request to KRA.
• Verification: Go to KRA eTIMS -> Stock Logs. You will see a log entry for that Product SKU with Status: Synced.

4. KRA Certification Details (Technical Specs)

• If you are undergoing the KRA Self-Integration certification process, use these details to fill out your application forms.
• Requirement Implementation Detail
• Architecture Botble CMS (PHP/Laravel) + Native REST API Connector
• Communication Protocol HTTPS / JSON
• OSCU Endpoints Used /selectInitOsdcInfo (Init)
  /saveTrnsSalesOsdc (Sales & Credit Notes)
  /saveStockIoOsdc (Inventory)
• Sales Type Codes N (Normal Sale)
• Receipt Type Codes S (Sale), R (Credit Note/Refund)
• Tax Mapping A = 16% VAT, B = 0% VAT (Exempt/Zero-rated)

5. Troubleshooting

* Return/Credit Note Failed

• Reason: The original order was never sent to KRA, or it failed.
• Fix: You cannot issue a Credit Note for an order that doesn't exist in the KRA system. Ensure the original Sales Invoice shows "Success" in the Transactions report before attempting a return.

* Stock Not Syncing

• Reason: The product SKU might be missing or too long.
• Fix: Ensure all products have a valid SKU (Max 20 characters). KRA requires an Item Code for stock updates.

* "Communication Key Missing"

• Reason: Device Initialization was skipped.
• Fix: Go to Settings and click "Initialize Device" again.

6. Support & Updates

For additional features or technical support, please check the plugin dashboard or contact the system administrator. Copyright © 2025 Motion Media | motionmedia.co.ke | [email protected] | +254 710 827 159.