LibreCFE

Motor open source de Comprobantes Fiscales Electronicos (CFE) para Uruguay.

LibreCFE es el primer proyecto libre de facturacion electronica para Uruguay. Implementa la integracion con la DGI (Direccion General Impositiva) para la emision, firma, envio y consulta de Comprobantes Fiscales Electronicos segun la normativa vigente (XSD v1.44.2, diciembre 2025).

Licencia: MIT.

---

Proposito

LibreCFE nace frente a un mercado de facturacion electronica saturado donde competir por precio dejo de ser sostenible, con la conviccion de que el futuro del sector pasa por un estandar abierto que democratice la tecnologia, potencie la innovacion y fortalezca el ecosistema local.

Objetivos:

• Ser una implementacion abierta y documentada de la integracion con la DGI Uruguay.
• Permitir a desarrolladores, universidades y empresas aprender, colaborar y extender la solucion.
• Convertirse en un estandar abierto de facto para la facturacion electronica en Uruguay.

Lectura recomendada antes de contribuir: docs/MANIFIESTO.md — documento fundacional del proyecto.

---

Caracteristicas

• 34 tipos de CFE soportados: e-Ticket, e-Factura, Notas de Credito/Debito, Exportacion, Venta por Cuenta Ajena, e-Boleta de Entrada, e-Remito, e-Resguardo y todos sus tipos de contingencia.
• Generacion XML contra namespace oficial http://cfe.dgi.gub.uy, ISO-8859-1, validacion XSD antes de firmar.
• Firma Electronica Avanzada XMLDSig con certificados PKI (RSA-SHA1 / RSA-SHA256).
• Web Services DGI: envio de sobres, consulta de estado, reporte diario, actualizacion de contactos. mTLS + WS-Security BinarySignature.
• Intercambio entre Emisores (peer-to-peer): WS SOAP v1.3 oficial DGI + canal alternativo por email con poll IMAP.
• CAE management: rangos por tipo de CFE, alertas de agotamiento.
• Multi-tenant / multi-empresa / multi-sucursal.
• Representacion impresa: PDF A4 y ticket 80mm con QR DGI, logo, colores y formato configurables por empresa.
• Reportes contables (PDF/Excel/TXT): emitidos, recibidos, por cliente, por proveedor, resguardos.
• API REST con autenticacion dual: API Key (sistemas integradores externos) o JWT Bearer (UI).
• Endpoint de provisioning para integraciones automaticas desde sistemas externos.
• Idempotency-Key support para retry-safe en POST de CFEs.
• Scheduler integrado para tareas recurrentes (cotizaciones BCU, reporte diario, intercambio EE, etc.).
• Exportaciones asincronicas con storage S3-compatible (AWS S3, MinIO, Backblaze B2, Cloudflare R2, etc.).

---

Stack

• Backend: Python 3.11+, FastAPI, SQLAlchemy 2.0 async, Pydantic v2
• Base de datos: PostgreSQL 16+
• XML / Firma: lxml, signxml, xmlsec
• SOAP: zeep
• PDF: ReportLab
• Scheduler: APScheduler
• Templates UI: Jinja2 + Tailwind (server-rendered)
• Container: Docker

---

Quick Start

Requisitos

• Docker y Docker Compose
• (Opcional para dev local sin docker) Python 3.11+, PostgreSQL 16+

Levantar con Docker

# 1. Clonar
git clone https://github.com/AvanceSoftware/LibreCFE.git
cd LibreCFE
# 2. Configurar variables
cp .env.example .env
# Editar .env y completar al menos:# JWT_SECRET (generar con: python -c "import secrets; print(secrets.token_hex(32))")# CERT_ENCRYPTION_KEY (generar con: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")# POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB# DATABASE_URL# 3. Levantarcd docker
docker compose up -d
# 4. Verificar
curl http://localhost:8000/health

La API estara en http://localhost:8000. La UI server-rendered en http://localhost:8000/ui/.

Dev local sin Docker

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"# Configurar PostgreSQL local y .env apuntando a el
alembic upgrade head
uvicorn app.main:app --reload

---

Arquitectura

LibreCFE/
├── app/
│ ├── main.py # FastAPI app
│ ├── config.py # Pydantic Settings
│ ├── api/v1/ # Endpoints REST por dominio
│ ├── models/ # SQLAlchemy ORM (35 tablas)
│ ├── schemas/ # Pydantic request/response
│ ├── services/ # Logica de dominio (XML, firma, DGI, intercambio, etc.)
│ ├── scheduler/ # APScheduler jobs
│ ├── templates/ # UI server-rendered (Jinja2)
│ ├── ui/ # Routes UI
│ └── xml/
│ ├── xsd/ # 19 XSD oficiales DGI v1.44.2
│ └── wsdl/ # WSDL DGI testing + produccion
├── alembic/ # Migraciones DB
├── tests/ # Pytest
├── docker/ # Dockerfile + compose + nginx
├── docs/ # Documentacion del proyecto
├── LICENSE # MIT
├── pyproject.toml
└── README.md

Flujo de un CFE

1. CAE valido (rango de numeracion autorizado por DGI por tipo)
2. Generar CFE XML (Encabezado + Detalle + CAEData)
3. Validar contra XSD oficial
4. Firmar (XMLDSig, certificado PKI persona juridica)
5. Armar Sobre (EnvioCFE, 1-250 CFEs)
6. Enviar a DGI por WS (no requiere autorizacion online para facturar)
7. Procesar respuesta asincrona de DGI (ACKSobre + ACKCFE)
8. Entregar al receptor (WS peer-to-peer o email)
9. Reporte diario a DGI con resumen

---

Modelo de datos

35 tablas principales:

Area	Tablas
Multi-tenant	empresas, sucursales, usuarios, usuarios_empresas, roles
Certificados	certificados (PKI per empresa)
CAE	caes
CFE emitidos	cfe_cabeceras + 8 hijas (detalles, retenciones, medios de pago, referencias, etc.)
CFE recibidos	cfe_recibidos (compras)
Sobres	sobres_dgi (a DGI), sobres_ee (peer-to-peer)
Reportes	resumenes_diarios + 4 hijas
Intercambio EE	bitacora_ee (eventos auditables)
Integracion	mapeo_codigo_sucursal, idempotency_keys
Padron	emisores_electronicos
Parametros	parametros_sistema, parametros_economicos (BCU)
Scheduler	scheduler_job_executions
Otros	anulacion_numero_pendiente, homologaciones, exportaciones_xml, retenciones_percepciones

---

Configuracion

Variables principales en .env:

Variable	Proposito
DATABASE_URL	Conexion a PostgreSQL
DGI_ENVIRONMENT	testing o produccion
JWT_SECRET	Secret para firmar JWT (REQUERIDO)
CERT_ENCRYPTION_KEY	Fernet key para cifrar passwords de PFX en BD (REQUERIDO en prod)
SERVICE_KEY_INTEGRATOR	Habilita /provisioning para sistemas integradores
SMTP_*	SMTP global outbound (opcional, fallback al SMTP per-empresa)
S3_*	Object storage para exportaciones (opcional)

Ver .env.example para el listado completo.

---

Tipos de CFE

Codigo	Tipo	Contingencia
101	e-Ticket	201
102	NC e-Ticket	202
103	ND e-Ticket	203
111	e-Factura	211
112	NC e-Factura	212
113	ND e-Factura	213
121-124	e-Factura/Remito Exportacion	221-224
131-133	e-Ticket Venta Cta. Ajena	231-233
141-143	e-Factura Venta Cta. Ajena	241-243
151-153	e-Boleta Entrada	251-253
181	e-Remito	281
182	e-Resguardo	282

---

Web Services DGI

Endpoints (configurables por ambiente)

• Testing: https://efactura.dgi.gub.uy/prueba/
• Produccion: https://efactura.dgi.gub.uy/
• RUC de prueba DGI: 219999830019

Operaciones

1. EFACRECEPCIONSOBRE — Envio de sobres con CFEs
2. EFACCONSULTARESTADOENVIO — Estado del envio
3. EFACCONSULTARESTADOCFE — Estado de un CFE puntual
4. EFACRECEPCIONREPORTE — Reporte diario
5. EFACSOLACTUALIZARCONTACTO — Actualizar contactos del emisor

WS Intercambio entre Emisores (peer-to-peer)

Cada emisor publica /ws_efactura_intercambio con 4 operaciones:

1. Sobre — recibir sobres con CFEs
2. RespuestaSobre — ACK del sobre
3. RespuestaCFEs — aceptacion/rechazo comercial
4. NotificacionAnulacionCFE — aviso de anulacion

---

Tests

pip install -e ".[dev]"
pytest tests/

Algunos tests requieren PostgreSQL local levantado.

---

Contribuir

Las contribuciones son bienvenidas. Antes de abrir un PR:

1. Leer el MANIFIESTO — alinea con el espiritu del proyecto.
2. Discutir cambios mayores en un issue antes de codear.
3. Mantener el alcance funcional (DGI Uruguay) — extensiones a otros paises pueden vivir como forks/repos satelite.
4. Tests para nueva funcionalidad. Linter limpio (ruff check .).
5. Sin secretos, dominios reales ni datos de cliente en commits.

---

Referencias

• Portal e-Factura DGI
• Documentos tecnicos DGI
• PKI Uruguay
• XMLDSig W3C

---

Licencia

MIT. Ver LICENSE.