diff --git a/content/applications/sales/sales.rst b/content/applications/sales/sales.rst index e623d30fa..661da47d9 100644 --- a/content/applications/sales/sales.rst +++ b/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 diff --git a/content/applications/sales/sales/shopee_connector.rst b/content/applications/sales/sales/shopee_connector.rst new file mode 100644 index 000000000..0d06a555b --- /dev/null +++ b/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 diff --git a/content/applications/sales/sales/shopee_connector/manage.rst b/content/applications/sales/sales/shopee_connector/manage.rst new file mode 100644 index 000000000..e7e8ba3bf --- /dev/null +++ b/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 + `_). + + 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` diff --git a/content/applications/sales/sales/shopee_connector/manage/shopee-delivery-orders-status.png b/content/applications/sales/sales/shopee_connector/manage/shopee-delivery-orders-status.png new file mode 100644 index 000000000..fd4ce0d9a Binary files /dev/null and b/content/applications/sales/sales/shopee_connector/manage/shopee-delivery-orders-status.png differ diff --git a/content/applications/sales/sales/shopee_connector/manage/shopee-seller-centre-product-extract.png b/content/applications/sales/sales/shopee_connector/manage/shopee-seller-centre-product-extract.png new file mode 100644 index 000000000..5112aaff9 Binary files /dev/null and b/content/applications/sales/sales/shopee_connector/manage/shopee-seller-centre-product-extract.png differ diff --git a/content/applications/sales/sales/shopee_connector/manage/shopee-wh-out.png b/content/applications/sales/sales/shopee_connector/manage/shopee-wh-out.png new file mode 100644 index 000000000..7d0749915 Binary files /dev/null and b/content/applications/sales/sales/shopee_connector/manage/shopee-wh-out.png differ diff --git a/content/applications/sales/sales/shopee_connector/setup.rst b/content/applications/sales/sales/shopee_connector/setup.rst new file mode 100644 index 000000000..b6cbc7a3a --- /dev/null +++ b/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 +`_, and click the :guilabel:`Get Access (Now)` button located in the +middle of the page. + +Use the `Open Shopee Developer Guide `_, 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 `_ + #. 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 ` 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 `_ 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 `, 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 `, 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` diff --git a/content/applications/sales/sales/shopee_connector/setup/shopee-sales-odoo.png b/content/applications/sales/sales/shopee_connector/setup/shopee-sales-odoo.png new file mode 100644 index 000000000..6fd8d8890 Binary files /dev/null and b/content/applications/sales/sales/shopee_connector/setup/shopee-sales-odoo.png differ