diff --git a/content/applications/finance/accounting.rst b/content/applications/finance/accounting.rst index f375dc038..454afe4d9 100644 --- a/content/applications/finance/accounting.rst +++ b/content/applications/finance/accounting.rst @@ -76,6 +76,8 @@ expense either when the transaction occurs (accrual basis) or when the payment i .. seealso:: :doc:`Cash basis ` +.. _accounting/multi-company: + Multi-company ============= diff --git a/content/applications/finance/fiscal_localizations/kenya.rst b/content/applications/finance/fiscal_localizations/kenya.rst index c03e2f1db..8df68115e 100644 --- a/content/applications/finance/fiscal_localizations/kenya.rst +++ b/content/applications/finance/fiscal_localizations/kenya.rst @@ -7,114 +7,336 @@ Kenya Configuration ============= -:ref:`Install ` the following modules to get all the features of the Kenyan -localization: +Install the 🇰🇪 **Kenyan** :ref:`fiscal localization package ` to get +all the features of the Kenyan localization. -.. list-table:: - :header-rows: 1 +eTIMS +===== - * - Name - - Technical name - - Description - * - :guilabel:`Kenyan - Accounting` - - `l10n_ke` - - Installing this module grants you access to the list of accounts used in the local GAAP and - the list of common taxes (VAT, etc.). - * - :guilabel:`Kenyan - Accounting Reports` - - `l10n_ke_reports` - - Installing this module grants you access to improved accounting reports for Kenya, such as - Profit and Loss and Balance Sheets. +The `Kenya Revenue Authority (KRA) `_ has implemented the +`electronic Tax Invoice Management System (eTIMS) `_ +for tax collection. -You also have to install the **Kenya Tremol Device EDI Integration** package to be able to report -your taxes to the **Kenya Revenue Authority (KRA)** using the Tremol G03 Control Unit: - -.. list-table:: - :header-rows: 1 - - * - Name - - Technical name - - Description - * - :guilabel:`Kenya Tremol Device EDI Integration` - - `l10n_ke_edi_tremol` - - Installing this module integrates with the Kenyan G03 Tremol control unit device to report - taxes to KRA through TIMS. - -.. image:: kenya/modules.png - :align: center - :alt: The three modules for the Kenya Fiscal Localization Package on Odoo - -Kenyan TIMS integration -======================= - -The Kenya Revenue Authority (KRA) has decided to go digital for tax collection through the **Tax -Invoice Management System (TIMS)**. As of December 1st, 2022, all VAT-registered persons should -comply with TIMS. The goal is to reduce VAT fraud, increase tax revenue, and increase VAT compliance -through standardization, validation, and transmission of invoices to KRA on a real-time or near -real-time basis. - -All VAT-registered taxpayers should use a **compliant tax register**. Odoo decided to develop the -integration of the **Tremol G03 Control Unit (type C)**, which can be run locally through USB. This -device validates invoices to ensure financial documents meet the new regulations and send the -validated tax invoices directly to KRA. Installing a proxy server that provides a gateway between -users and the internet is required. - -Installing the proxy server on a Windows device ------------------------------------------------ - -Go to `odoo.com/download `_, fill out the required information -and click :guilabel:`Download`. - -.. image:: kenya/download.png - :align: center - :alt: Install the Proxy Server on a Windows device - -Once it is loaded on your computer, a wizard opens. You have to read and agree with the terms of the -agreement. On the next page, select the :guilabel:`type of install: Odoo IoT`. Then, click -:guilabel:`Next` and :guilabel:`Install`. Once completed, click :guilabel:`Next`. Check the -:guilabel:`Start Odoo` box to be redirected to Odoo automatically, and then click :guilabel:`Finish`. - -A new page opens, confirming your :doc:`IoT Box <../../general/iot/config/connect>` is up and -running. Connect your physical device **Tremol G03 Control Unit (type C)** to your laptop via USB. -In the :guilabel:`IoT Device` section, check that your Tremol G03 Control Unit (type C) appears, -confirming the connection between the device and your computer. - -.. image:: kenya/iot-box.png - :align: center - :alt: Your IoT box is up and running +To submit documents through eTIMS, you must use an :abbr:`OSCU (Online Sales Control Unit)` that +integrates with the existing **Trader Invoicing System (TIS)**, such as the one provided by Odoo. +The OSCU is used to validate, encrypt, sign, transmit, and store tax invoices. .. note:: - If the device is not detected, try to plug it in again or click on the :guilabel:`Restart` button - in the top right corner. + Make sure to :ref:`install ` the **Kenya eTIMS EDI** modules to use the OSCU + device fully. + +.. _kenya/initialization: + +OSCU device initialization +-------------------------- + +The OSCU must be initialized before use. To do so, navigate to :menuselection:`Settings --> General +Settings`, click :guilabel:`Update Info` in the :guilabel:`Companies` section, and enter your +:guilabel:`Tax ID`. + +To initialize the OSCU: + +#. Go to the :guilabel:`eTIMS` tab. +#. Fill in the :guilabel:`eTIMS Branch Code` and :guilabel:`Serial Number` of the device. +#. Set the :guilabel:`eTIMS Server Mode` to :guilabel:`Test` for the initialization. +#. Tick the **user agreement** and click :guilabel:`Initialize OSCU`. + +.. note:: + Three server modes are available: + + - :guilabel:`Demo`: Designed for demo purposes; it uses mock data and does not require an + initialized OSCU; + - :guilabel:`Test`: Used to test the connection to eTIMS; + - :guilabel:`Production`: Used for live databases that are ready to send data. + +.. Important:: + If your device has **already been initialized** (through another ERP, for example), enable the + :doc:`../../general/developer_mode`, go to the :guilabel:`eTIMS` tab, and enter the key + obtained through a previous initialization in the :guilabel:`Device Communication Key` field. + Click :guilabel:`Save manually`, then :guilabel:`Initialize OSCU` (which may take a moment to + become available). + +eTIMS codes +----------- + +Common standard codes are **automatically** fetched from the KRA eTIMS API servers every two days. +To fetch them manually, proceed as follows: + +#. Enable the :doc:`../../general/developer_mode`. +#. Go to :menuselection:`Settings --> Technical --> Automation: Scheduled Actions` and search for + :guilabel:`KE eTIMS: Fetch KRA standard codes`. +#. Click the action in the list, then click :guilabel:`Run Manually` to fetch the codes. + +Go to :menuselection:`Accounting --> Vendors --> KE OSCU Codes` to view the complete list of +fetched OSCU codes. + +.. image:: kenya/oscu-codes.png + :alt: List of fetched OSCU codes. + +.. _etims/unspsc: + +UNSPSC codes +------------ + +The KRA needs UNSPSC codes for a product to be **registered**. UNSPSC codes are **automatically** +fetched from the KRA eTIMS API servers every day. To fetch them manually, proceed as follows: + +#. Enable the :doc:`../../general/developer_mode`. +#. Go to :menuselection:`Settings --> Technical --> Automation: Scheduled Actions` and search for + :guilabel:`KE eTIMS: Fetch UNSPSC codes from eTIMS`. +#. Click the action in the list, then click :guilabel:`Run Manually` to fetch the codes. + +Go to :menuselection:`Accounting --> Vendors --> KE UNSPSC Codes` to view the complete list of +fetched UNSPSC codes. + +Notices +------- + +Notices are **automatically** fetched from the KRA eTIMS API servers every day. To fetch them +**manually**, proceed as follows: + +#. Enable the :doc:`../../general/developer_mode`. +#. Go to :menuselection:`Settings --> Technical --> Automation: Scheduled Actions` and search for + :guilabel:`KE eTIMS: Fetch KRA notices from eTIMS`. +#. Click the action in the list, then click :guilabel:`Run Manually` to fetch the notices. + +Go to :menuselection:`Accounting --> Vendors --> KE OSCU Notices` to view the complete list of +fetched notices. + +Multi-company +------------- + +.. _kenya/branch: .. seealso:: - :doc:`Connect an IoT box to your database <../../general/iot/config/connect>` + :doc:`../../general/companies` -Sending the data to KRA using the Tremol G03 Control Unit ---------------------------------------------------------- +If you have :ref:`multiple companies `, you can centralize and manage them +all on a single Odoo database. The KRA identifies and differentiates the **main** company from +its **subsidiaries** by using IDs. Furthermore, subsidiaries are classified as **branches** of the +main company. -As a pre-requisite, check out that the :ref:`Kenyan Accounting modules -` are installed on your database. Then, go to -:menuselection:`Accounting --> Configuration --> Settings --> Kenya TIMS Integration section`, and -check that the :guilabel:`control Unit Proxy Address` matches the address of the IoT box. +To configure the company ID, open the **Settings** app, click :guilabel:`Update Info` in the +:guilabel:`Companies` section, then click the :guilabel:`eTIMS` tab. The **main company** has a +branch ID equal to `00` in a multi-company environment. Companies that are *not* the main company +have a branch ID other than `00` and are assigned an ID by the KRA. -To send data to KRA, create a new invoice by going to :menuselection:`Accounting Dashboard --> -Customer Invoice card` and clicking :guilabel:`New Invoice`. Upon confirmation of a new invoice, the -:guilabel:`Send invoice to Fiscal Device` button appears. Clicking on it sends the invoice details -to the device and from the device to the government. The :guilabel:`CU Invoice Number` field is now -completed in your invoice, confirming the information has been sent. +To add a branch, go to the :guilabel:`Branches` tab in the **company settings** and click +:guilabel:`Add a line`. -The :guilabel:`Tremol G03 Fiscal Device` tab contains fields that are automatically completed once -the invoice is sent to the government: - -- :guilabel:`CU QR Code`: Url from the KRA portal which reflects a QR code. -- :guilabel:`CU Serial Number`: reflects the serial number of the device. -- :guilabel:`CU Signing Date and Time`: The date and time when the invoice has been sent to KRA. - -If you click on :guilabel:`Send and Print`, a .pdf of the invoice is generated. The -:guilabel:`Kenyan Fiscal Device Info` is mentioned on the document. +To fetch the **branch ID** from the KRA for your non-main companies, ensure the main company has a +Kenyan :guilabel:`Tax ID` and the OSCU device has been :ref:`initialized `. +Then, go to the :guilabel:`Branches` tab and click :guilabel:`Populate from KRA`. .. note:: - To verify KRA has received the invoice information, take the :guilabel:`CU Invoice Number` and - enter it in the :guilabel:`Invoice Number Checker` section on - `Kenya Revenue Authority website `_. Click - :guilabel:`Validate` and find the invoice details. + - The KRA considers each **place of supply** as a separate branch (ID). + - The **OSCU** device must be :ref:`initialized independently ` for each + branch. + +.. image:: kenya/branches.png + :alt: "Populate from KRA" button for branches. + +Contact branch ID +----------------- + +To attribute a branch ID to a contact, access the contact form, go to the :guilabel:`Accounting` +tab, and enter the branch code in the :guilabel:`eTIMS Branch Code` field. + +.. note:: + By default, contacts' branch IDs are set to `OO`. + +KRA sequences +------------- + +.. important:: + Odoo invoice sequences and KRA sequences are **different**. + +In Odoo, invoice sequences depend on the **main company**. Main companies can see the invoices of +branches, but branches **cannot** see the main company's invoices or those of other branches. + +The KRA needs **independent** sequences per branch. Therefore, Odoo manages sequences individually +per branch. + +.. example:: + If you have a main company with two branches, the invoice sequence would be the following: + + - Creating an invoice on **branch 1**: INV/2024/00001; + - Creating an invoice on **branch 2**: INV/2024/00002; + - Creating an invoice on the **main company**: INV/2024/00003. + + This is how Odoo manages sequences to be compliant with the KRA regulations: + + - Creating an invoice on **branch 1**: INV/2024/00001; + - Creating an invoice on **branch 2**: INV/2024/00001; + - Creating an invoice on the **main company**: INV/2024/00001. + +Insurance +========= + +For **health service providers**, you can send insurance information about the main and branch +companies and update it in eTIMS. To do so, open the **Settings** app, click :guilabel:`Update Info` +in the :guilabel:`Companies` section, and in the :guilabel:`eTIMS` tab, fill in the fields related +to your company: :guilabel:`Insurance Code`, :guilabel:`Insurance Name`, and :guilabel:`Insurance +Rate`. + +.. _kenya/product-registration: + +Product registration +==================== + +The KRA requires **products to be registered** first before conducting business operations (such as +stock movements, :abbr:`BOM (Bill of Materials)`, customer invoices, etc.). For a product to be +registered, the following fields must be defined on the product form: + +- In the :guilabel:`General Information` tab: :guilabel:`Cost`. +- In the :guilabel:`Accounting` tab: + + - :guilabel:`Packaging Unit`; + - :guilabel:`Packaging Quantity`; + - :guilabel:`Origin Country`; + - :guilabel:`eTIMS Product Type`; + - :guilabel:`Insurance Applicable`; + - :ref:`UNSPSC Category `. + +If the elements above are defined, the product is automatically registered while sending the +operation to the KRA. If not, you will be alerted by a yellow banner at the top of the screen +inviting you to check the missing elements. + +.. image:: kenya/product-registration.png + :alt: Product registration template. + +Stock movements +=============== + +All **stock movements** must be sent to the KRA. They do not require an invoice if they are +internal operations or stock adjustments; therefore, Odoo automatically sends them if at least one +of the following conditions are met: + +#. No contact is set for the move; +#. The contact is your main company or a branch of the main company. + +If the stock moves are **external operations** (e.g., to contacts that are not part of the main +company or its branches), the stock moves are automatically sent *after* the invoice is sent to +eTIMS. + +.. note:: + - The stock move must be confirmed before sending the invoice to eTIMS. + - The product(s) must be :ref:`registered ` for the stock move to be + sent to eTIMS. If the product has not been registered yet, a yellow banner will prompt the + products' registration. + +Purchases +========= + +Odoo automatically fetches new vendor bills from eTIMS every day. You need to confirm the fetched +vendor bills and send the confirmation to the KRA. To confirm a vendor bill, it must be linked to +one or several confirmed purchase order line(s). + +.. _kenya/purchases: + +In the case of purchases (not customs imports), the steps to link purchase order lines with bills +are the following: + +#. Go to :menuselection:`Accounting --> Vendors --> Bills`. + The vendor bill is fetched from the KRA servers. The JSON file is available in the chatter of the + vendor bill if needed. +#. Odoo looks at the :guilabel:`Tax ID` (PIN) of the vendor (partner); + + - If it is unknown, a new contact (partner) is created. + - If it is known and the branch ID is the same, Odoo uses the known contact. + +#. In the fetched bill from the KRA, select the :guilabel:`Product`. Each vendor bill *must* contain + a product to be confirmed and sent to eTIMS later on. +#. Odoo checks existing purchase order lines matching the product(s) entered at the previous step + and the partner (if any). Click the :guilabel:`Purchase Order Line` field, and select the correct + related purchase order line(s) matching the product(s). The quantities on the bill *must* be the + same as the received quantities indicated on the purchase order. + + If no existing purchase order line matches the lines of the fetched bill, click + :guilabel:`Create Purchase Order` and create a purchase order based on the unmatched line(s). + :guilabel:`Validate` the resulting stock move and :guilabel:`Confirm` the bill. + +#. Set a method in the :guilabel:`eTIMS Payment Method` field.. +#. Once all steps are completed, click :guilabel:`Send to eTIMS` to send the vendor bill. When the + vendor bill has been confirmed on eTIMS, the **KRA invoice number** can be found in the + :guilabel:`eTIMS Details` tab. + +.. image:: kenya/purchase-order-lines.png + :alt: Bill registration steps. + +Invoicing +========= + +.. note:: + The KRA does *not* accept sales if the product is not in stock. + +This is the **advised sales flow** in Odoo when selling: + +#. Create a **sales order**. +#. :guilabel:`Validate` the delivery. +#. :guilabel:`Confirm` the invoice. +#. Click :guilabel:`Send and print`, and then enable :guilabel:`Send to eTIMS`. +#. Click :guilabel:`Send & print` to send the invoice. + +Once the invoice has been sent and signed by the KRA, the following information can be found on +it: + +- **KRA invoice number**; +- Mandatory KRA invoice fields, such as **SCU information**, **date**, **SCU ID**, **receipt + number**, **item count**, **internal date**, and **receipt signature**; +- The **KRA tax table**; +- A unique **KRA QR code** for the signed invoice. + +Imports +======= + +Customs import codes are **automatically** fetched from the KRA eTIMS API servers every day. To +fetch them manually, proceed as follows: + +#. Enable the :doc:`../../general/developer_mode`. +#. Go to :menuselection:`Settings --> Technical --> Automation: Scheduled Actions` and search for + :guilabel:`KE eTIMS: Receive Customs Imports from the OSCU`. +#. Click the action in the list, then click :guilabel:`Run Manually` to fetch the codes. + +Go to :menuselection:`Accounting --> Vendors --> Customs Imports` to view the imported codes. + +The following steps are required to send and have **customs imports** signed by the KRA: + +#. Go to :menuselection:`Accounting --> Vendors --> Customs Imports`; The customs import is fetched + automatically from the KRA. +#. Match the imported item with an existing registered product in the :guilabel:`Product` field (or + create a product if no related product exists). +#. Set a vendor in the :guilabel:`Partner` field. +#. Based on the partner, match the imported item with its related purchase order (see + :ref:`purchase steps `). The stock must be correctly adjusted when the customs + import is approved. + + If no related purchase order exists, create one and :guilabel:`Confirm` it. Then, confirm the + delivery by clicking :guilabel:`Receive Products`, then :guilabel:`Validate` on the purchase + order. + +#. Click :guilabel:`Match and Approve` or :guilabel:`Match and Reject`, depending on the + situation of the goods. + +.. note:: + The JSON file received from the KRA is attached to the chatter of the customs import. + +BOM +=== + +The KRA requires all BOMs to be sent to them. To send BOMs to eTIMS, the product and its components +*must* be :ref:`registered `. To access a product's BOM, click on the +product and then click the :guilabel:`Bill of Materials` smart button. + +Fill in the KRA's required fields in the :guilabel:`KRA eTIMS details` section of the +:guilabel:`Accounting` tab, then click :guilabel:`Send to eTIMS`. The successful sending of the +BOM is confirmed in the chatter, where you can also find the sent information in an attached JSON +file. + +Credit notes +============ + +The KRA does not accept credit notes with quantities or prices higher than the initial invoice. When +reversing the invoice, a KRA reason must be indicated: in the credit note form, go to the +:guilabel:`eTIMS Details` tab, select the :guilabel:`eTIMS Credit Note Reason`, and then select the +invoice number in the :guilabel:`Reversal of` field. diff --git a/content/applications/finance/fiscal_localizations/kenya/branches.png b/content/applications/finance/fiscal_localizations/kenya/branches.png new file mode 100644 index 000000000..8d2b21360 Binary files /dev/null and b/content/applications/finance/fiscal_localizations/kenya/branches.png differ diff --git a/content/applications/finance/fiscal_localizations/kenya/download.png b/content/applications/finance/fiscal_localizations/kenya/download.png deleted file mode 100644 index 8e9c17f95..000000000 Binary files a/content/applications/finance/fiscal_localizations/kenya/download.png and /dev/null differ diff --git a/content/applications/finance/fiscal_localizations/kenya/iot-box.png b/content/applications/finance/fiscal_localizations/kenya/iot-box.png deleted file mode 100644 index 768f7926f..000000000 Binary files a/content/applications/finance/fiscal_localizations/kenya/iot-box.png and /dev/null differ diff --git a/content/applications/finance/fiscal_localizations/kenya/modules.png b/content/applications/finance/fiscal_localizations/kenya/modules.png deleted file mode 100644 index e744df2de..000000000 Binary files a/content/applications/finance/fiscal_localizations/kenya/modules.png and /dev/null differ diff --git a/content/applications/finance/fiscal_localizations/kenya/oscu-codes.png b/content/applications/finance/fiscal_localizations/kenya/oscu-codes.png new file mode 100644 index 000000000..fb4c66a98 Binary files /dev/null and b/content/applications/finance/fiscal_localizations/kenya/oscu-codes.png differ diff --git a/content/applications/finance/fiscal_localizations/kenya/product-registration.png b/content/applications/finance/fiscal_localizations/kenya/product-registration.png new file mode 100644 index 000000000..b0cafa111 Binary files /dev/null and b/content/applications/finance/fiscal_localizations/kenya/product-registration.png differ diff --git a/content/applications/finance/fiscal_localizations/kenya/purchase-order-lines.png b/content/applications/finance/fiscal_localizations/kenya/purchase-order-lines.png new file mode 100644 index 000000000..97b2d3220 Binary files /dev/null and b/content/applications/finance/fiscal_localizations/kenya/purchase-order-lines.png differ