[ADD] Payroll: Turkey localization

Author: larm-odoo

content/applications/hr/payroll/payroll_localizations.rst

@@ -91,7 +91,7 @@ Payroll localization modules are available for the countries listed below.
 - :doc:`Saudi Arabia <payroll_localizations/saudi_arabia>`
 - Slovakia
 - Switzerland
-- Türkiye
+- :doc:`Türkiye <payroll_localizations/turkey>`
 - :doc:`United Arab Emirates <payroll_localizations/united_arab_emirates>`
 - :doc:`United States <payroll_localizations/united_states>`
 
@@ -105,6 +105,7 @@ Payroll localization modules are available for the countries listed below.
    payroll_localizations/jordan
    payroll_localizations/mexico
    payroll_localizations/saudi_arabia
+   payroll_localizations/turkey
    payroll_localizations/united_arab_emirates
    payroll_localizations/united_states
    payroll_localizations/employment_hero

content/applications/hr/payroll/payroll_localizations/turkey.rst

@@ -0,0 +1,329 @@
+=======
+Türkiye
+=======
+
+The Türkiye payroll localization covers salary computations for employees, including both employee
+and employer payroll taxes. It accounts for federal and state regulations.
+
+Before configuring the Türkiye localization, refer to the general :doc:`payroll <../../payroll>`
+documentation, which includes the basic information for all localizations, as well as all universal
+settings and fields.
+
+.. _payroll/turkey_apps:
+
+Apps & modules
+==============
+
+:ref:`Install <general/install>` the following modules to get all the features of the Türkiye payroll
+localization:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Technical name
+     - Dependencies
+     - Description
+   * - :guilabel:`Türkiye - Payroll`
+     - `l10n_tr_hr_payroll`
+     - - hr_payroll
+     - Includes all salary rules, leave logic, and compensation rules compliant with Türkiye labor
+       laws.
+   * - :guilabel:`Türkiye - Payroll with Accounting`
+     - `l10n_tr_hr_payroll_account`
+     - - hr_payroll_account
+       - l10n_tr_hr_payroll_account
+       - l10n_tr_hr_payroll
+     - Links payroll and accounting by creating journal entries (per payslip if needed) to record
+       payroll in the company's books.
+
+.. seealso::
+   :doc:`Configure the Türkiye fiscal localization
+   <../../../finance/fiscal_localizations/turkey>`
+
+General configurations
+======================
+
+First, the company must be configured. Navigate to :menuselection:`Settings app --> Users &
+Companies --> Companies`. From the list, select the desired company, and configure the following
+fields:
+
+- :guilabel:`Company Name`: Enter the business name in this field.
+- :guilabel:`Address`: Complete the full address, including the :guilabel:`City`, :guilabel:`State`,
+  :guilabel:`ZIP`, and :guilabel:`Country`.
+- :guilabel:`Tax ID`: Enter the company's tax ID.
+- :guilabel:`Company ID` : Enter the business's ID number.
+- :guilabel:`Currency`: By default, :abbr:`TRY (Turkish lira)` is selected. If not, select
+  :guilabel:`TRY` from the drop-down menu.
+- :guilabel:`Phone`: Enter the company phone number.
+- :guilabel:`Email`: Enter the email used for general contact information.
+
+Employees
+=========
+
+Every employee being paid must have their employee profiles configured for the Türkiye payroll
+localization. Additional fields are present after configuring the database for Türkiye.
+
+To update an employee form, open the :menuselection:`Employees` app and click on the desired
+employee record. On the employee form, configure the required fields in the related tabs.
+
+Work tab
+--------
+
+Enter the :guilabel:`Work Address` for the employee in the :guilabel:`Location` section of the
+:guilabel:`Work` tab.
+
+Personal tab
+------------
+
+Ensure the employee has a minimum of one :ref:`trusted bank account <employees/private-contact>`
+listed in the :guilabel:`Bank Accounts` field in the :guilabel:`Private Contact` section.
+
+These accounts are used to pay the employee. Payroll **cannot** be processed for employees without a
+*trusted* :ref:`bank account <employees/private-contact>`. If no trusted bank account is set, a
+warning appears on the **Payroll** dashboard and an error occurs when attempting to run payroll.
+
+Payroll tab
+-----------
+
+Contract overview section
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section holds information that drives salary calculations. Ensure the following fields are
+configured:
+
+- :guilabel:`Contract`: Ensure a contract start date is entered in the first field.
+- :guilabel:`Wage Type`: Select how the employee is paid.
+
+  - Select :guilabel:`Fixed Wage` for salaried employees who receive the same amount each pay
+    period.
+  - Select :guilabel:`Hourly Wage` for employees paid based on hours worked.
+
+  .. tip::
+     Set a default :guilabel:`Wage Type` in the salary :ref:`Structure Type
+     <payroll/structure-types>` to configure employees in bulk. If needed, the default can be
+     overridden on individual employee records if exceptions are needed.
+
+- :guilabel:`Net to Gross`: Tick this checkbox if the gross salary is calculated based on the net
+  salary.
+- :guilabel:`Contract Type`: Determines how the employee is paid and classified, such as
+  :guilabel:`Permanent`, :guilabel:`Temporary`, or :guilabel:`Student`.
+- :guilabel:`Pay Category`: Select :guilabel:`Türkiye: Employee` for this field. This defines
+  when the employee is paid, their default working schedule, and the work entry type it applies to.
+
+.. image:: turkey/contract-tr.png
+   :alt: The contract overview section of the employee form of the payroll tab.
+
+Schedule section
+~~~~~~~~~~~~~~~~
+
+- :guilabel:`Work Entry Source`: Defines how :doc:`work entries <../work_entries>` are generated for
+  payroll during the specified pay period. The options are:
+
+  - :guilabel:`Working Schedule`: Based on the employee's assigned :ref:`working schedule
+    <employees/schedule>` (e.g., 40 hours per week).
+  - :guilabel:`Attendances`: Based on :doc:`approved checked-in hours
+    <../../attendances/management>` in the **Attendances** app.
+  - :guilabel:`Planning`: Based on :ref:`scheduled shifts <planning/shifts>` in the **Planning**
+    app.
+
+- :guilabel:`Working Hours`: Using the drop-down menu, select the default work schedule. This is
+  particularly important for employees available to receive overtime pay (typically hourly
+  employees, not salaried).
+
+Payroll configuration
+=====================
+
+Several sections within the **Payroll** app installs a Salary Structure, Structure Type, Rules, and
+Parameters specific to the Türkiye.
+
+Salary structures & structure types
+-----------------------------------
+
+When the **l10n_us_tr_payroll** module is :ref:`installed <payroll/turkey_apps>`, a new
+:guilabel:`Salary Structure` gets installed, :guilabel:`Türkiye: Regular Pay`. This structure
+includes one :guilabel:`Structure Type`, :guilabel:`Türkiye: Employee`.
+
+The :guilabel:`Salary Structure` contains all the individual :ref:`salary rules
+<payroll/turkey_apps>` that informs the **Payroll** app how to calculate employee payslips.
+
+.. image:: turkey/structure-types-tr.png
+   :alt: The Türkiye salary structure in the salary structures list.
+
+.. _payroll/turkey_rules:
+
+Salary rules
+------------
+
+To view the salary rules that inform the salary structure what to do, navigate to
+:menuselection:`Payroll app --> Configuration --> Structures` and expand the :guilabel:`Türkiye:
+Employee` group to reveal the :guilabel:`Türkiye: Monthly Pay` structure type. Click
+:guilabel:`Türkiye: Monthly Pay` to view the detailed salary rules.
+
+.. image:: turkey/tr-rules-top-half.png
+   :alt: The top portion of the Türkiye salary rules.
+
+Each rule defines how pay is calculated, taking into account factors such as commissions, bonuses,
+taxes, and insurance.
+
+Rule parameters
+---------------
+
+Some calculations require specific rates associated with them, or wage caps. *Rules Parameters* are
+capable of listing a value, either a percentage or a fixed amount, to reference in the salary rules.
+
+.. example::
+   The wage base for Social Security tax calculations has a cap for 2025, accounted for in the `US:
+   FICA OASDI Cap` parameter.
+
+Most rules pull information stored in the parameters module to get the rate of the rule (a
+percentage) and the cap (a dollar amount).
+
+To view rule parameters, navigate to :menuselection:`Payroll app --> Configuration --> Rule
+Parameters`. Here, all rule parameters are displayed with their linked :guilabel:`Salary Rules`,
+which can be accessed. Review the parameters associated with a rule by looking for the
+:guilabel:`Name` of the rule, and make any edits as needed.
+
+.. example::
+   The Unemployment tax of a company is different from the one added by default in Odoo. To update
+   this, navigate to :menuselection:`Payroll app --> Configuration --> Rule Parameters`, then,
+   filter the results by :abbr:`FUTA (Federal Unemployment Tax Act)`, or the name of the state that
+   needs editing, and edit the corresponding rate from the list.
+
+.. important::
+   Odoo adds updated rule parameters for the current calendar year. It is **not** recommended to
+   edit rule parameters **unless a federal or state parameter has changed**, and is different from
+   the rule parameters created by Odoo. Check with all local and national regulations *before*
+   making any changes to rule parameters.
+
+Run Türkiye payroll
+===================
+
+Before running payroll, the payroll officer must validate employee :doc:`work entries
+<../work_entries>` to confirm pay accuracy and catch errors. This includes checking that all time
+off is approved and any overtime is appropriate.
+
+Work entries sync based on the employee's :doc:`contract <../contracts>` configuration. Odoo pulls
+from the assigned working schedule, attendance records, planning schedule, and approved time off.
+
+Any :ref:`discrepencies or conflicts <payroll/conflicts>` must be resolved, then the work entries
+can be :ref:`regenerated <payroll/regenerate-work-entries>`.
+
+Once everything is correct, draft payslips can be :ref:`created individually <payroll/process>` or
+in :doc:`batches <../batches>`, referred to in the **Payroll** app as *Pay Runs*.
+
+.. image:: turkey/work-entries-tr.png
+   :alt: The work entries for a pay run, with some time off entered in the work entries.
+
+.. note::
+   To cut down on the payroll officer's time, it is typical to process payslips in batches, either
+   by wage type (fixed salary vs hourly), pay schedule (weekly, bi-weekly, monthly, etc.),
+   department (direct cost vs. administration), or any other grouping that best suits the company.
+
+The process of running payroll includes different actions that need to be executed to ensure that
+the amount withheld from payroll taxes is correct, the amount that the employee receives as their
+net salary is correct, and the computation of hours worked reflects the employee's actual hours
+worked, among others.
+
+When running a payroll batch, check that the period, company, and employees included are correct
+*before* starting to analyze or validate the data.
+
+Once the payslips are drafted, review them for accuracy. Check the :guilabel:`Worked Days & Inputs`
+tab, and ensure the listed worked time is correct, as well as any other inputs. Add any missing
+inputs, such as commissions, tips, reimbursements, that are missing.
+
+Next, check the various totals (gross pay, employee taxes, benefits, employer taxes, net salaries),
+then click :guilabel:`Compute Sheet` to update the salary calculations, if there were edits. If
+everything is correct, click :guilabel:`Validate`.
+
+.. image:: turkey/check-payslip-tr.png
+   :alt: The worked days tab of a payslip.
+
+Accounting check
+----------------
+
+The accounting process when running payroll has two components: :ref:`creating journal entries
+<payroll/journal>`, and :ref:`registering payments <payroll/register>`.
+
+.. _payroll/journal:
+
+Journal entry creation
+~~~~~~~~~~~~~~~~~~~~~~
+
+After payslips are confirmed and validated, journal entries are posted either individually, or in a
+batch. The journal entry is created first as a draft.
+
+.. important::
+   It must be decided if journal entries are done individually or in batches *before* running
+   payroll.
+
+.. image:: turkey/create-draft-entry.png
+   :alt: All payslips in a draft state.
+
+Four accounts from the US :abbr:`CoA (Chart of Accounts)` are included with the payroll
+localization:
+
+- `611000 Salaries & Wages`: Records gross salary and the employer's portion of payroll expenses.
+  Also groups values from rules without specific accounts (e.g., company-specific benefits).
+- `230100 Employee Payroll Taxes`: Withheld taxes from employees, which the employer must file and
+  pay. The partner and label columns of the journal entry indicate the specific tax.
+- `230200 Employer Payroll Taxes`: Employer portion of payroll taxes to be filed and paid. The
+  partner and label columns of the journal entry indicate the specific tax.
+- `230000 Salary Payable`: Net salary owed to the employee.
+
+.. note::
+   The :abbr:`CoA (Chart of Accounts)` configuration is done by default when a company is located in
+   the US. The account codes and names can be edited to suit the company's needs. If there is no
+   :abbr:`CoA (Chart of Accounts)` account associated with a salary rule (used in a salary
+   structure), Odoo uses the account `Salary Expenses` to create the journal entry, regardless of
+   the nature of the move.
+
+If everything seems correct on the journal entry draft, post the journal entries.
+
+.. image:: turkey/post-entries.png
+   :alt: Journal entries posted.
+
+.. _payroll/register:
+
+Register Payments
+-----------------
+
+After the :ref:`journal entries <payroll/journal>` are validated, Odoo can generate payments.
+
+.. important::
+   To generate payments from payslips,employee's **must** have a *trusted* bank account. If the
+   employee's bank account is *not* marked as `trusted`, NACHA files **cannot** be generated through
+   Odoo.
+
+Payments can be :guilabel:`Grouped by Partner` if there is a partner associated with a salary rule.
+
+.. image:: turkey/paid.png
+   :alt: Payslips with a status of paid.
+
+Close Payroll
+-------------
+
+If there are no errors, payroll is completed for the pay period.
+
+Reports
+=======
+
+The US localization contains several reports unique to the US, which provide tax information for
+employees, as well as the ability to integrate with outside organizations such as ADP.
+
+Export data to third-party apps
+-------------------------------
+
+The *ADP Export* report generates a CSV file that can be submitted to ADP, which then makes payments
+to the employees.
+
+The CSV file summarizes the employee's worked hours during a specified time period, correlating to
+their salary or hourly wage. The report is generated from :doc:`work entry <../work_entries>`
+*after* any time off is confirmed.
+
+The export format is meant to match with the ADP format. Since companies can customize their portal
+and may require some changes, the data is there to be fed to ADP to run payroll in it.
+
+.. important::
+   To access the ADP Export report, the `Türkiye - Payroll - Export to ADP` module **must** be
+   :ref:`installed <general/install>`.