Kenya Compliance

bench get-app https://github.com/navariltd/kenya-compliance

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=navariltd%2Fkenya-compliance)](https://frappegems.com/gems/apps/navariltd/kenya-compliance)

# Note * This app is no longer in active development. That said, it was comprehensively tested using KRA Sandbox environment in 2024. * To use it, you need to seek approval from KRA for the App: either as a self integrator, or as a 3rd party integrator. This is the difficult part in my view. * Instead use, [https://github.com/navariltd/kenya-compliance-via-slade](https://github.com/navariltd/kenya-compliance-via-slade), which is in active use. Contact Slade360 Advantage team. Their contacts are at the bottom of the Kenya Compliance via Slade readme. # Kenya-Compliance This app works to integrate ERPNext with KRA's eTIMS via the Online Sales Control Unit (OSCU) to allow for the sharing of information with the revenue authority. This integration allows the user to send and receive the required information after sales, and purchase transactions, updating inventory, and creating customers. The user can also register their information such as items to the eTims servers. For more details about eTims: https://www.kra.go.ke/images/publications/OSCU_Specification_Document_v2.0.pdf ## Architectural Overview An overview of ERPNext's Architecture  An overview of an ERPNext Instance's communication with the eTims servers  Once the application is [installed](#installation) and [configured](#environment-settings) in an ERPNext instance, communication to the ETims servers takes place through background jobs executed by [Redis Queue](https://redis.com/glossary/redis-queue/). The eTims response Information is stored in the relevant [customised DocType's](#customisations) tables in the [site's database](https://frappeframework.com/docs/user/en/basics/sites). ## Key Features The following are the key features of the application: 1. [Application Workspace](#workspace) 2. [Error Logs](#error_logs) 3. [Bulk submission of information](#bulk_submissions) 4. [Flexible setup and configuration](#flexible_setup_and_configuration) ### App Workspace  The workspace contains shortcuts to various documents of interest concerning eTims. **NOTE**: The workspace may look different depending on when you install the app or due to future changes. ### Error Logs  Each request is logged in the Integration Request DocType. Any response errors are logged in the Error Log doctype. Additionally, logs are written and can also be accessed through the logs folder of the bench harbouring the running instance if the records in the Error Logs/Integration Request DocTypes are cleared. ### Bulk Submission of Information  Bulk submission of information is supported for relevant DocTypes. ### Flexible Setup and Configuration By default, the application comes with some data pre-loaded to allow the user to begin immediately. This is data that was fetched during development and might be stale depending on when you [install](#how-to-install) the application. **Ensure you update the information immediately after getting valid credentials by clicking the _Get Codes_ action button in the eTims settings Doctype, as shown below**.  The information that is pre-loaded on installation includes: 1. Item Classification Codes 2. Taxation Type Codes 3. Country Codes 4. Packaging Unit Codes 5. Quantity Unit Codes 6. Payment Type Codes 7. Transaction Type Codes 8. Stock Movement Type Codes 9. Product Type Codes 11. Importation Status Codes ## Key DocTypes The following are the key doctypes included: 1. [Current Environment Identifier](#current_env_id) 2. [Environment Settings for single and/or multiple companies](#environment_settings) 3. [Routes Reference](#routes_reference) The app also creates a Workspace that collates important doctypes. ### Current Environment Identifier This doctype is used to provide a global identifier for the current environment, which will in turn influence whether communication will happen with the Sandbox or Production eTims servers that KRA has provided. This is a Single doctype with only two possible values: _Sandbox or Production_. **NOTE**: The option is applied globally to all users of the current ERPNext instance.  ### Environment Settings This doctype aggregates all the settings, and credentials required for communication with the eTims Servers.  The fields present include: 1. **Branch ID**: Acquired from KRA during registration for etims OSCU. 2. **Device Serial Number**: Acquired from KRA during registration for etims OSCU. 3. **Company**: This is a link to an existing company in the ERPNext instance. 4.**Sandbox Environment Check**: Marks the current settings record as associated with either the Sandbox or Production eTims server. Sandbox is used for testing while Production is for real-world cases. Make sure to choose the correct environment. 4. **is Active Check**: Marks the current settings record as the active one, in the event of multiple settings for the same company. Note you can only have one settings record as active for each unique combination of environment, company (and by extension company PIN), and branch Id. **NOTE**: The company's PIN selected together with the Branch Id and Device Serial number are important in generating the communication key, which is in turn used for all subsequent communication with eTims servers.  The additional Settings tab offers options to customise the frequency of communication to the eTims Servers. Choosing hourly implies information will be batched, and sent on an hourly basis. Possible options include: _All_, _Hourly_, _Daily_, as well as the possibility of adding custom configurations through the _Cron_ option among others. To learn more about Cron, and how to specify Cron Expression, [Click here](https://en.wikipedia.org/wiki/Cron). **NOTE**: The communication key is stored in this doctype, and it's fetched immediately one tries to save a record. If all information is valid, a valid key will be issued and stored which is used for all subsequent communication. If the key was not fetched, one cannot proceed to save the record as that will impose an inconsistent state upon the system. **The key is only issued once. In the event of loosing it, one has to liaise with KRA to regenerate a new key**. ### Routes Reference  This doctype holds references to the endpoints provided by KRA for the various activities. Each endpoint has an associated last request date that is updated after each eTims response. For a comprehensive documentation on the various endpoints, see the [More Details](#etims_official_documentation) section at the beginning. **NOTE**: The _URL Path Function_ field is used as the search parameter whenever an endpoint is retrieved. ## Customisations The following are the customisations done in order for the ERPNext instance to interface with the eTims servers. 1. [Item Doctype](#item_doctype_customisations) 2. [Sales Invoice Doctype](#sales_invoice_doctype_customisations) 3. [POS Invoice Doctype](#pos_invoice_doctype_customisations) 4. [Customer Doctype](#customer_doctype_customisations) ### Item Doctype  The **eTims Details tab** will be present for each item during and after loading of each item. The tab holds fields to various doctypes that allow one to classify each item according to the specifications provided by KRA. **NOTE**: The information captured here is mandatory when sending sales information to the eTims servers. The doctypes linked include: 1. **Item Classifications**: Item classifications as specified by KRA 2. **Packaging Unit**: Packaging units as specified by KRA, e.g. Jars, wooden box, etc. 3. **Unit of Quantity**: Units of Quantity as specified by KRA, e.g. kilo-gramme, grammes, etc. 4. **Product Type Code**: Product type as specified by KRA, e.g. finished product, raw materials, etc. 5. **Country of Origin**: The country of origin declared for the item. The _eTims Action_ button is also present for items that have not been registered in the etims server (for the lifetime of the current instance), which are denoted by the _Item Registered?_ check field not being ticked. This is a read-only field that is updated only after successful Item registration. ### Customer Doctype  For customers, the customisations are domiciled in the Tax tab. Also present is the eTims Actions Button where one can perform a _Customer Search_ in the eTims Servers. Successful customer searches update read-only fields in the same record and check the _Is Validated field_. **NOTE**: Supplying the customer's KRA PIN is a pre-requisite to making the search. ### Sales Invoice  Customisations on the Sales Invoice are found under the eTims Details tab. The fields in the tab are: 1. **Payment Type**: A reference to the relevant payment type for the invoice record. This is a link field, with values fetched from KRA. 2. **Transaction Progress**: A reference to the relevant transaction progress for the invoice record. This is also a link field, with values also fetched from KRA. Fields under the _eTims Response Details_ are values received as a response from eTims. These are read-only, and only updated after a successful response is received.  For each item, the above fields are required in order to submit sales information to eTims. These information is fetched from the item data by default, but it can be edited on the sales invoice before submitting information. **NOTE**: Submission of the data happens whenever one submits a sales invoice as a background job. ### POS Invoice POS Invoice customisations also reflect the changes such as Sales Invoice, with the same behavior for the items, as well as submission. ### Stock Movements Transactions that affect stock levels are automatically submitted to the eTims Servers. Submission of Stock Movements is achieved by sending Stock Ledger Entry records. The process has been automated throu