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.
Check under the Key Doctypes section to learn how to setup and get running
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: Immediately, Half-Hourly, Hourly, and Daily
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.
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.
As development is still ongoing, not all endpoints have been fully integrated with. The table below lists the endpoints that are currently supported.
| Endpoint | Status | Documentation Section |
|---|---|---|
| DeviceVerificationReq | Completely | 3.3.1.1 |
| CodeSearchReq | Completely | 3.3.2.1 |
| CustSearchReq | Completely | 3.3.2.2 |
| NoticeSearchReq | Not Yet | 3.3.2.3 |
| ItemClsSearchReq | Completely | 3.3.3.1 |
| ItemSaveReq | Completely | 3.3.3.2 |
| ItemSearchReq | Not Yet | 3.3.3.3 |
| BhfSearchReq | Not Yet | 3.3.4.1 |
| BhfCustSaveReq | Not Yet | 3.3.4.2 |
| BhfUserSaveReq | Not Yet | 3.3.4.3 |
| BhfInsuranceSaveReq | Not Yet | 3.3.4.4 |
| ImportItemSearchReq | Not Yet | 3.3.5.1 |
| ImportItemUpdateReq | Not Yet | 3.3.5.2 |
| TrnsSalesSaveWrReq | Completely | 3.3.6.1 |
| TrnsPurchaseSalesReq | Not Yet | 3.3.7.1 |
| TrnsPurchaseSaveReq | Not Yet | 3.3.7.2 |
| StockMoveReq | Completely | 3.3.8.1 |
| StockIOSaveReq | Completely | 3.3.8.2 |
| StockMasterSaveReq | Not Yet | 3.3.8.2 |
To get a deeper understanding of the above endpoints, consult the documentation provided by KRA in the beginning.