Metadata-Version: 2.1
Name: odoo-addon-l10n_mx_sat
Version: 18.0.1.0.0.2
Requires-Python: >=3.10
Requires-Dist: odoo==18.0.*
Summary: Connect to the SAT portal using FIEL credentials & manage downloads
Home-page: https://github.com/OCA/l10n-mexico
License: AGPL-3
Author: Gray Matter Logic, Asociacion Mexicana de Odoo (AMOdoo), Odoo Community Association (OCA), Cloud Lotus
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 18.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

=======================
Mexico - SAT Connection
=======================

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

.. |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%2Fl10n--mexico-lightgray.png?logo=github
    :target: https://github.com/OCA/l10n-mexico/tree/18.0/l10n_mx_sat
    :alt: OCA/l10n-mexico
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/l10n-mexico-18-0/l10n-mexico-18-0-l10n_mx_sat
    :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/l10n-mexico&target_branch=18.0
    :alt: Try me on Runboat

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

Description
===========

Base module to connect Odoo to the Mexican Tax Administration (SAT)
portal using FIEL electronic signature credentials.

It provides:

- Multi-company FIEL credentials stored on each ``res.company`` record.
- A SAT tab on the company form to configure download flows, sync dates,
  and manual synchronization.
- A secure FIEL credentials wizard that stores certificate, key, and
  password without exposing saved values in the UI.
- Generic SAT document storage (``l10n_mx_sat.document``) for CFDIs and
  retentions, both issued and received.
- A download orchestration layer (``l10n_mx_sat.download.request``) that
  handles XML mass downloads via ``satcfdi``.
- Configurable XML download flows per company: CFDI issued/received and
  retentions issued/received.
- An adapter (``SatClient``) that wraps communication with the SAT via
  the ``satcfdi`` library. Other modules can use this adapter without
  depending directly on ``satcfdi``.
- A factory method ``company.l10n_mx_sat_get_client()`` that returns an
  adapter instance. It can be overridden via ``_inherit`` to swap the
  underlying implementation.

This module downloads and stores SAT XML documents. Automatic metadata
synchronization is postponed for a future release. Other custom modules
may consume ``l10n_mx_sat.document`` records for their own business
flows.

.. 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
============

This module requires the Python library
```satcfdi`` <https://pypi.org/project/satcfdi/>`__ to communicate with
the SAT web services. Install it in the same Python environment as Odoo
before using SAT connection features.

Install it with pip:

::

   pip install satcfdi

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

For each Mexican company:

1. Open **Settings > Companies > [Company] > SAT** tab.
2. Click **Update FIEL credentials** and upload the certificate
   (``.cer``), private key (``.key``), and password in the wizard. The
   company VAT/RFC is set automatically from the FIEL certificate.
3. Once FIEL is configured, the company VAT/RFC becomes read-only and
   must be updated through the FIEL credentials wizard.
4. Review the FIEL configured indicator shown on the company form. Saved
   credentials are never displayed or downloadable from the UI.
5. Choose which XML download flows are enabled:

   - CFDI issued
   - CFDI received
   - Retentiones issued
   - Retentiones received

6. Optionally set:

   - **Sync documents from**: first XML backfill date.
   - **Automatic SAT download**: enable/disable daily cron processing.

7. Click **Test connection** to validate FIEL credentials.
8. Click **Sync now** to enqueue SAT XML download requests immediately.

Multi-company
-------------

Each company keeps its own FIEL credentials, download flow selection,
and sync windows. Users only see SAT documents and requests for
companies they are allowed to access.

Metadata
--------

Automatic metadata downloads are disabled for now. SAT status refresh
from metadata will be implemented in a later release.

Usage
=====

After configuration, the daily cron creates and processes SAT XML
download requests for each enabled company and for each enabled flow.

Manual review
-------------

Open **SAT > Documents** to browse downloaded CFDIs and retenciones. Use
filters for company, SAT status, direction, and document type.

Open **SAT > Download Requests** to monitor request states, packages,
and errors.

Downstream modules
------------------

Other modules should read from ``l10n_mx_sat.document`` instead of
calling SAT web services directly.

Metadata
--------

Automatic metadata synchronization is not scheduled by this module yet.
Use XML downloads for document storage and wait for the future metadata
refresh logic before expecting SAT status updates from metadata files.

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

Bugs are tracked on `GitHub Issues <https://github.com/OCA/l10n-mexico/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/l10n-mexico/issues/new?body=module:%20l10n_mx_sat%0Aversion:%2018.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
* Asociacion Mexicana de Odoo (AMOdoo)
* Cloud Lotus

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

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

  - Maxime Chambreuil maxime.chambreuil@graymatterlogic.com
  - Roberto Cifuentes roberto@cloudlotus.net

- `Asociacion Mexicana de Odoo (AMOdoo) <https://amodoo.org/>`__

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/l10n-mexico <https://github.com/OCA/l10n-mexico/tree/18.0/l10n_mx_sat>`_ project on GitHub.

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