[ADD] sale_shopee: Shopee Connector

Documentation on the benefits of the new shopee connector and guidelines for odoo users.

tasks-3623720

closes odoo/documentation#11984

Signed-off-by: Samuel Lieber (sali) <sali@odoo.com>

content/applications/sales/sales.rst

@@ -20,3 +20,4 @@ deliver and invoice what has been sold.
    sales/invoicing
    sales/products_prices
    sales/amazon_connector
+   sales/shopee_connector

content/applications/sales/sales/shopee_connector.rst

@@ -0,0 +1,73 @@
+:show-content:
+
+================
+Shopee Connector
+================
+
+The **Shopee Connector** synchronizes orders between Shopee and Odoo, which considerably reduces the
+amount of time spent manually entering Shopee orders (from the Shopee Seller account) into Odoo. It
+also allows users to accurately keep track of Shopee sales in Odoo.
+
+Supported features
+==================
+
+The **Shopee Connector** is able to:
+
+- Synchronize (Shopee to Odoo) all confirmed orders, and their order items, which include:
+
+  - Product name
+  - SKU reference
+  - Quantity
+
+- Synchronize (Odoo to Shopee) all available quantities of your products (:abbr:`FBM (Fulfilled by
+  Merchant)`).
+- Support multiple seller accounts.
+- Support multiple Shopee marketplaces (shops) per seller account.
+
+.. note::
+   The **Shopee Connector** is designed to synchronize sales orders data. Other actions, such as
+   downloading weekly/monthly income/fees reports, handling disputes, or issuing refunds, **must**
+   be managed from the *Shopee Seller Central*, as usual.
+
+Shopee supported marketplaces
+=============================
+
++-------------------------------+
+| **APAC region**               |
++===============+===============+
+| Indonesia     | Shopee.co.id  |
++---------------+---------------+
+| Taiwan        | Shopee.tw     |
++---------------+---------------+
+| Vietnam       | Shopee.vn     |
++---------------+---------------+
+| Thailand      | Shopee.co.th  |
++---------------+---------------+
+| Philippines   | Shopee.ph     |
++---------------+---------------+
+| Malaysia      | Shopee.com.my |
++---------------+---------------+
+| Singapore     | Shopee.sg     |
++---------------+---------------+
+
++-------------------------------+
+| **South America region**      |
++===============+===============+
+| Brazil        | Shopee.com.br |
++---------------+---------------+
+| Chile         | Shopee.cl     |
++---------------+---------------+
+| Colombia      | Shopee.com.co |
++---------------+---------------+
+| Mexico        | Shopee.com.mx |
++---------------+---------------+
+
+.. seealso::
+   - :doc:`shopee_connector/setup`
+   - :doc:`shopee_connector/manage`
+
+.. toctree::
+   :titlesonly:
+
+   shopee_connector/setup
+   shopee_connector/manage

content/applications/sales/sales/shopee_connector/manage.rst

@@ -0,0 +1,199 @@
+=======================
+Shopee order management
+=======================
+
+Product catalog mapping
+=======================
+
+New Odoo customers with no existing products
+--------------------------------------------
+
+If you are starting a new Odoo database and your products are only on Shopee, you can import your
+Shopee product catalog into Odoo.
+
+#. **Export Shopee catalog:** Use the *Mass Function* drop-down to export the product catalog from
+   Shopee, ensuring it includes the Shopee SKUs.
+
+   .. image:: manage/shopee-seller-centre-product-extract.png
+      :alt: Mass Function drop-down in Shopee.
+
+#. **Import into Odoo:** :doc:`Import <../../../essentials/export_import_data>` the exported catalog
+   into Odoo. During the import process, it is *crucial* to map the Shopee SKU to the
+   *Internal Reference* field in Odoo. This field will serve as the link between your Shopee and
+   Odoo products.
+
+Existing Odoo customers with products already in Odoo
+-----------------------------------------------------
+
+If you already have products in your Odoo database, you'll need to map your Shopee listings to your
+existing Odoo products.
+
+#. **Export Shopee catalogs:** Use the *Mass Function* drop-down to export the product catalog from Shopee
+   (including Shopee SKUs) and :doc:`export <../../../essentials/export_import_data>` your product
+   catalog from Odoo (including *Internal References*).
+#. **Map in a spreadsheet:** Use a spreadsheet to map the products. Match the Shopee SKU from the
+   Shopee export with the corresponding *Internal Reference* from the Odoo export. Create a column
+   that links the Shopee SKU with the Odoo *Internal Reference*.
+#. **Update Odoo products:** Import the updated spreadsheet back into Odoo. Use the mapping you
+   created in the spreadsheet to update the *Internal Reference* field of your existing Odoo
+   products with the corresponding Shopee SKU. This establishes the link between your Odoo and
+   Shopee products.
+
+.. important::
+   Product catalog synchronization between Odoo and Shopee is **not automatic**. It is a
+   **manual operation** that you must initiate. The process differs depending on whether your
+   products already exist in Odoo.
+
+Order synchronization
+=====================
+
+Orders are automatically fetched from Shopee, and synchronized in Odoo, at **regular intervals**.
+
+The synchronization is based on the Shopee orders status: only orders whose status has changed
+since the last synchronization are fetched from Shopee. This includes changes on Shopee only.
+
+When an order is canceled on Shopee, it will update the order's status in Odoo. On the other hand,
+if an order is canceled on Odoo, the change won't be reflected on Shopee.
+
+For every synchronized order, Odoo creates a sales order and a customer (contact), as long as the
+customer hasn't been previously imported from Shopee or doesn't already exist in the database.
+
+.. note::
+   The principal of the synchronization is to *only fetch orders that needs to be shipped*
+   (i.e., `SHIPPED`, `CANCEL`, `UNPAID`, `COMPLETED`).
+
+Force synchronization
+=====================
+
+In order to force the synchronization of an order, whose status has **not** changed since the
+previous synchronization:
+
+Then, navigate to the Shopee account in Odoo :menuselection:`Sales app --> Configuration --> Shopee
+--> Account --> Shop`. Modify the date for :guilabel:`Last Order Sync` under :guilabel:`Orders
+Follow-up`.
+
+Be sure to pick a date that occurs prior to the last status change of the desired order to
+synchronize and save. This will ensure synchronization occurs correctly.
+
+Manage deliveries in :abbr:`FBM (Fulfilled by Merchant)`
+========================================================
+
+Whenever an FBM (Fulfilled by Merchant) order is synchronized in Odoo, a picking is instantly
+created in the **Inventory** app, along with a sales order and customer record.
+
+When a picking related to the order is confirmed, you also have to click on :guilabel:`Arrange
+Shipment` in your Shopee Seller Account in order to be able to generate and fetch the
+:guilabel:`Shipping Label` and :guilabel:`Tracking Number`.
+
+Shopee delivery statuses
+------------------------
+
+Understanding the different Shopee delivery statuses is crucial for managing your orders
+effectively. Here's a breakdown:
+
+- **Ready to ship:** The seller can now arrange shipment for this order.
+- **Shipment arranged:** The seller has arranged shipment online and received a tracking number
+  from the third-party logistics (3PL) provider.
+- **Shipped:** The parcel has been dropped off at the 3PL location or picked up by the 3PL
+  provider.
+- **Cancelled:** The order has been canceled.
+- **Pickup failed:** The 3PL parcel pickup attempt failed. The seller needs to rearrange shipment,
+  and the rest of the order fulfillment content.
+
+.. image:: manage/shopee-delivery-orders-status.png
+   :alt: Shopee delivery status in Odoo.
+
+.. important::
+   Unsupported for Non-Shopee Supported Logistics (NSSL)
+
+   This feature is not available for :abbr:`NSSL (Non-Shopee Supported Logistics)`, you have to
+   manually create shipping label and tracking number via the logistics provider's website/app.
+   Check your region for list of supported logistics (e.g. `Malaysia
+   <https://seller.shopee.com.my/edu/article/388>`_).
+
+   Shopee requires users to provide a tracking reference with each delivery. This is needed to
+   assign a carrier.
+
+   If the carrier doesn't automatically provide a tracking reference, one must be set manually.
+   This rule applies to all Shopee marketplaces.
+
+Follow deliveries in Odoo
+=========================
+
+For :abbr:`FBM (Fulfilled by Merchant)` orders, the stock move is automatically created in Odoo by
+the Shopee connector, thanks to the shipping status of Shopee.
+
+.. image:: manage/shopee-wh-out.png
+   :alt: Stock move created for Shopee order in Odoo.
+
+Order fulfillment process
+-------------------------
+
+This section describes the process of fulfilling Shopee orders within Odoo, from order creation to
+inventory updates.
+
+#. **New order creation:** When a new order is placed on Shopee, it is automatically created in
+   Odoo.
+#. **Arrange shipment on Shopee:** Before the order can be shipped, you **must** arrange the
+   shipment through the Shopee platform itself. This usually involves selecting a shipping
+   provider, generating a shipping label, and scheduling pickup or drop-off. Odoo does *not*
+   handle the physical shipping arrangements; this is managed entirely within Shopee.
+#. **Fetch Shopee shipping label (delivery note):** Once the shipment is arranged on Shopee,
+   Odoo fetches the generated shipping label (which serves as the delivery note). This label
+   contains crucial information like the tracking number and is essential for printing and
+   attaching to the package. The shipping label is imported into Odoo and associated with the
+   corresponding sales order.
+#. **Validate stock out in Odoo:** After the shipping label is retrieved, you need to validate the
+   stock movement in Odoo. This confirms that the ordered items have left your warehouse or
+   inventory. Validating the stock out will decrease the stock levels in Odoo.
+#. **Inventory update on Shopee:** Finally, Odoo pushes the updated stock levels back to Shopee.
+   This ensures that your Shopee listings reflect the current inventory, preventing overselling and
+   keeping your product availability accurate. This synchronization keeps your Shopee storefront
+   up-to-date with your Odoo inventory.
+
+Register payments
+=================
+
+Since customers pay Shopee as an intermediary, creating a dedicated *Bank* journal (e.g. named
+`Shopee Payments`), with a dedicated *Bank and Cash* intermediary account is recommended.
+
+Additionally, as Shopee makes a single weekly or monthly payment, selecting all the invoices linked
+to a single payment is necessary when registering payments.
+
+To do that, use the appropriate :guilabel:`Journal` dedicated to Shopee payments, and select
+:guilabel:`Batch Deposit` as the :guilabel:`Payment Method`.
+
+Then, select all the generated payments, and click :menuselection:`Actions --> Create batch payment
+--> Validate`.
+
+.. tip::
+   This same action can be performed with vendor bills from Shopee dedicated to fees/commissions.
+
+   When the balance is received in the bank account at the end of the week/month, and the bank
+   statements are recorded, credit the Shopee intermediary account by the amount received.
+
+Analyzing Shopee sales with Odoo's reporting
+============================================
+
+Odoo's dashboard consolidates sales data from all your connected sales channels, providing a
+comprehensive overview of your business performance. To specifically analyze your Shopee sales, you
+will need to configure sales teams for your Shopee shops. This setup enables you to filter and
+isolate Shopee sales data within the Odoo dashboard.
+
+Setting up sales teams for Shopee reporting
+-------------------------------------------
+
+By default, the Shopee account's sales team is shared across all of your company's accounts. To
+generate separate reports for specific Shopee shops or marketplaces, you'll need to assign dedicated
+sales teams.
+
+#. **Assign a sales team to your Shopee shop:** Navigate to the Shopee account configuration
+   (typically found under :menuselection:`Sales --> Configuration --> Accounts`).  Within the
+   account details, assign a specific sales team to your Shopee shop.
+#. **Filtering Shopee sales on the dashboard:** Once sales teams are assigned, you can use the
+   dashboard filters to view sales data specifically for your Shopee shops. Select the appropriate
+   sales team to isolate and analyze your Shopee performance.
+
+.. seealso::
+   - :doc:`Shopee supported features and marketplaces <../shopee_connector>`
+   - :doc:`setup`

content/applications/sales/sales/shopee_connector/setup.rst

@@ -0,0 +1,232 @@
+==============================
+Shopee Connector configuration
+==============================
+
+Odoo allows users to synchronize with Shopee Seller account in the database, but users **must**
+have a registered **Shopee Seller account** and a **Shopee Open account** prior to completing the
+configuration.
+
+Set up an Open Shopee account by first going to the `Shopee Open Platform
+<https://open.shopee.com/>`_, and click the :guilabel:`Get Access (Now)` button located in the
+middle of the page.
+
+Use the `Open Shopee Developer Guide <https://open.shopee.com/developer-guide/12>`_, and follow the
+registration process. Once all done, proceed to follow the instructions below to register and link
+the Open Shopee account in Odoo.
+
+.. important::
+   Shopee Open Platform access and seller account requirements are **regionally specific**. This
+   means the rules, qualifications, and processes differ from country to country. Before proceeding
+   with Odoo's Shopee Connector setup, verify the requirements for *your* specific Shopee region.
+
+   **Key Considerations:**
+
+   - **Shopee Seller Status & Business Type:** You must have an active Shopee seller account
+     (Individual or Registered Business). Your eligibility depends on your region and business
+     registration.
+   - **Order Volume/Seller Tier (If Applicable):** Many regions require a minimum number of orders
+     within a specific time frame or a certain seller tier (e.g., Mall, Preferred, Managed) to
+     access the Open Platform.
+
+   **Action Required:**
+
+   #. Identify your Shopee region.
+   #. Locate the official Shopee documentation for your region.
+      `Open Shopee Developer Guide <https://open.shopee.com/developer-guide/12>`_
+   #. Carefully review the requirements for seller accounts and Open Platform access in your
+      region.
+   #. Ensure your Shopee account meets all the necessary criteria *before* proceeding with the
+      Odoo Shopee Connector configuration.
+
+.. _shopee/setup:
+
+Connect Shopee seller account to Odoo
+=====================================
+
+:ref:`Install <general/install>` the :guilabel:`Shopee Connector` (`sale_shoppe`) by going to
+:menuselection:`Apps`.
+
+Then connect your Shopee Open account by navigating to :menuselection:`Sales app --> Configuration
+--> Shopee --> Accounts`.
+
+From here, click :guilabel:`New` to create to link a new Shopee account.
+
+Then, in the :guilabel:`Credentials` tab, select the appropriate :guilabel:`API Endpoint` from the
+drop-down menu.
+
+.. note::
+   Shopee offers several API endpoints for production and testing. Selecting the correct endpoint
+   is crucial for successful integration. Choose the endpoint that corresponds to your marketplace
+   location.
+
+   - :guilabel:`Shopee Production Endpoint (Singapore)`: This is the primary endpoint for sellers in
+     most APAC countries. Select this option unless you are specifically operating within mainland
+     China or Brazil.
+   - :guilabel:`Shopee Production Endpoint (China)`: This endpoint is exclusively for sellers
+     operating within mainland China. It is designed to comply with local regulations and business
+     practices.
+   - :guilabel:`Shopee Production Endpoint (Brazil)`: This endpoint is dedicated to sellers
+     operating within Brazil. Select this option if your Shopee store is based in Brazil.
+   - :guilabel:`Shopee Testing Endpoint`: This endpoint is for development and testing purposes
+     only. Use it to simulate interactions with the Shopee API without affecting your live data.
+     **Do not use this endpoint for production.**
+   - :guilabel:`Shopee Testing Endpoint (China)`:  Similar to the general testing endpoint, this one
+     is specifically for testing integrations related to the China-specific production endpoint.
+     **Do not use this endpoint for production.**
+
+After selecting the correct API Endpoint in the :guilabel:`Credentials` form, input your Open
+Shopee :guilabel:`Partner ID` and :guilabel:`Partner Key` in the corresponding fields. Then click
+:guilabel:`Save And Authorize`.
+
+.. important::
+   You'll need your Open Shopee :guilabel:`Partner ID` and :guilabel:`Partner Key` to complete this
+   step. Here's how to find them in the Shopee Open Platform:
+
+   #. **Log in to the Shopee Open Platform:** `Log in <https://open.shopee.com/>`_ with the
+      credentials you used to register your Open Shopee account.
+   #. **Navigate to App Management:** Go to the :guilabel:`App Management` section, then select
+      :guilabel:`App List`.
+   #. **Select your app:** Choose the specific app you want to synchronize with Odoo (either your
+      test app or your production app).
+   #. **Find your credentials:** Within the app details, you'll find your Partner ID and Partner
+      Key. These are the values you'll need to copy and paste into the corresponding fields in
+      Odoo.
+
+.. note::
+   - **Copy carefully:** Copy the Partner ID and Partner Key accurately, without any extra spaces
+     or characters. These are case-sensitive.
+   - **Keep your key secure:** Your Partner Key is sensitive information. Do not share it with
+     anyone. Treat it like a password.
+
+Authorization and account registration
+======================================
+
+After entering connecting the :ref:`Shoppe Seller account to Odoo <shopee/setup>`, the authorization
+process begins.
+
+Shopee seller account selection/login
+-------------------------------------
+
+Upon clicking :guilabel:`Save and Authorize`, Odoo redirects to the Shopee seller account selection
+page.
+
+- **Already logged in:** If you are already logged in to a Shopee account, your email address or
+  username will be displayed. Click on your account to proceed.
+- **Not logged in:** If you are not logged in, you will be prompted to enter the credentials
+  (email/username and password) of the Shopee seller account you wish to connect to Odoo.
+
+Granting access to Odoo
+-----------------------
+
+After selecting or logging into your Shopee seller account, you will be directed to the
+authorization (or consent) page. Here, confirm that you allow Shopee to grant Odoo access to your
+account and related data. This step is essential for the integration to function correctly.
+
+Account registration and Shopee shop creation
+=============================================
+
+Upon confirming access, Shopee redirects you back to Odoo. An indicator appears, confirming that
+your Shopee account has been successfully registered.
+
+Post-synchronization configuration
+----------------------------------
+
+After the redirection, you should perform the following steps within Odoo:
+
+#. **Rename the Shopee Account (Optional):** The newly created Shopee account in Odoo will likely
+   have a default name. You can rename it to something more descriptive (e.g., the name of your
+   Shopee shop) for easier management.
+#. **Set the Last Order Synchronization Date:** This setting determines the starting point for
+   fetching orders from Shopee. Choose a date from which you want Odoo to retrieve past orders.
+#. **Configure Inventory Synchronization:**  Decide whether you want to synchronize your product
+   inventory between Odoo and Shopee. Enable the :guilabel:`Synchronize Inventory` option to
+   automatically push stock updates from Odoo to Shopee. Disabling this option prevents automatic
+   inventory updates.
+#. **Assign a Default Sales Team:** Assign a default sales team to your Shopee account in Odoo.
+   This helps with reporting and order management.
+
+With the Shopee account successfully registered, the marketplaces available with this specific
+account can later be synchronized the exact same way, and listed under the :guilabel:`Shops`
+button.
+
+Shopee orders in Odoo
+=====================
+
+When a Shopee order is synchronized, only lines for items are created on the sales order in Odoo.
+Each one represents one for the product that was sold on Shopee.
+
+.. image:: setup/shopee-sales-odoo.png
+   :alt: Shopee synchronized sale order in Odoo.
+
+Any necessary price reconciliation related to shipping or income versus fees can be managed later
+using Shopee's weekly / monthly financial reports, which can then be imported into the Odoo
+**Accounting** app.
+
+The selection of a database product for a sales order item is done by matching its
+:guilabel:`Internal Reference` (a customizable product reference identifier in Odoo, like `FURN001`)
+with the Shopee *SKU*.
+
+If no database product with a matching internal reference is found for a given
+:guilabel:`Shopee SKU`, then a default database product, *Shopee Item*.
+
+.. note::
+   To modify default products, activate the :ref:`developer mode <developer-mode>`, and navigate to
+   :menuselection:`Sales app --> Configuration --> Settings`. In the :guilabel:`Connectors` section,
+   under :guilabel:`Shopee Sync`, find the :guilabel:`Default Products`.
+
+Product tax configuration
+=========================
+
+To allow for tax reporting of Shopee sales with Odoo, the taxes applied to the sales order items are
+those set on the product, or determined by the :doc:`fiscal position
+<../../../finance/fiscal_localizations>`.
+
+Make sure to have the correct taxes set on your products in Odoo, or have it done by a fiscal
+position, to avoid discrepancies in the subtotals between *Shopee Seller Central* and Odoo.
+
+.. note::
+   As shopee does not necessarily apply the same taxes as those configured in Odoo, it may happen
+   that order totals differ by a few cents between Odoo and *Shopee Seller Central*. Those
+   differences can be resolved with a write-off when reconciling the payments in Odoo.
+
+.. _shopee/add-new-marketplace:
+
+Add a new marketplace
+=====================
+
+To add a new marketplace, follow these steps:
+
+#. **Navigate to Shopee Accounts:** Go to :menuselection:`Sales --> Configuration --> Accounts`.
+#. **Create a New Shopee Account:** Click :guilabel:`New` to create a new Shopee marketplace
+   account.
+#. **Select the API Endpoint:** Choose the appropriate API endpoint for your local market.
+   (Typically, this will be :guilabel:`Shopee Production Endpoint (Singapore)` unless you are
+   operating in mainland China or Brazil. Refer to the documentation for details on endpoint
+   selection).
+#. **Enter Credentials:** Your :guilabel:`Partner ID` and :guilabel:`Partner Key` are the same as
+   those linked to your unique Open Shopee account. Enter these values in the corresponding fields.
+#. **Name Your Shop:** Give the new shop a descriptive name (e.g., `Shopee Philippines`) to identify
+   it later.
+#. **Assign a Sales Team:** Assign a relevant sales team (e.g., `Shopee Sales Philippines`) to
+   enable advanced reporting capabilities.
+#. **Synchronize Your Account:** If none of your existing marketplaces are listed, click
+   :guilabel:`Log in with another account` to synchronize a new one. This will initiate the Shopee
+   authorization process.
+
+Automatic synchronization
+-------------------------
+
+Newly added marketplaces are automatically added to the list of synchronized marketplaces. If a new
+marketplace does *not* appear in the list after synchronization, it indicates that the marketplace
+is either incompatible with the Shopee Open Platform or unavailable for your specific seller
+account. Consult the Shopee Open Platform documentation or contact their support for further
+assistance.
+
+.. important::
+   While Odoo allows creating the same Shopee shop multiple times, only one instance will function
+   due to token limitations. To avoid order management issues, synchronize each shop only once. For
+   connection updates, manually fetch orders first before re-establishing the connection.
+
+.. seealso::
+   - :doc:`Shopee supported features and marketplaces <../shopee_connector>`
+   - :doc:`manage`