Skip to content

navariltd/kenya-compliance

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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 ERPNext Architectural Overview

An overview of an ERPNext Instance's communication with the eTims servers Architectural Overview

Once the application is installed and configured in an ERPNext instance, communication to the ETims servers takes place through background jobs executed by Redis Queue. The eTims response Information is stored in the relevant customised DocType's tables in the site's database.

Key Features

The following are the key features of the application:

  1. Application Workspace
  2. Error Logs
  3. Bulk submission of information
  4. Flexible setup and configuration

App Workspace

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

Example Error Log

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 Records

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 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.

Refreshing data

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
  10. Importation Status Codes

Key DocTypes

The following are the key doctypes included:

  1. Current Environment Identifier
  2. Environment Settings for single and/or multiple companies
  3. 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.

Current Environment Identifier

Environment Settings

This doctype aggregates all the settings, and credentials required for communication with the eTims Servers.

Environment Settings

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.

Environment Settings Next Tab

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.

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

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 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
  2. Sales Invoice Doctype
  3. POS Invoice Doctype
  4. Customer Doctype

Item Doctype

Item Doctype Customisations

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

Customer Doctype Customisations

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

Sales Invoice Customisations

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.

Sales Invoice Items Customisations

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 through Background Jobs to relieve users from having to manually submit Stock Balance (inventory) information, as well as changes in stocks.

The frequency of submission can be customised from the relevant settings record, under the Submission Frequency Settings tab.

NOTE: Only Stockable Items are submitted to eTims Servers.

Fetching Purchases

Users are able to fetch Sales details registered by other Parties that form the basis for Purchase Documents.

Registered Purchases

Once the counter-party's sales information (your purchase) is successfully fetched, you can create Items, Suppliers, Purchase Invoices, and Purchase Receits from the details.

Registered Purchases Actions

NOTE: This feature is highly experimental and may result in discrepancies between the information fetched and the generated records, e.g. Tax Details after creating a Purchase Invoice.

Branch Management

branch management

Managing Branches is achieved via mapping Warehouses to the Navari eTims Branch doctype on a one-to-one basis.

warehouses

Mapping the Warehouses to the relevant branch ensures correct referencing of Branch Ids when submitting stock movement information.

Imported Item Management

imported item management

The Registered Imported Item doctype allows one to fetch imported items declared to belong to the user's company. These Items can be of existing Items (items already in ERPNext's database) or new Items.

imported item record view

To link an Imported Item to an existing Item, you reference the Item in the Referenced Imported Item field of Item doctype under the Purchasing tab.

linking item with imported item

Once the records have been linked, the user can submit the converted (specifying the item classification of the accepted imported item) back to eTims to register the item. This is done through the eTims Action, Submit Imported Item action button. This action button is active if the Item is linked to an Imported Item and the Item has not been registered prior.

How to Install

Manual Installation/Self Hosting

To install the app, Setup, Initialise, and run a Frappe Bench instance.

Once the instance is up and running, add the application to the environment by running the command below in an active Bench terminal:

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

followed by:

bench --site <your.site.name.here> install-app kenya_compliance

To run tests, ensure Testing is enabled in the target site by executing:

bench --site <your.site.name.here> set-config allow_tests true

followed by

bench --site <your.site.name.here> run-tests --app kenya_compliance

NOTE: Replace <your.site.name.here> with the target site name.

FrappeCloud Installation

Installing on FrappeCloud can be achieved after setting up a Bench instance, and a site. The app can then be added using the Add App button in the App tab of the bench and referencing this repository by using the Install from GitHub option if you are not able to search for the app.

Summary of Integrated Endpoints

Endpoint Status Documentation Section
DeviceVerificationReq Completely 3.3.1.1
CodeSearchReq Completely 3.3.2.1
CustSearchReq Completely 3.3.2.2
NoticeSearchReq Completely 3.3.2.3
ItemClsSearchReq Completely 3.3.3.1
ItemSaveReq Completely 3.3.3.2
ItemSearchReq Completely 3.3.3.3
BhfSearchReq Completely 3.3.4.1
BhfCustSaveReq Completely 3.3.4.2
BhfUserSaveReq Completely 3.3.4.3
BhfInsuranceSaveReq Completely 3.3.4.4
ImportItemSearchReq Completely 3.3.5.1
ImportItemUpdateReq Completely 3.3.5.2
TrnsSalesSaveWrReq Completely 3.3.6.1
TrnsPurchaseSalesReq Completely 3.3.7.1
TrnsPurchaseSaveReq Completely 3.3.7.2
StockMoveReq Completely 3.3.8.1
StockIOSaveReq Completely 3.3.8.2
StockMasterSaveReq Completely 3.3.8.2
SaveItemComposition Completely Section not specified in documentation

To get a deeper understanding of the above endpoints, consult the documentation provided by KRA in the beginning.

Releases

No releases published

Packages

No packages published