[IMP] amazon_connector: new authentication flow + add a marketplace

- How to install the update module
- How to generate an authorization token
- How to add an unsupported marketplace

sales/amazon_connector.rst

@@ -5,6 +5,6 @@ Amazon Connector
 .. toctree::
    :titlesonly:
 
-   amazon_connector/apply
    amazon_connector/setup
-   amazon_connector/manage
+   amazon_connector/manage
+   amazon_connector/update

sales/amazon_connector/apply.rst

@@ -1,10 +0,0 @@
-================================
-Apply for Amazon MWS Access Keys
-================================
-
-.. _amazon/developer-form:
-
-.. warning::
-   | The authentication mechanism that previously used MWS keys is no longer authorized by Amazon
-     and will soon be replaced by another flow.
-   | This page will be updated accordingly in the coming weeks.

sales/amazon_connector/setup.rst

@@ -2,16 +2,67 @@
 Configure Amazon Connector in Odoo
 ==================================
 
+Generate an Authorization Token in Seller Central
+=================================================
+
+.. _amazon/generate_auth_token:
+
+The Amazon Connector uses an Authorization Token that allows Odoo to fetch data from your Amazon
+Seller Central account. This token can be obtained directly through Seller Central in a few clicks
+and needs to be set up in your Odoo database configuration.
+
+Connect to your Seller Central account for the marketplace you initially signed
+up (e.g. if you created your account on Amazon Germany, go to `Amazon Seller
+Central for Germany <https://sellercentral.amazon.de>`_) with an administrator account.
+
+.. note::
+  You might need to use the *main* (or first) administrator account and not one
+  added subsequently.
+
+In the main menu, select :menuselection:`Apps & Services --> Manage Your Apps`;
+in the page that displays, click on the ``Authorize new developper`` button:
+
+.. image:: ./media/seller_central_apps.png
+  :align: center
+
+Fill in the form depending on your Marketplace:
+
+.. image:: ./media/seller_central_form.png
+  :align: center
+
+If your seller account is registered in the **North America** region, use these values:
+
+- Developer's Name: ``Odoo S.A.``
+- Developer ID: ``586127723692``
+
+For the **Europe** region, use these values:
+
+- Developer's Name: ``Odoo S.A.``
+- Developer ID: ``579095187166``
+
+Amazon will then inform you that by submitting the form, you are giving access
+to your Seller Central Information to Odoo S.A.
+
+.. note::
+    Odoo S.A. is unable to access your Amazon account's information without the
+    Authorization Token which is stored in your Odoo database - we do not store
+    these tokens on our platform directly and are therefore unable to access
+    your account's information outside of the Amazon Connector normal flows.
+
 Register your Amazon account in Odoo
 ====================================
 
+.. _amazon/setup:
+
 To register your seller account in Odoo, navigate to :menuselection:`Sales --> Configuration
 --> Settings --> Connectors --> Amazon Sync --> Amazon Accounts` and click on **CREATE**.
 
 The **Seller ID** can be found in Seller Central under the link **Your Merchant Token** on the
-**Seller Account Information** page. The **Access Key** and the **Secret Key** can be found in
+**Seller Account Information** page. The **Authorization Token** is the one you generated in the
-Developer Central (where the :ref:`Developer Registration and Assessment form
+:ref:`previous step <amazon/generate_auth_token>`.
-<amazon/developer-form>` was located).
+
+Upon saving, your credentials are checked. In case of issues, an error will be displayed - the
+information cannot be saved until your credentials are recognized by Amazon.
 
 Once the account is registered, the marketplaces available to this account are synchronized and
 listed under the **Marketplaces** tab. If you wish, you can remove some items from the list of
@@ -62,4 +113,46 @@ the subtotals between Seller Central and Odoo.
 .. note::
    As Amazon does not necessarily apply the same taxes as those configured in Odoo, it may happen
    that order totals differ by a few cents from that on Seller Central. Those differences can be
-   resolved with a write-off when reconciling the payments in Odoo.
+   resolved with a write-off when reconciling the payments in Odoo.
+
+Add an unsupported marketplace to the Amazon Connector
+======================================================
+
+Some Amazon Marketplaces, such as Amazon Brazil or Amazon Netherlands, are
+not included by default in the Amazon Connector list of possible marketplaces.
+
+These marketplaces can be added manually should you wish to use them.
+
+.. important::
+    These marketplaces are not officially supported by Odoo - there is no guarantee
+    that adding a new marketplace as described here will work, nor can this be considered
+    as a bug when contacting Odoo Support.
+
+.. note::
+    Amazon marketplaces are only supported in the European and North American region;
+    though Amazon includes Brazil with the North American region and India in the
+    European region, so your mileage may vary; check the `Amazon Documentation
+    <https://docs.developer.amazonservices.com/en_US/dev_guide/DG_Endpoints.html>`_
+    to know to which region your marketplace belongs.
+
+To add a new marketplace, you must first enable 
+:doc:`Developer mode <../../general/developer_mode/activate>`.
+
+Once that is done, go to :menuselection:`Sales --> Configuration --> Settings --> Connectors --> Amazon Sync -->
+Amazon Marketplaces`.
+
+From there, you can create a new marketplace record. You will need the Marketplace ID and Endpoint for your
+marketplace as described in the
+`Amazon Documentation <https://docs.developer.amazonservices.com/en_US/dev_guide/DG_Endpoints.html>`_.
+
+Set the name of the record to ``Amazon.<domain>`` to easily retrieve it. The **Code**, **Domain** and
+**API Identifier** fields should contain the *Country Code*, *Amazon MWS Endpoint* and *MarkteplaceId*
+values from the Amazon Documentation respectively.
+
+Once the marketplace is saved, you should then update the Amazon Account configuration by going to 
+:menuselection:`Sales --> Configuration --> Settings --> Connectors --> Amazon Sync --> Amazon Accounts`,
+open the account on which you wish to use the new marketplace, go to the **Marketplaces** tab and click
+on **Update available marketplaces** (an animation should confirm the success of the operation). You can then
+edit the Amazon Account to add the new marketplace in the list of synchronized marketplaces - if the new
+marketplace is not available in the list, it means it is either incompatible with the account's region or
+simply that it is not supported by the Amazon Connector.

sales/amazon_connector/update.rst

@@ -0,0 +1,70 @@
+==================================================
+Install the Amazon Connector Authentication Update
+==================================================
+
+Starting July 2020, the Amazon Connector requires the use of a new authentication
+method that makes it easier for you to set up the Connector.
+
+Prior to the update, Odoo customers who wished to use the Amazon Connector had
+to apply to get developer credentials through Amazon, which was a painful and long
+process that could take weeks. This method of authentication is still technically
+possible, but Amazon will refuse to provide developer credentials for Odoo customers
+from July 2020 onwards and will deactivate such credentials for existing customers.
+
+This documentation will help you install the update and use the new authentication
+flow.
+
+Note that if your Odoo database was first created after the update was released, the
+update module is installed automatically. You can check if this module is already installed
+by going to the  **Apps** menu, removing the ``Apps`` search facet and search for ``amazon``.
+If the module **Amazon/Authentication Patch** is present and marked as installed, your Odoo
+database is already up-to-date and you can proceed with the :doc:`setup <setup>` step
+of the Amazon Connector.
+
+Update Odoo to the latest release
+=================================
+
+The new authentication mechanism is made available through a new Odoo module; to
+be able to install it, you must make sure that your Odoo source code is up-to-date.
+
+If you use Odoo on Odoo.com or Odoo.sh platform, your code is already up-to-date and
+you can proceed to the next step.
+
+If you use Odoo with an on-premise setup or through a partner, then you must update
+your installation as detailed in
+`this documentation page <https://www.odoo.com/documentation/13.0/setup/update.html>`_
+or by contacting your integrating partner.
+
+Update the list of available modules
+====================================
+
+New modules must be *discovered* by your Odoo instance to be available in the **Apps**
+menu.
+
+To do so, activate the :doc:`Developer Mode <../../../general/developer_mode/activate>`, and go to
+:menuselection:`Apps --> Update Apps List`. A wizard will ask for confirmation.
+
+Install the Amazon/Authentication Patch
+=======================================
+
+.. warning::
+    You should never install new modules in your production database without testing
+    them in a duplicate or staging environment. For Odoo.com customers, a duplicate database
+    can be created from the database management page as explained in 
+    :doc:`this documentation page <../../db_management/db_online>`. For
+    Odoo.sh users, you should use a staging or duplicate database. For on-premise users,
+    you should use a staging environment - you should contact your integrating partner for
+    more information regarding how to test a new module in your particular setup.
+
+The module should now be available in your **Apps** menu. Remove the ``Apps`` search facet
+and search for ``amazon``; the module **Amazon/Authentication Patch** should be available for
+installation. If you cannot find the module after having updated the list of available
+modules, it means your Odoo source code is not up-to-date; refer to step one of this
+page.
+
+.. image:: ./media/auth_module.png
+  :align: center
+
+Once the module is installed, you will need to generate an Authorization Token in Amazon
+Seller Central and set it up on your Amazon Account in Odoo; this process is detailed
+in the :doc:`setup <setup>` page.