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.
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.
- 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.).
- 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
- Docker y Docker Compose
- (Opcional para dev local sin docker) Python 3.11+, PostgreSQL 16+
# 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. Levantar
cd docker
docker compose up -d
# 4. Verificar
curl http://localhost:8000/healthLa API estara en http://localhost:8000. La UI server-rendered en http://localhost:8000/ui/.
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 --reloadLibreCFE/
├── 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
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
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 |
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.
| 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 |
- Testing:
https://efactura.dgi.gub.uy/prueba/ - Produccion:
https://efactura.dgi.gub.uy/ - RUC de prueba DGI:
219999830019
EFACRECEPCIONSOBRE— Envio de sobres con CFEsEFACCONSULTARESTADOENVIO— Estado del envioEFACCONSULTARESTADOCFE— Estado de un CFE puntualEFACRECEPCIONREPORTE— Reporte diarioEFACSOLACTUALIZARCONTACTO— Actualizar contactos del emisor
Cada emisor publica /ws_efactura_intercambio con 4 operaciones:
Sobre— recibir sobres con CFEsRespuestaSobre— ACK del sobreRespuestaCFEs— aceptacion/rechazo comercialNotificacionAnulacionCFE— aviso de anulacion
pip install -e ".[dev]"
pytest tests/Algunos tests requieren PostgreSQL local levantado.
Las contribuciones son bienvenidas. Antes de abrir un PR:
- Leer el MANIFIESTO — alinea con el espiritu del proyecto.
- Discutir cambios mayores en un issue antes de codear.
- Mantener el alcance funcional (DGI Uruguay) — extensiones a otros paises pueden vivir como forks/repos satelite.
- Tests para nueva funcionalidad. Linter limpio (
ruff check .). - Sin secretos, dominios reales ni datos de cliente en commits.
MIT. Ver LICENSE.