[ADD] sale_amazon: Amazon connector

This commit adds a complete documentation for the configuration and management of the Amazon connector in the Sales app.

sales.rst

@@ -10,5 +10,6 @@ Sales
    sales/send_quotations
    sales/invoicing
    sales/products_prices
+   sales/sale_amazon
    sales/sale_ebay
    sales/advanced

sales/sale_amazon.rst

@@ -0,0 +1,9 @@
+====================
+Amazon MWS Connector
+====================
+
+.. toctree::
+   :titlesonly:
+
+   sale_amazon/setup
+   sale_amazon/manage

sales/sale_amazon/manage.rst

@@ -0,0 +1,96 @@
+============================
+Manage Amazon orders in Odoo
+============================
+
+Synchronization of orders
+=========================
+
+Orders are automatically fetched from Amazon and synchronized in Odoo at regular intervals.
+The synchronization is based on the Amazon status: only orders whose status has changed since the
+last synchronization are fetched from Amazon. For **FBA** (Fulfilled by Amazon), only **Shipped**
+and **Canceled** orders are fetched. For **FBM** (Fulfilled by Merchant), the same is done for
+**Unshipped** and **Canceled** orders. For each synchronized order, a sales order and a customer are
+created in Odoo if they are not yet registered.
+
+.. note :: If you did not request access to Personally Identifiable Information of your customers
+           in the `Developer Registration and Assessment form <setup.html#developer-form>`_, the
+           customers are created anonymously (the name, postal address and phone number are omitted)
+           and named **Amazon Customer**.
+
+When an order is canceled in Amazon and was already synchronized in Odoo, the corresponding sales
+order is canceled in Odoo.
+When an order is canceled in Odoo, a notification is sent to Amazon who will mark it as such in
+Seller Central and notify the customer.
+
+.. note :: To force the synchronization of an order whose status has not changed since the last
+           synchronization, activate the **Developer mode**, navigate to your Amazon account and
+           modify the date under :menuselection:`Orders Follow-up --> Last Order Sync`. Pick a date
+           anterior to the last status change of the order that you wish to synchronize and save.
+
+.. tip :: To synchronize immediately the orders of your Amazon account, open that later's form in
+          **Developer mode** and click the button **SYNC ORDERS**. The same can be done with order
+          cancellations and pickings by clicking the buttons **SYNC CANCELLATIONS** and **SYNC
+          PICKINGS**.
+
+Manage deliveries in FBM
+========================
+
+When a **FBM** (Fulfilled by Merchant) order is synchronized in Odoo, a picking is created along
+with the sales order and the customer. You can either ship all the ordered products to your customer
+at once or ship products partially by using backorders.
+
+When a picking related to the order is confirmed, a notification is sent to Amazon who will, in
+turn, notify the customer that the order (or a part of it) is on its way.
+
+Follow deliveries in FBA
+========================
+
+When a **FBA** (Fulfilled by Amazon) order is synchronized in Odoo, a stock move is recorded for
+each sales order item so that it is saved in your system. Inventory managers can find such moves
+in :menuselection:`Inventory --> Reporting --> Product Moves`. They pick up products in a specific
+inventory location called **Amazon**. This location represents your stock in Amazon's warehouses
+and allows you to manage the stock of your products under the FBA program.
+
+.. tip :: To follow your Amazon (FBA) stock in Odoo, you can make an inventory adjustment after
+          replenishing it. You can also trigger an automated replenishment from reordering rules
+          on the Amazon location.
+
+.. tip :: The Amazon location is configurable by Amazon account managed in Odoo. All accounts of
+          the same company use the same location by default. It is however possible to follow the
+          stock by marketplace. First, remove the marketplace for which you want to follow the stock
+          separately from the list of synchronized marketplaces. Then, create another registration
+          for this account and remove all marketplaces, except the one to isolate from the others.
+          Finally, assign another stock location to the second registration of your account.
+
+
+Issue invoices and register payments
+====================================
+
+You can issue invoices for Amazon orders in Odoo. Click **Create Invoice** in the sales order to do
+so. You can also do it in batch from the list view of orders. Then, confirm and send the invoices to
+your customers.
+
+.. tip :: To display only Amazon-related orders on the list view, you can filter orders based on the
+          sales team.
+
+As the customer has paid Amazon as an intermediary, you should register invoice payments in a
+payment journal dedicated to Amazon (e.g. Amazon Payments, with a dedicated intermediary account).
+You can do the same with the vendor bill received from Amazon and dedicated to commissions. When you
+receive the balance on your bank account at the end of the month and record your bank statements in
+Odoo, you simply credit the Amazon intermediary account by the amount received.
+
+Follow your Amazon sales in sales reporting
+===========================================
+
+As a sales team is set on your account under the tab **Order Follow-up**, this helps you give quick
+glances at the figures in just a few clicks in Sales reporting. By default, your account's sales
+team is shared between all of your company's accounts.
+
+If you wish, you can change the sales team on your account for another to perform a separate
+reporting for the sales of this account.
+
+.. tip :: It is also possible to perform reporting on a per-marketplace basis in a similar fashion.
+          First, remove the marketplace you wish to track separately from the list of synchronized
+          marketplaces. Then, create another registration for this account and remove all
+          marketplaces, except the one to isolate from the others. Finally, assign another sales
+          team to one of the two registrations of your account.

sales/sale_amazon/setup.rst

@@ -0,0 +1,87 @@
+======================================
+Configure Amazon MWS Connector in Odoo
+======================================
+
+Get your Amazon MWS Credentials
+===============================
+
+In order to integrate Amazon with Odoo, a seller account on professional selling plan is required.
+
+.. Anchor should be one paragraph below but is placed here to fix wrongly adjusted display
+.. _developer-form:
+
+Visit the `Amazon Marketplace Web Service documentation
+<http://docs.developer.amazonservices.com/en_US/dev_guide/DG_Registering.html>`_ and follow the
+instructions to register as a developer.
+
+Fill the Developer Registration and Assessment form as suggested below and provide your own contact
+information in the **Developer contact information** section. For the other sections, take care to
+adapt your responses accordingly to your business case. In particular, select the correct region of
+your seller account and uncheck the **Merchant Fulfilled Shipping** function if you plan to sell
+exclusively with the Fulfillment by Amazon service.
+
+.. warning :: If you select the **Merchant Fulfilled Shipping** function (i.e. you request access to
+              Personally Identifiable Information (PII) of your customers), Amazon may request you
+              to fill out a second form, depending on the data protection policy in the region of
+              your seller account (e.g. GDPR in Europe).
+
+.. image:: ./media/dev_form.png
+
+
+Register your Amazon account in Odoo
+====================================
+
+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
+Developer Central (where the Developer Registration and Assessment form was located).
+
+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 from the list of
+synchronized marketplaces to disable their synchronization.
+
+Match database products in Amazon orders
+========================================
+
+.. Anchor should be one paragraph below but is placed here to fix wrongly adjusted display
+.. _matching:
+
+When an Amazon order is synchronized, up to three sales order items are created in Odoo for each
+product sold on Amazon: one for the marketplace product, one for the shipping charges (if any) and
+one for the gift wrapping charges (if any).
+
+The selection of a database product for a sales order item is done by matching its
+**internal reference** with the **SKU** for marketplace items, the **shipping code** for delivery
+charges, and the **gift wrapping** code for gift wrapping charges.
+
+For marketplace products, matchings are saved as **Amazon Offers** which are listed under the
+**Offers** stat button on the account form. Offers are automatically created when the matching is
+established and are used for subsequent orders to lookup SKUs. If no offer with a matching SKU is
+found, :ref:`the internal reference is used instead <matching>`.
+
+.. tip :: It is possible to force the matching of a marketplace item with a specific product by
+          changing either the product or the SKU of an offer. The offer can be manually created if
+          it was not automatically done yet. This is useful if you do not use the internal
+          reference as the SKU or if you sell the product under different conditions.
+
+If no database product with a matching internal reference is found for a given SKU or gift wrapping
+code, a default database product **Amazon Sale** is used. The same is done with the default product
+**Amazon Shipping** and the shipping code.
+
+.. note :: To modify the default products, activate the **Developer mode** and navigate to
+           :menuselection:`Sales --> Configuration --> Settings --> Connectors --> Amazon Sync -->
+           Default Products`.
+
+Configure taxes of products
+===========================
+
+To allow for tax reporting of Amazon sales with Odoo, the taxes applied to the sales order items are
+those set on the product or determined by the fiscal position. Make sure to have set the correct
+taxes on your products in Odoo or to have it done by a fiscal position, to avoid discrepancies in
+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.