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
An overview of ERPNext's Architecture
An overview of an ERPNext Instance's communication with the eTims servers
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.
The following are the key features of the application:
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.
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 is supported for relevant DocTypes.
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.
The information that is pre-loaded on installation includes:
- Item Classification Codes
- Taxation Type Codes
- Country Codes
- Packaging Unit Codes
- Quantity Unit Codes
- Payment Type Codes
- Transaction Type Codes
- Stock Movement Type Codes
- Product Type Codes
- Importation Status Codes
The following are the key doctypes included:
- Current Environment Identifier
- Environment Settings for single and/or multiple companies
- Routes Reference
The app also creates a Workspace that collates important doctypes.
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.
This doctype aggregates all the settings, and credentials required for communication with the eTims Servers.
The fields present include:
- Branch ID: Acquired from KRA during registration for etims OSCU.
- Device Serial Number: Acquired from KRA during registration for etims OSCU.
- 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.
- 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.
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.
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.
The following are the customisations done in order for the ERPNext instance to interface with the eTims servers.
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:
- Item Classifications: Item classifications as specified by KRA
- Packaging Unit: Packaging units as specified by KRA, e.g. Jars, wooden box, etc.
- Unit of Quantity: Units of Quantity as specified by KRA, e.g. kilo-gramme, grammes, etc.
- Product Type Code: Product type as specified by KRA, e.g. finished product, raw materials, etc.
- 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.
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.
Customisations on the Sales Invoice are found under the eTims Details tab. The fields in the tab are:
- Payment Type: A reference to the relevant payment type for the invoice record. This is a link field, with values fetched from KRA.
- 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 customisations also reflect the changes such as Sales Invoice, with the same behavior for the items, as well as submission.
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.
Users are able to fetch Sales details registered by other Parties that form the basis for Purchase Documents.
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.
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.
Managing Branches is achieved via mapping Warehouses to the Navari eTims Branch doctype on a one-to-one basis.
Mapping the Warehouses to the relevant branch ensures correct referencing of Branch Ids when submitting stock movement information.
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.
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.
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.
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.
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.
| 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.