[IMP] accounting/l10n_ar: purchase withholding automation

Add new section Withholding Management
Content based on v18

closes odoo/documentation#11770

Signed-off-by: Samuel Lieber (sali) <sali@odoo.com>
Co-authored-by: Liz Bender (beli) <beli@odoo.com>
Co-authored-by: samueljlieber <sali@odoo.com>
Co-authored-by: dade-odoo <87431108+dade-odoo@users.noreply.github.com>

content/applications/finance/fiscal_localizations/argentina.rst

@@ -48,6 +48,9 @@ localization:
      - `l10n_ar_website_sale`
      - (optional) Allows the user to see Identification Type and AFIP Responsibility in the
        eCommerce checkout form in order to create electronic invoices.
+   * - :ref:`Argentina - Payment Withholdings <l10n_ar/payment-withholdings>`
+     - `l10n_ar_withholding`
+     - Allows registering withholdings during the payment of an invoice.
 
 .. _argentina/configure-your-company:
 
@@ -681,6 +684,147 @@ the invoice can then be validated.
    :align: center
    :alt: Enter the perception amount.
 
+.. _l10n_ar/payment-withholdings:
+
+Withholding management
+----------------------
+
+The Argentinean fiscal localization module is already loaded with the necessary withholdings
+records, which can be seen by navigating to :menuselection:`Accounting app --> Configuration -->
+Taxes` and removing the default :guilabel:`Sale or Purchase` filter. To verify these records, the
+**Argentina Payment Withholdings** (`l10n_ar_withholding`) module must be :ref:`installed
+<general/install>`:
+
+Journal entries are *not* created when payments are posted unless :ref:`outstanding accounts
+<accounting/bank/outstanding-accounts>` are set up. Thus, for this feature to work properly, it is
+important to verify that *all* payment methods within the bank journals have an outstanding payment
+and receipt account set.
+
+.. image:: argentina/l10n-ar-outstanding-payments.png
+   :alt: An outstanding payment account must be set.
+
+This configuration is crucial for the proper accounting of withholding transactions with clients
+and vendors.
+
+.. note::
+   In Argentina, withholdings represent the cancellation of a specific portion of the total debt
+   owed to a supplier or a reduction in the total payment to be collected from a customer.
+   Therefore, one or multiple withholdings can be recorded for each payment applied to an invoice.
+
+Configuration
+~~~~~~~~~~~~~
+
+While Odoo already creates most of the required withholdings inside the :guilabel:`Taxes`
+menu, in several cases, it is necessary to apply or modify certain configurations to correctly
+calculate the withholding amount on vendor payments. The following withholding types are available:
+
+- :ref:`Earnings <l10n_ar/earnings-withholdings>`
+- :ref:`Earnings Scale <l10n_ar/earnings-scale-withholdings>`
+- :ref:`IIBB Total Amount <l10n_ar/iib-total-amount-withholdings>`
+- :ref:`IIBB Non-Taxable <l10n_ar/iib-nontax-withholdings>`
+
+.. _l10n_ar/earnings-withholdings:
+
+Earnings
+********
+
+For :guilabel:`Earnings` withholdings, Odoo already has a record for each regime group, which is
+stated under the name of the tax and the AFIP code.
+
+Each of these records are ready to be used. As a good practice, the configuration should be double
+checked to make sure the configuration is updated and well-applied. The fields to validate are:
+
+- :guilabel:`Amount`: This is the percentage of the total payment amount which is withheld.
+- :guilabel:`Non-Taxable Amount`: Up to this amount, the withholding does not apply.
+- :guilabel:`Minimum Withholding`: If the calculated withholding amount is smaller than this value,
+  the total withholding amount is set to `0.0`.
+- :guilabel:`Withholding Sequence`: This field helps to automate the capture of a withholding number
+  under the payment line. If this field is not set, a number is manually captured while adding a
+  withholding to a payment.
+
+.. image:: argentina/l10n-ar-earnings.png
+   :alt: Earnings withholding type.
+
+.. _l10n_ar/earnings-scale-withholdings:
+
+Earnings Scale
+**************
+
+In this particular case, a percentage does not need to be set. Instead, this withholding is
+calculated based on the value of the :guilabel:`Scale` field.
+
+To view, modify, or create new scales, navigate to :menuselection:`Accounting app --> Configuration
+--> Earnings Scale`. By default, the Argentinian localization is preconfigured with two main scales.
+However, scales should be created and updated as necessary to suit a business's needs.
+
+.. note::
+   Earnings scales are cumulative, which means that Odoo keeps track of the different records
+   created for a bill and automatically calculates the proper withholding amount.
+
+.. _l10n_ar/iib-total-amount-withholdings:
+
+IIBB Total Amount
+*****************
+
+In this case, the necessary records related to the applicable province need to be created. The
+withholding amount is calculated based on the percentage :guilabel:`Amount` set on the tax
+configuration. Since Odoo does not automatically synchronize the percentages applicable to each
+province, this information needs to be manually updated.
+
+The recommendation, in this case, is to always duplicate and apply the different configurations for
+each record to safeguard any technical configurations that allow the proper calculation and
+accounting of the withholding.
+
+.. _l10n_ar/iib-nontax-withholdings:
+
+IIBB Untaxed
+************
+
+The configuration of non-taxable gross income withholdings is very similar to that of a :ref:`total
+amount withholding <l10n_ar/iib-total-amount-withholdings>`, so the percentage :guilabel:`Amount` in
+each of the records needs to be maintained. However, Odoo comes preconfigured with several records
+that apply to different provinces. The difference, in this case, is that it is not necessary to
+establish a non-taxable amount or minimum withholding for this record type.
+
+Partner withholding assignation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the proper configuration is set on each possible withholding for partners, the applicable
+withholdings need to be assigned to each contact. To do this, open the :guilabel:`Contacts` app and
+select the desired partner. In the :guilabel:`Accounting` tab, find the :guilabel:`Purchase
+Withholdings` table.
+
+By using the additional fields :guilabel:`From Date` and :guilabel:`To Date`, the applicability of
+multiple withholdings can be automated across different date ranges. The :guilabel:`ref` field
+allows you to apply an internal control number to each withholding line, which is just for internal
+reference, so it does not affect any transactions and is not visible on them. These fields are
+accessible from the :icon:`oi-settings-adjust` :guilabel:`(adjust settings)` menu.
+
+- :guilabel:`From Date`: the start of the withholding date range.
+- :guilabel:`To Date`: the end of the withholding date range.
+- :guilabel:`ref`: apply an internal control number to each withholding line that is only visible
+  for internal reference and does not affect any transactions.
+
+Automatic withholding calculation and application per payment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By applying new payments to vendor bills, Odoo automatically applies and calculates the proper
+withholding into the payment. Based on the record's configuration, it may be necessary to use a
+reference number for each withholding line.
+
+More withholdings can be added, or computed withholdings can be edited if necessary.
+
+.. image:: argentina/l10n-ar-payment.png
+   :alt: Payment with applied withholdings.
+
+.. important::
+   The total amount of the debt to be canceled is the total amount of the payment. However, Odoo
+   still captures the net amount (i.e. the amount to be reconciled with the bank), which will be
+   represented as the payment amount after the withholding application.
+
+   .. image:: argentina/l10n-ar-payment-registered.png
+      :alt: Payment registered form.
+
 Check management
 ----------------