Metadata-Version: 2.3
Name: unpaismejor_currency_do
Version: 8.0.0
Summary: Dominican Republic currency rates for Tryton
Project-URL: homepage, https://code.unpaismejor.org.do/tryton-do/currency_do
Project-URL: repository, https://code.unpaismejor.org.do/tryton-do/currency_do
Author: Fundación Un País Mejor
Maintainer: Fundación Un País Mejor
License: GPL-3.0-or-later
Keywords: bcrd,currency,dominican-republic,tryton
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Framework :: Tryton
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: trytond-currency<8.1,>=8.0
Requires-Dist: trytond<8.1,>=8.0
Provides-Extra: test
Requires-Dist: proteus<8.1,>=8.0; extra == 'test'
Description-Content-Type: text/x-rst

Currency DO
===========

Dominican Republic currency integration for Tryton 8.0.

The module extends the standard ``currency.cron`` model with a new source:
``Banco Central de la República Dominicana``. It reads effective BCRD rates
from a compatible HTTP API and converts them to the rate format expected by
Tryton.

Tryton stores rates as target currency per one unit of the cron base currency.
The BCRD API is expected to return DOP per one unit of the requested foreign
currency. The module therefore calculates cross rates using DOP as pivot.

Configuration
-------------

Create or edit a currency cron and set:

* Source: ``Banco Central de la República Dominicana``
* Currency: the base currency for Tryton rates, commonly ``DOP``
* Currencies: the target currencies to update
* BCRD API Base URL: for example ``https://rates.joseagrc.com``
* BCRD Rate Type: normally ``Purchase``
* BCRD Fallback Policy: normally ``Previous Available``

The API endpoint must respond to:

``GET /rates/effective?date=YYYY-MM-DD&currency=USD&variant=STANDARD&fallback_policy=previous_available``

The response must contain the selected rate field, for example:

.. code-block:: json

   {
     "rate_date": "2026-06-05",
     "currency_code": "USD",
     "currency_variant": "STANDARD",
     "purchase": "59.123456",
     "sale": null
   }

Currency Variants
-----------------

By default, currencies are requested with variant ``STANDARD``. Overrides can
be configured with JSON:

.. code-block:: json

   {"GBP": "SCOTLAND"}

or one mapping per line:

.. code-block:: text

   GBP=SCOTLAND

Operational Note
----------------

The module uses the standard Tryton currency cron behavior. Pressing the run
button processes pending dates based on ``last_update`` and the cron frequency;
if there is no pending date, no API request is made.

The service configured in ``BCRD API Base URL`` is an API adapter compatible
with this module.  It is not part of Tryton and must be operated and secured
separately.  SSL verification should remain enabled in production.

Migration
---------

This release uses only the public ``currency.cron`` extension mechanism from
Tryton 8.0.  Its fields are additive and existing BCRD cron records are kept
when the module is upgraded.  The module sets the symbol of the existing DOP
currency to ``RD$`` during activation or upgrade.  It also applies the same
symbol when DOP is imported after the module has been activated.  The
operation is idempotent and does not create or duplicate currency records.

After replacing the package, update the database with the standard Tryton
module upgrade procedure and restart all Tryton workers.  Existing cron
credentials and scheduling data do not need to be recreated.
