Metadata-Version: 2.1
Name: odoo-addon-connector_mercadolibre
Version: 19.0.1.0.0.2
Requires-Dist: odoo-addon-connector==19.0.*
Requires-Dist: odoo==19.0.*
Requires-Dist: requests
Summary: Backend, OAuth, and notifications for Mercado Libre
Home-page: https://github.com/OCA/connector-mercadolibre
License: AGPL-3
Author: Gray Matter Logic, Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 19.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Development Status :: 3 - Alpha
Description-Content-Type: text/x-rst

.. image:: https://odoo-community.org/readme-banner-image
   :target: https://odoo-community.org/get-involved?utm_source=readme
   :alt: Odoo Community Association

=======================
Mercado Libre Connector
=======================

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:bd51e3d779f45d70560cffcc3ab3ed06787c43f9f5bcee060433a2069e4ab7b2
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Alpha-red.png
    :target: https://odoo-community.org/page/development-status
    :alt: Alpha
.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fconnector--mercadolibre-lightgray.png?logo=github
    :target: https://github.com/OCA/connector-mercadolibre/tree/19.0/connector_mercadolibre
    :alt: OCA/connector-mercadolibre
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/connector-mercadolibre-19-0/connector-mercadolibre-19-0-connector_mercadolibre
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
    :target: https://runboat.odoo-community.org/builds?repo=OCA/connector-mercadolibre&target_branch=19.0
    :alt: Try me on Runboat

|badge1| |badge2| |badge3| |badge4| |badge5|

Connect an Odoo company to a Mercado Libre seller account.

This is the core of the connector. It stores the seller backend,
authorizes the application with OAuth 2.0, refreshes access tokens, and
receives Mercado Libre notifications. Listing, stock, and sale
synchronization live in ``connector_mercadolibre_product`` and
``connector_mercadolibre_sale``.

A notification is stored and acknowledged in the HTTP request. The work
runs afterwards in an OCA queue job.

.. IMPORTANT::
   This is an alpha version, the data model and design can change at any time without warning.
   Only for development or testing purpose, do not use in production.
   `More details on development status <https://odoo-community.org/page/development-status>`_

**Table of contents**

.. contents::
   :local:

Installation
============

Install this module together with OCA ``connector`` 19.0. ``connector``
depends on ``component``, ``component_event``, and ``queue_job``.

The HTTP client uses the Python package ``requests``.

Enable the job runner. In ``odoo.conf``:

::

   [queue_job]
   channels = root:2,root.mercadolibre.import:2,root.mercadolibre.export:1,root.mercadolibre.webhook:2

Start Odoo with ``--load=base,web,queue_job`` and more than one worker.

Configuration
=============

1. Create an application in Mercado Libre (My Applications) with write
   scope and a redirect URI that points at this database, for example
   ``https://example.com/mercadolibre/oauth/callback``.
2. Set the notification callback to
   ``https://example.com/mercadolibre/notification/<backend-database-id>``.
   Subscribe the topics the installed addons handle. The core stores
   every topic; product and sale addons consume ``items``,
   ``stock-location``, ``orders_v2``, ``shipments``, and ``payments``.
3. Grant operators **Mercado Libre / User** and administrators **Mercado
   Libre / Manager**.
4. Open **Mercado Libre / Configuration / Backends**, create a backend,
   set the company, the site (``MLA``, ``MLB``, ``MLM``, …), the client
   id, the client secret, and the redirect URI.
5. Click **Connect** and authorize the seller. The backend stores the
   seller id returned by ``/users/me`` and the token pair.
6. A scheduled action refreshes the access token before the six-hour
   expiry. When Mercado Libre rejects the refresh token, the backend
   moves to **Error** and an administrator reconnects the seller.

Usage
=====

Open **Mercado Libre / Operations / Notifications** to see the callbacks
Mercado Libre has posted. Each row is dispatched by a job on the
``root.mercadolibre.webhook`` channel.

A topic with no installed handler is marked **Skipped**. Installing a
later addon adds a handler component; the controller stays unchanged.

**Refresh token** on the backend asks Mercado Libre for a new access
token immediately. **Disconnect** deletes the stored tokens.

Development
===========

The backend model ``mercadolibre.backend`` is the component collection.
Dispatch loads every component with usage ``notification.handler`` on
``mercadolibre.notification`` and keeps the one whose ``_topic`` equals
the payload topic. A handler with an empty ``_topic`` marks the
notification skipped.

``_apply_on`` has to be an Odoo model name. The Mercado Libre topic is
not a model, so a later addon selects its topic with ``_topic``.

Register a handler for one topic in another addon:

::

   class OrderNotificationHandler(Component):
       _name = "mercadolibre.notification.handler.orders"
       _inherit = "mercadolibre.notification.handler"
       _apply_on = "mercadolibre.notification"
       _usage = "notification.handler"
       _topic = "orders_v2"

       def handle(self):
           notification = self.work.notification
           ...

The HTTP adapter usage is ``backend.adapter``. Child adapters inherit
``mercadolibre.adapter`` and set the resource path. Token refresh takes
a row lock on the backend because the refresh token is single-use.

Set ``QUEUE_JOB__NO_DELAY=1`` to run jobs inline while developing.

Known issues / Roadmap
======================

- ``connector_mercadolibre_product`` binds listings and exports price
  and seller-warehouse stock.
- ``connector_mercadolibre_sale`` imports orders, packs, and shipments.
- Questions, claims, shipping labels, promotions, payouts, country
  fiscal documents, and Global Selling (``/marketplace``) are further
  addons. Each one adds components and does not change this controller.

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/connector-mercadolibre/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/connector-mercadolibre/issues/new?body=module:%20connector_mercadolibre%0Aversion:%2019.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
-------

* Gray Matter Logic

Contributors
------------

- `Gray Matter Logic <https://www.graymatterlogic.com>`__:

  - Maxime Chambreuil <maxime.chambreuil@graymatterlogic.com>

Maintainers
-----------

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

.. |maintainer-max3903| image:: https://github.com/max3903.png?size=40px
    :target: https://github.com/max3903
    :alt: max3903

Current `maintainer <https://odoo-community.org/page/maintainer-role>`__:

|maintainer-max3903| 

This module is part of the `OCA/connector-mercadolibre <https://github.com/OCA/connector-mercadolibre/tree/19.0/connector_mercadolibre>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
