[IMP]accounting: avatax api integration rewrite

content/applications/finance/accounting/taxes/avatax.rst

@@ -2,23 +2,146 @@
 Avatax integration
 ==================
 
-Avatax is a tax calculation provider that can be integrated in Odoo.
+Avalara's *AvaTax* is a cloud-based tax software that delivers the latest sales and use
+tax calculations to Odoo's sales and invoicing flow when the customer makes a purchase. *AvaTax* is
+supported in every United Nations charted country. This includes inter-boarder transactions as well.
+
+*AvaTax* accounts for geospatial tax rates for each state, county and city. It improves remittance
+accuracy by paying close attention to laws, rules, jurisdiction boundaries, and special
+circumstances like tax holidays and product exemptions. Companies who integrate with *AvaTax* can
+maintain control of tax-calculations in-house with this simple :abbr:`API (application programming
+interface)` integration.
+
+.. seealso::
+   Avalara's support documents: `About AvaTax
+   <https://community.avalara.com/support/s/document-item?language=en_US&bundleId=dqa1657870670369_dqa1657870670369&topicId=About_AvaTax.html&_LANG=enus>`_
+
+To use *AvaTax*, an account with Avalara is required for the setup. If one has not been set up yet,
+connect with Avalara to purchase a license: `Avalara: Let's Talk
+<https://www.avalara.com/us/en/get-started.html>`_
+
+.. important::
+   Note the Avatax :guilabel:`Account ID` as this will be needed in the :ref:`Odoo setup
+   <avatax/credentials>` later in the setup. This number will be used for the :guilabel:`API ID`.
+
+Set up Avatax (onboarding)
+==========================
+
+ First `create a basic company profile
+ <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Create_a_Basic_company_profile.html&_LANG=enus>`_.
+
+Create basic company profile
+----------------------------
+
+First, gather some key information about the business. Things that are necessary for the next step
+are: where the company collects tax, products and service that the company sells and where each is
+sold, and finally which customer are exempt from tax, if any.
+
+Follow the Avalara documentation for creating a basic company profile:
+
+# `Add your company information
+  <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Add_your_company_information.html&_LANG=enus>`_.
+# `Tell us where you collect and pay tax
+  <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Tell_us_where_you_collect_and_pay_tax.html&_LANG=enus>`_.
+# `Verify your jurisdictions and activate your company
+  <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Verify_your_jurisdictions_and_activate_your_company.html&_LANG=enus>`_.
+# `Add other company locations for location-based filing
+  <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Add_other_company_locations_for_location-based_filing.html&_LANG=enus>`_.
+# `Add a marketplace to your company profile
+  <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Add_marketplace_transactions_to_your_company_profile.html&_LANG=enus>`_.
+
+.. _avatax/create_avalara_credentials:
+
+Connect to AvaTax
+=================
+
+Following creating the basic company profile in Avalara, a connection to Avatax **must** be made.
+This step is necessary to connect Odoo to Avatax and vice-versa.
+
+Navigate to either Avalara's `sandbox <https://sandbox.admin.avalara.com/>`_ or `production
+<https://admin.avalara.com/>`_ environment. This will depend on which type of account was set up
+above.
+
+.. seealso::
+   Avalara's documentation on `sandbox vs production environments
+   https://knowledge.avalara.com/bundle/fzc1692293626742/page/sandbox-vs-production.html>`_.
+
+Login to create the :guilabel:`Licence Key`. Go to :menuselection:`Settings --> Licence and API
+Keys`. Click :guilabel:`Generate Licence Key`.
+
+A warning will display stating: `If your business app is connected to Avalara solutions, the
+connection will be broken until you update the app with the new license key. This action cannot be
+undone.`. Should this be the first :abbr:`API (application programming interface)` integration being
+made with AvaTax and Odoo, then click :guilabel:`Generate license key`.
+
+Should this be an additional license key then, ensure the previous connection can be broken. There
+is **only** one license key associated with the AvaTax/Avalara account.
+
+Copy this key to a safe spot. It is strongly encouraged to *download*, *print*, *copy and paste*, or
+*write* down the license key for future reference. This key is un-retrievable after leaving the
+screen.
+
+Initial Odoo setup
+==================
+
+Ensure that the company has data set up in the Odoo database. When the database or company is
+initially set up, a country is set. This country sets the fiscal position and helps *Avatax*
+calculate the correct tax rates.
+
+.. seealso::
+   Refer to this documentation for more information: :ref:`../fiscal_localizations` or
+   :ref:`fiscal_positions`.
+
+Next, ensure that the Odoo *Avatax* module is installed. To do so, navigate to :menuselection:`Apps
+application --> Search...` bar and then type in `avatax`. Press enter and the following results will
+populate:
+
+- :guilabel:`Avatax`: `account_avatax``
+- :guilabel:`Avatax for SO`: `account_avatax_sale`
+- :guilabel:`Avatax for Subscriptions`: `account_avatax_sale_subscription`
+- :guilabel:`Avatax Brazil`: `l10n_br_avatax`
+- :guilabel:`Avatax for SOs in Brazil`: `l10n_br_avatax_sale`
+- :guilabel:`Account Avatax - Ecommerce`: `website_sale_account_avatax`
+- :guilabel:`Account AvaTax - Ecommerce - Delivery`: `website_sale_delivery_avatax`
+
+Click on the :guilabel:`Install` button on the module labeled :guilabel:`Avatax`: `account_avatax`.
+This will install the following modules:
+
+- :guilabel:`Avatax`: `account_avatax``
+- :guilabel:`Avatax for SO`: `account_avatax_sale`
+- :guilabel:`Account Avatax - Ecommerce`: `website_sale_account_avatax`
+
+Should *Avatax* be needed for Odoo *Subscriptions* or for delivery tax in Odoo *Ecommerce*, then
+install those modules individually by clicking on :guilabel:`Install`. Additionally, in Brazil two
+separate *AvaTax* modules need to be installed. See the list above for these modules.
 
 .. _avatax/credentials:
 
-Credential configuration
-========================
+Credential configuration in Odoo
+================================
+
+To integrate the *Avatax* :abbr:`API (application programming interface)` with Odoo, go to
+:menuselection:`Accounting --> Configuration --> Settings --> Taxes --> Avatax` section. This where
+the *AvaTax* credentials will be entered in.
 
-To integrate Avatax with Odoo, go to :menuselection:`Accounting --> Configuration --> Settings -->
-Taxes` and add your Avatax credentials in the :guilabel:`Avatax` section.
+The Avatax :guilabel:`Account ID` will be the :guilabel:`API ID` and the :guilabel:`License Key`
+will be the :guilabel:`API Key`.
 
 .. tip::
-   If you do not yet have credentials, click on :guilabel:`How to Get Credentials`.
+   The :guilabel:`Account ID` can be found by logging into the AvaTax portal (`sandbox
+   <https://sandbox.admin.avalara.com/>`_ or `production <https://admin.avalara.com/>`_). In the
+   upper-right corner are the initials of the user and :guilabel:`Account`, click into this icon.
+   The :guilabel:`Account ID` is listed first.
 
 .. image:: avatax/avatax-configuration-settings.png
    :align: center
    :alt: Configure Avatax settings
 
+.. seealso::
+   For help determining which *AvaTax* environment to use (either :guilabel:`Production` or
+   :guilabel:`Sandbox`), visit: `Sandbox vs Production environments
+   <https://knowledge.avalara.com/bundle/fzc1692293626742/page/sandbox-vs-production.html>`_.
+
 .. _avatax/tax-mapping:
 
 Tax mapping