# sifen-core

[![PyPI version](https://img.shields.io/pypi/v/sifen-core.svg)](https://pypi.org/project/sifen-core/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/sifen-core.svg)](https://pypi.org/project/sifen-core/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**sifen-core** es una librería Python pura diseñada para facilitar la integración con **SIFEN** (Sistema Integrado de Facturación Electrónica Nacional) de Paraguay.

Proporciona herramientas de alto nivel para manejar todo el ciclo de vida de los Documentos Electrónicos (DE): desde la generación del XML hasta la firma digital y la comunicación con los servicios web de la SET.

---

## Características principales

- ✅ **Generación de XML**: Soporte para DE y Eventos siguiendo las especificaciones de la SET.
- ✅ **Firma Digital**: Firma XMLDSig (RSA-SHA256) utilizando certificados PKCS#12 (.p12 / .pfx).
- ✅ **Comunicación SOAP**: Cliente integrado para interactuar con los Web Services (recibe, lote, consulta, evento).
- ✅ **Generación de QR**: Generación automática de la URL de consulta y su inserción en el XML.
- ✅ **Soporte Async**: Compatibilidad con `aiohttp` para operaciones no bloqueantes.
- ✅ **Tipado Fuerte**: Incluye archivo `py.typed` para soporte completo de MyPy/Type Checking.

---

## Estructura del paquete

```text
sifen/
├── setup.py            # Script de instalación legacy
├── pyproject.toml      # Configuración de empaquetado moderna
├── MANIFEST.in         # Asegura la inclusión de archivos extra
└── sifen/              # El paquete importable
    ├── __init__.py     # Exports principales
    ├── workflow.py     # Helpers de alto nivel (flujo completo)
    ├── xmlgen/         # Generación de XML (DE y Eventos)
    ├── xmlsign/        # Firma digital (RSA-SHA256)
    ├── qrgen/          # Generación e inserción de QR
    └── setapi/         # Cliente SOAP para la SET
```

---

## Instalación

### Desde PyPI (Recomendado)

```bash
pip install sifen-core
```

*Nota: El paquete se instala como `sifen-core`, pero se importa como `import sifen`.*

### Desde GitHub (Desarrollo)

```bash
pip install git+https://github.com/joshuboshu/sifen.git
```

---

## Uso rápido

### Flujo simplificado: Generar → Firmar → QR

La librería proporciona un helper en `sifen.workflow` que maneja todo el proceso inicial:

```python
from sifen.workflow import generate_de_signed_qr_xml

# Leer certificado y configurar secretos
pfx_bytes = open("certificado.p12", "rb").read()
password = "tu_contraseña"
id_csc = 1
csc_secret = "tu_csc_secreto"

# Generar XML firmado con QR listo para enviar
xml_final = generate_de_signed_qr_xml(
    params=params_dict,  # Ver documentación de parámetros
    data=data_dict,      # Datos de la factura
    pfx_bytes=pfx_bytes,
    password=password,
    id_csc=id_csc,
    csc=csc_secret,
    qr_test=True,        # True para ambiente de test
)
```

### Paso a paso detallado

```python
from sifen.xmlgen import generate_de_xml
from sifen.xmlsign import sign_de_xml
from sifen.qrgen import add_qr_to_signed_de_xml
from sifen.setapi import recibe

# 1. Generar XML base
xml = generate_de_xml(params=params, data=data)

# 2. Firmar digitalmente
signed = sign_de_xml(xml, pfx_bytes=pfx, password="pass")

# 3. Insertar código QR
final = add_qr_to_signed_de_xml(signed, id_csc=1, csc="secret", test=True)

# 4. Enviar a la SET
resp = recibe(id=1, xml=final, env="test", pfx_bytes=pfx, password="pass")
```

---

## Ambientes SIFEN

| Ambiente | Valor `env` | URL Base |
|----------|-------------|----------|
| **Pruebas** | `"test"` | `https://sifen-test.set.gov.py` |
| **Producción** | `"prod"` | `https://sifen.set.gov.py` |

---

## Requisitos

- Python 3.10 o superior
- Dependencias automáticas: `lxml`, `cryptography`, `xmltodict`, `requests`, `aiohttp`, `qrcode`.

---

## Contribuir

¡Las contribuciones son bienvenidas! Si encuentras un error o quieres proponer una mejora, abre un *issue* o envía un *pull request*.

## Licencia

Este proyecto está bajo la Licencia **MIT**. Consulta el archivo [LICENSE](LICENSE) para más detalles.

---

### Autor

**Joshua Lombardo** - [GitHub](https://github.com/joshuboshu)
