Mexico - SAT Connection

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

Table of contents

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 (satcfdi >= 26.7.2, which restores Python 3.10 support and the retention download API):

pip install "satcfdi>=26.7.2"

satcfdi is declared in the module manifest external_dependencies. OCA CI and Runboat also pin it in the repository root test-requirements.txt (satcfdi>=26.7.2), together with compatible urllib3 and requests pins.

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

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:
  • Maxime Chambreuil <maxime.chambreuil@graymatterlogic.com>
  • Roberto Cifuentes <roberto@cloudlotus.net>
• Asociacion Mexicana de Odoo (AMOdoo)

Maintainers

This module is maintained by the OCA.

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.

Current maintainer:

This module is part of the OCA/l10n-mexico project on GitHub.

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