{"id":39620629,"url":"https://github.com/navariltd/kenya-compliance","last_synced_at":"2026-01-18T08:25:51.035Z","repository":{"id":222655726,"uuid":"727131594","full_name":"navariltd/kenya-compliance","owner":"navariltd","description":"KRA eTIMS Tax Compliance Integration 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.via OSCU with ERPNext","archived":false,"fork":false,"pushed_at":"2025-10-06T18:09:15.000Z","size":2959,"stargazers_count":49,"open_issues_count":4,"forks_count":40,"subscribers_count":11,"default_branch":"develop","last_synced_at":"2025-10-06T20:22:29.319Z","etag":null,"topics":["e-invoicing","kra-etims-tax-compliance","open-source"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/navariltd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-04T08:50:37.000Z","updated_at":"2025-10-06T18:09:19.000Z","dependencies_parsed_at":"2024-02-23T14:27:45.319Z","dependency_job_id":"9fbd0895-7fbc-4eb7-8d38-2cc32667ed4f","html_url":"https://github.com/navariltd/kenya-compliance","commit_stats":null,"previous_names":["navariltd/kenya-compliance"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/navariltd/kenya-compliance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navariltd%2Fkenya-compliance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navariltd%2Fkenya-compliance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navariltd%2Fkenya-compliance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navariltd%2Fkenya-compliance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/navariltd","download_url":"https://codeload.github.com/navariltd/kenya-compliance/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navariltd%2Fkenya-compliance/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["e-invoicing","kra-etims-tax-compliance","open-source"],"created_at":"2026-01-18T08:25:50.974Z","updated_at":"2026-01-18T08:25:51.020Z","avatar_url":"https://github.com/navariltd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Note\n* This app is no longer in active development. That said, it was comprehensively tested using KRA Sandbox environment in 2024.\n* 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.\n* 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.\n\n# Kenya-Compliance\n\n\u003ca id=\"more_details\"\u003e\u003c/a\u003e\n\nThis 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.\n\nThis 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.\n\nFor more details about eTims:\n\n\u003ca id=\"etims_official_documentation\"\u003e\u003c/a\u003e\n\nhttps://www.kra.go.ke/images/publications/OSCU_Specification_Document_v2.0.pdf\n\n## Architectural Overview\n\n\u003ca id=\"architectural_overview\"\u003e\u003c/a\u003e\n\nAn overview of ERPNext's Architecture\n![ERPNext Architectural Overview](/kenya_compliance/docs/images/erpnext_instance_architecture.PNG)\n\nAn overview of an ERPNext Instance's communication with the eTims servers\n![Architectural Overview](/kenya_compliance/docs/images/architectural_overview.jpg)\n\nOnce 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).\n\n## Key Features\n\nThe following are the key features of the application:\n\n1. [Application Workspace](#workspace)\n2. [Error Logs](#error_logs)\n3. [Bulk submission of information](#bulk_submissions)\n4. [Flexible setup and configuration](#flexible_setup_and_configuration)\n\n### App Workspace\n\n\u003ca id=\"workspace\"\u003e\u003c/a\u003e\n\n![App Workspace](/kenya_compliance/docs/images/workspace.PNG)\n\nThe workspace contains shortcuts to various documents of interest concerning eTims.\n\n**NOTE**: The workspace may look different depending on when you install the app or due to future changes.\n\n### Error Logs\n\n\u003ca id=\"error_logs\"\u003e\u003c/a\u003e\n\n![Example Error Log](/kenya_compliance/docs/images/error_log.PNG)\n\nEach 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.\n\n### Bulk Submission of Information\n\n\u003ca id=\"bulk_submissions\"\u003e\u003c/a\u003e\n\n![Bulk Submission of Records](/kenya_compliance/docs/images/bulk_submission.PNG)\n\nBulk submission of information is supported for relevant DocTypes.\n\n### Flexible Setup and Configuration\n\n\u003ca id=\"flexible_setup_and_configuration\"\u003e\u003c/a\u003e\n\nBy 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**.\n\n![Refreshing data](/kenya_compliance/docs/images/refresh%20codes.PNG)\n\nThe information that is pre-loaded on installation includes:\n\n1. Item Classification Codes\n2. Taxation Type Codes\n3. Country Codes\n4. Packaging Unit Codes\n5. Quantity Unit Codes\n6. Payment Type Codes\n7. Transaction Type Codes\n8. Stock Movement Type Codes\n9. Product Type Codes\n11. Importation Status Codes\n\n## Key DocTypes\n\n\u003ca id=\"key_doctypes\"\u003e\u003c/a\u003e\n\nThe following are the key doctypes included:\n\n1. [Current Environment Identifier](#current_env_id)\n2. [Environment Settings for single and/or multiple companies](#environment_settings)\n3. [Routes Reference](#routes_reference)\n\nThe app also creates a Workspace that collates important doctypes.\n\n### Current Environment Identifier\n\n\u003ca id=\"current_env_id\"\u003e\u003c/a\u003e\n\nThis 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.\n\nThis is a Single doctype with only two possible values: _Sandbox or Production_.\n\n**NOTE**: The option is applied globally to all users of the current ERPNext instance.\n\n![Current Environment Identifier](/kenya_compliance/docs/images/current_environment_identifier.PNG)\n\n### Environment Settings\n\n\u003ca id=\"environment_settings\"\u003e\u003c/a\u003e\n\nThis doctype aggregates all the settings, and credentials required for communication with the eTims Servers.\n\n![Environment Settings](/kenya_compliance/docs/images/environment_settings.PNG)\n\nThe fields present include:\n\n1. **Branch ID**: Acquired from KRA during registration for etims OSCU.\n2. **Device Serial Number**: Acquired from KRA during registration for etims OSCU.\n3. **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.\n4. **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.\n\n**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.\n\n![Environment Settings Next Tab](/kenya_compliance/docs/images/environment_settings_page_2.PNG)\n\n\u003ca id=\"submission_frequency\"\u003e\u003c/a\u003e\n\nThe 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.\n\nTo learn more about Cron, and how to specify Cron Expression, [Click here](https://en.wikipedia.org/wiki/Cron).\n\n**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**.\n\n### Routes Reference\n\n\u003ca id=\"routes_reference\"\u003e\u003c/a\u003e\n\n![Routes Reference](/kenya_compliance/docs/images/routes_reference.PNG)\n\nThis 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.\n\n**NOTE**: The _URL Path Function_ field is used as the search parameter whenever an endpoint is retrieved.\n\n## Customisations\n\nThe following are the customisations done in order for the ERPNext instance to interface with the eTims servers.\n\n1. [Item Doctype](#item_doctype_customisations)\n2. [Sales Invoice Doctype](#sales_invoice_doctype_customisations)\n3. [POS Invoice Doctype](#pos_invoice_doctype_customisations)\n4. [Customer Doctype](#customer_doctype_customisations)\n\n### Item Doctype\n\n\u003ca id=\"item_doctype_customisations\"\u003e\u003c/a\u003e\n\n![Item Doctype Customisations](/kenya_compliance/docs/images/item_etims_tab.PNG)\n\nThe **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.\n\n**NOTE**: The information captured here is mandatory when sending sales information to the eTims servers.\n\nThe doctypes linked include:\n\n1. **Item Classifications**: Item classifications as specified by KRA\n2. **Packaging Unit**: Packaging units as specified by KRA, e.g. Jars, wooden box, etc.\n3. **Unit of Quantity**: Units of Quantity as specified by KRA, e.g. kilo-gramme, grammes, etc.\n4. **Product Type Code**: Product type as specified by KRA, e.g. finished product, raw materials, etc.\n5. **Country of Origin**: The country of origin declared for the item.\n\nThe _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.\n\n### Customer Doctype\n\n\u003ca id=\"customer_doctype_customisations\"\u003e\u003c/a\u003e\n\n![Customer Doctype Customisations](/kenya_compliance/docs/images/customer_doctype.PNG)\n\nFor 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_.\n\n**NOTE**: Supplying the customer's KRA PIN is a pre-requisite to making the search.\n\n### Sales Invoice\n\n\u003ca id=\"sales_invoice_doctype_customisations\"\u003e\u003c/a\u003e\n\n![Sales Invoice Customisations](/kenya_compliance/docs/images/sales_invoice_details.PNG)\n\nCustomisations on the Sales Invoice are found under the eTims Details tab. The fields in the tab are:\n\n1. **Payment Type**: A reference to the relevant payment type for the invoice record. This is a link field, with values fetched from KRA.\n2. **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.\n\nFields 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.\n\n![Sales Invoice Items Customisations](/kenya_compliance/docs/images/sales_invoice_item_details.PNG)\n\nFor 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.\n\n**NOTE**: Submission of the data happens whenever one submits a sales invoice as a background job.\n\n### POS Invoice\n\n\u003ca id=\"pos_invoice_doctype_customisations\"\u003e\u003c/a\u003e\n\nPOS Invoice customisations also reflect the changes such as Sales Invoice, with the same behavior for the items, as well as submission.\n\n### Stock Movements\n\n\u003ca id=\"stock_movements\"\u003e\u003c/a\u003e\n\nTransactions that affect stock levels are automatically submitted to the eTims Servers.\n\nSubmission of Stock Movements is achieved by sending Stock Ledger Entry records. The process has been automated through [Background Jobs](#background_jobs) to relieve users from having to manually submit Stock Balance (inventory) information, as well as changes in stocks.\n\nThe frequency of submission can be customised from the relevant settings record, under the [Submission Frequency Settings](#submission_frequency) tab.\n\n**NOTE**: Only Stockable Items are submitted to eTims Servers.\n\n### Fetching Purchases\n\n\u003ca id=\"registered_purchases\"\u003e\u003c/a\u003e\n\nUsers are able to fetch Sales details registered by other Parties that form the basis for Purchase Documents.\n\n![Registered Purchases](/kenya_compliance/docs/images/registered_purchases.PNG)\n\nOnce the counter-party's sales information (your purchase) is successfully fetched, you can create Items, Suppliers, Purchase Invoices, and Purchase Receits from the details.\n\n![Registered Purchases Actions](/kenya_compliance/docs/images/registered_purchases_actions.PNG)\n\n**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.\n\n### Branch Management\n\n\u003ca id=\"branch_management\"\u003e\u003c/a\u003e\n\n![branch management](/kenya_compliance/docs/images/branch.PNG)\n\nManaging Branches is achieved via mapping Warehouses to the Navari eTims Branch doctype on a one-to-one basis.\n\n![warehouses](/kenya_compliance/docs/images/warehouse.PNG)\n\nMapping the Warehouses to the relevant branch ensures correct referencing of Branch Ids when submitting stock movement information.\n\n### Imported Item Management\n\n\u003ca id=\"imported_item_management\"\u003e\u003c/a\u003e\n\n![imported item management](/kenya_compliance/docs/images/fetching%20imported%20items.PNG)\n\nThe **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.\n\n![imported item record view](/kenya_compliance/docs/images/imported%20item%20record%20view.PNG)\n\nTo 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.\n\n![linking item with imported item](/kenya_compliance/docs/images/linking%20imported%20item%20to%20item.PNG)\n\nOnce 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.\n\n## How to Install\n\n\u003ca id=\"installation\"\u003e\u003c/a\u003e\n\n### Manual Installation/Self Hosting\n\n\u003ca id=\"manual_installation\"\u003e\u003c/a\u003e\n\nTo install the app, [Setup, Initialise, and run a Frappe Bench instance](https://frappeframework.com/docs/user/en/installation).\n\nOnce the instance is up and running, add the application to the environment by running the command below in an active Bench terminal:\n\n`bench get-app https://github.com/navariltd/kenya-compliance.git`\n\nfollowed by:\n\n`bench --site \u003cyour.site.name.here\u003e install-app kenya_compliance`\n\nTo run tests, ensure Testing is enabled in the target site by executing:\n\n`bench --site \u003cyour.site.name.here\u003e set-config allow_tests true`\n\nfollowed by\n\n`bench --site \u003cyour.site.name.here\u003e run-tests --app kenya_compliance`\n\n**NOTE**: Replace _\u003cyour.site.name.here\u003e_ with the target site name.\n\n### FrappeCloud Installation\n\n\u003ca id=\"frappecloud_installation\"\u003e\u003c/a\u003e\n\nInstalling on [FrappeCloud](https://frappecloud.com/docs/introduction) 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.\n\n### Summary of Integrated Endpoints\n\n| Endpoint              |   Status   | [Documentation Section](#more_details) |\n| :-------------------- | :--------: | -------------------------------------: |\n| DeviceVerificationReq | Completely |                                3.3.1.1 |\n| CodeSearchReq         | Completely |                                3.3.2.1 |\n| CustSearchReq         | Completely |                                3.3.2.2 |\n| NoticeSearchReq       | Completely |                                3.3.2.3 |\n| ItemClsSearchReq      | Completely |                                3.3.3.1 |\n| ItemSaveReq           | Completely |                                3.3.3.2 |\n| ItemSearchReq         | Completely |                                3.3.3.3 |\n| BhfSearchReq          | Completely |                                3.3.4.1 |\n| BhfCustSaveReq        | Completely |                                3.3.4.2 |\n| BhfUserSaveReq        | Completely |                                3.3.4.3 |\n| BhfInsuranceSaveReq   | Completely |                                3.3.4.4 |\n| ImportItemSearchReq   | Completely |                                3.3.5.1 |\n| ImportItemUpdateReq   | Completely |                                3.3.5.2 |\n| TrnsSalesSaveWrReq    | Completely |                                3.3.6.1 |\n| TrnsPurchaseSalesReq  | Completely |                                3.3.7.1 |\n| TrnsPurchaseSaveReq   | Completely |                                3.3.7.2 |\n| StockMoveReq          | Completely |                                3.3.8.1 |\n| StockIOSaveReq        | Completely |                                3.3.8.2 |\n| StockMasterSaveReq    | Completely |                                3.3.8.2 |\n| SaveItemComposition   | Completely | Section not specified in documentation |\n\nTo get a deeper understanding of the above endpoints, consult the [documentation provided by KRA](#more_details) in the beginning.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavariltd%2Fkenya-compliance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnavariltd%2Fkenya-compliance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavariltd%2Fkenya-compliance/lists"}