Metadata-Version: 2.4
Name: cfdi-toolkit
Version: 1.0.0
Summary: Python toolkit for Mexican electronic invoicing (CFDI)
Author: chonchah
License: MIT
Project-URL: Homepage, https://github.com/chonchah/cfdi-python
Project-URL: Repository, https://github.com/chonchah/cfdi-python
Keywords: cfdi,sat,invoicing,mexico,tax,fiscal,factura
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: lxml>=4.6.0
Requires-Dist: qrcode>=6.3.0
Requires-Dist: Pillow>=8.0.0
Requires-Dist: python-dotenv>=0.19.0
Provides-Extra: pdf
Requires-Dist: reportlab>=3.5.0; extra == "pdf"
Provides-Extra: soap
Requires-Dist: zeep>=4.0.0; extra == "soap"
Provides-Extra: test
Requires-Dist: pytest>=6.0.0; extra == "test"
Dynamic: license-file

# cfdi (cfdi-toolkit)

[![PyPI](https://img.shields.io/pypi/v/cfdi-toolkit.svg)](https://pypi.org/project/cfdi-toolkit/)
[![Python](https://img.shields.io/badge/Python-3.7%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Python toolkit for **Mexican electronic invoicing — CFDI (Comprobante Fiscal Digital por Internet, SAT México)**. Validate, build, stamp, verify and convert CFDI documents.

## Features

- Validation of invoice requests
- Building of CFDI XML documents
- SOAP integration with the PAC (digital stamping)
- Sealed XML and PDF download
- SAT verification QR code generation
- Digital stamp (timbre) information extraction
- Number-to-words conversion in Spanish (Mexican pesos)
- Creation of ZIP archives with multiple documents

## Installation

```bash
pip install cfdi-toolkit
```

Or, to develop locally from this repository:

```bash
pip install -e .[test]
```

## Quick start

```python
from cfdi import CFDI

# Validate a request
datos = {
    'jbautoinc': 12345,
    'RFC': 'ABC123456XYZ',
    'CFDI': '<xml>...</xml>',
    'MetodoPago': 'PUE',
    'FormaPago': '01',
}
es_valido, errores = CFDI.validate_invoice_request(datos)

# Build XML and stamp via PAC
cfdi = CFDI(timeout=600)
xml = CFDI.get_cfdi_xml({'CFDI': {'Folio': '001', 'Total': '1500.00'}})
resultado = cfdi.obtener_xml_pdf(xml)   # seals via SOAP and downloads

# Number to words
print(CFDI.num2letras(1234.56))
# Mil doscientos treinta y cuatro pesos 56/100 M.N.

# SAT verification QR
qr = CFDI.generate_qr('uuid', 'RfcEmisor', 'RfcReceptor', '1500.00', 'sello123')

# Extract timbre from a sealed XML
timbre = CFDI.get_timbre(xml_sellado)
print(timbre['UUID'])
```

## API overview

| Method | Description |
|---|---|
| `CFDI.validate_invoice_request(data)` | Validate required invoice fields |
| `CFDI.get_cfdi_xml(request_data)` | Build the CFDI XML |
| `CFDI.obtener_xml_pdf(document, document_type='1')` | Seal via SOAP and download XML + PDF |
| `CFDI.generate_invoice(document, document_type='1')` | Perform the SOAP request to the PAC |
| `CFDI.get_timbre(xml_content)` | Extract digital stamp info |
| `CFDI.generate_qr(uuid, rfc_emisor, rfc_receptor, total, sello)` | Generate verification QR |
| `CFDI.create_zip(files, output_path=None)` | Group documents into a ZIP |
| `CFDI.num2letras(num, feminine=False, decimals=True)` | Number to words |
| `LoginObject(username, password)` | SOAP credentials holder |

Exceptions: `CFDIError` (base), `CFDIValidationError`, `CFDISoapError`.

## Configuration

Environment variables (optionally loaded via `python-dotenv`):

| Variable | Description |
|---|---|
| `SLACK_WEBHOOK_CFDI` | Slack webhook for error notifications |
| `EMISOR_EMAIL` | Issuer email (for PDFs) |
| `EMISOR_TEL` | Issuer phone (for PDFs) |
| `CFDI_SOAP_USERNAME` / `CFDI_SOAP_PASSWORD` | Optional SOAP credentials |

> **Note:** the PAC endpoint is configured through `CFDI.CFDI_360_URL`. Set this value (or a `PAC_URL`) before using it in production.

## Tests

```bash
pip install -e .[test]
python -m pytest tests -v
```

## Examples

Run the practical examples:

```bash
python examples/examples.py
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT — see [LICENSE](LICENSE).
