Skip to main content

CFDI PDF

PyPI version Python Version License: MIT Typing CI / CD Coverage

Biblioteca profesional para convertir CFDI 4.0 XML a PDF con templates modernos y extensibles.

El PDF generado siempre se nombra con el UUID del timbre fiscal ({uuid}.pdf) y el tamaño de página es carta (8.5 × 11 in), estándar en México.

Características

  • CFDI 4.0 Completo: Soporte total para la versión 4.0 del SAT
  • Cadena original oficial: genera la cadena original con los XSLT del SAT (cadenaoriginal_4_0.xslt y cadenaoriginal_TFD_1_1.xslt empaquetados)
  • Verificación de sellos: SelloVerifier valida SelloCFD (certificado embebido) y SelloSAT (cert SAT) contra la cadena original
  • Validación XSD: validate_xsd=True valida contra el esquema oficial cfdv40.xsd (catálogos incluidos)
  • Complemento de Pago 2.0: modelos, parser y render dedicados
  • Complemento de Nómina 1.2: modelos, parser y render dedicados
  • Complemento de Carta Porte 3.1: modelos, parser y render dedicados
  • Tamaño carta: Todos los templates generan PDFs en tamaño carta (estándar SAT México)
  • Nombre por UUID: El archivo PDF siempre se nombra {uuid}.pdf para trazabilidad
  • QR SAT Oficial: Generación del código QR con especificaciones oficiales
  • 3 Templates incluidos: minimal, corporativo y clasico
  • Templates Extensibles: Sistema de templates basado en Jinja2 + HTML/CSS
  • Tipado Estricto: Pydantic v2 para validación robusta — Python 3.12+
  • Seguridad: Protección contra XXE, XML bombs y otros ataques
  • UTF-8 Completo: Manejo correcto de acentos, ñ y caracteres especiales
  • Catálogos SAT: Todos los catálogos oficiales del SAT
  • CLI Incluida: Herramienta de línea de comandos para conversiones rápidas

Instalación

pip install cfdi-pdf

Requiere Python 3.12 o superior.

Uso Rápido

CLI (Línea de Comandos)

# Un archivo — guarda {uuid}.pdf en el mismo directorio que el XML
cfdi-pdf factura.xml

# Directorio de salida personalizado
cfdi-pdf factura.xml --output-dir ./pdfs

# Procesamiento por lotes
cfdi-pdf enero/*.xml --output-dir ./pdfs

# Con logo y template
cfdi-pdf factura.xml --template corporativo --logo logo.png

# Ver templates disponibles
cfdi-pdf --list-templates

# Salida detallada
cfdi-pdf factura.xml --verbose

El comando imprime la ruta completa del PDF generado:

✓ factura.xml → /ruta/al/cce4d168-1234-5678-9abc-def012345678.pdf

API Python

from cfdi_pdf import CFDIPDF

pdf = CFDIPDF(template="minimal")

# Convierte y guarda {uuid}.pdf en el mismo directorio del XML
output_path = pdf.render(xml_path="factura.xml")
print(output_path)  # PosixPath('/ruta/cce4d168-...-uuid.pdf')

# Especificar directorio de salida
output_path = pdf.render(xml_path="factura.xml", output_dir="./pdfs")

# Con logo
output_path = pdf.render(
    xml_path="factura.xml",
    output_dir="./pdfs",
    logo_path="logo.png",
)

Desde string XML

from cfdi_pdf import CFDIPDF

pdf = CFDIPDF()

with open("factura.xml") as f:
    xml_content = f.read()

# Guarda {uuid}.pdf en el directorio indicado
output_path = pdf.render_from_string(xml_content, output_dir="./pdfs")

Obtener bytes (sin escribir a disco)

from cfdi_pdf import CFDIPDF

pdf = CFDIPDF()

# Retorna (bytes, nombre_archivo) sin tocar el sistema de archivos
pdf_bytes, filename = pdf.render_bytes(xml_path="factura.xml")

# filename = "cce4d168-1234-5678-9abc-def012345678.pdf"
# Útil para APIs web, S3, etc.
with open(filename, "wb") as f:
    f.write(pdf_bytes)

Desde string XML y obtener bytes (sin disco)

from cfdi_pdf import CFDIPDF

pdf = CFDIPDF()

with open("factura.xml") as f:
    xml_content = f.read()

# Retorna (bytes, nombre_archivo) sin tocar el sistema de archivos
pdf_bytes, filename = pdf.render_bytes_from_string(xml_content)

# Ideal para exponer la librería detrás de un framework web (FastAPI, etc.)

La librería es 100% pura: no depende de ningún framework web. Para usarla en un microservicio, ver el adaptador de ejemplo en examples/fastapi_service.py.

Templates Disponibles

Template Descripción Compatibilidad
minimal Diseño limpio y moderno (por defecto) WeasyPrint, Chromium
corporativo Azul corporativo #1a3a5c, encabezado destacado WeasyPrint, Chromium
clasico Blanco/negro, tipografía Times, máxima compatibilidad WeasyPrint, Chromium, wkhtmltopdf

Todos los templates:

  • Tamaño carta (8.5 × 11 in / 215.9 × 279.4 mm)
  • Sin propiedades CSS experimentales (compatible con motores de impresión estrictos)
  • Layout con tablas HTML en secciones fiscales (compatible con wkhtmltopdf)
  • Zebra striping con clases explícitas (no :nth-child)

Seleccionar template

from cfdi_pdf import CFDIPDF

pdf = CFDIPDF(template="corporativo")
output_path = pdf.render(xml_path="factura.xml")
cfdi-pdf factura.xml --template clasico

API de Referencia

CFDIPDF

CFDIPDF(
    template: str = "minimal",
    custom_template_paths: list[str | Path] | None = None,
    validate_xsd: bool = False,
    validate_catalogs: bool = False,
    max_xml_size: int | None = 10_000_000,
    on_render: Callable[[CFDI, str], None] | None = None,
)
Método Descripción Retorna
render(xml_path, output_dir, template, logo_path) Convierte XML a PDF, guarda en disco Path al PDF
render_from_string(xml_content, output_dir, template, logo_path) Igual pero desde string Path al PDF
render_bytes(xml_path, template, logo_path) Sin escribir a disco (bytes, filename)
render_bytes_from_string(xml_content, template, logo_path) Desde string, sin escribir a disco (bytes, filename)
parse(xml_path) Parsea XML sin generar PDF CFDI
parse_string(xml_content) Parsea string XML CFDI
list_templates() Lista templates disponibles list[str]

Nota: El nombre del archivo siempre es {uuid}.pdf (UUID en minúsculas del timbre fiscal). Si el CFDI no tiene timbre fiscal, se lanza CFDIPDFError.

Cadena original, sellos y validación XSD

El parser calcula la cadena original del comprobante y del timbre con los XSLT oficiales del SAT (cadenaoriginal_4_0.xslt y cadenaoriginal_TFD_1_1.xslt, empaquetados en cfdi_pdf/xslt/).

from cfdi_pdf import CFDIPDF, SelloVerifier

pdf = CFDIPDF(validate_xsd=True)  # valida contra cfdv40.xsd durante el parseo
cfdi = pdf.parse("factura.xml")

print(cfdi.cadena_original)  # cadena original del comprobante
print(cfdi.timbre_fiscal.cadena_origen)  # cadena original del TFD

# Verificar la firma del emisor contra su certificado embebido
if SelloVerifier.verify_sello_cfd(cfdi):
    print("✓ SelloCFD válido")

# Verificar la firma del SAT (requiere el certificado del SAT, identificado
# por NoCertificadoSAT)
if SelloVerifier.verify_sello_sat(cfdi, sat_certificate_pem):
    print("✓ SelloSAT válido")

Nota: la verificación de SelloSAT requiere el certificado X.509 del SAT (no viene embebido en el XML). Se puede pasar explícitamente o dejar el certificado en el store (~/.cache/cfdi-pdf/certs/ o la variable CFDI_PDF_SAT_CERTS_DIR); entonces se busca automáticamente por NoCertificadoSAT:

if SelloVerifier.verify_sello_sat(cfdi):  # busca en el store
    print("✓ SelloSAT válido")

Validación de catálogos (sin XSD)

from cfdi_pdf import CFDIPDF

pdf = CFDIPDF(validate_catalogs=True)  # valida claves SAT (moneda, régimen, uso CFDI…)
cfdi = pdf.parse("factura.xml")  # lanza InvalidCFDIError si alguna clave es inválida

Complementos soportados

Además de Pagos 2.0, Nómina 1.2 y Carta Porte 3.1, se modelan Leyendas Fiscales, IEPS e Información Global (se renderizan en los templates). La cfdi:Addenda se detecta (cfdi.has_addenda) pero se ignora por seguridad: es XML arbitrario del emisor, sin valor fiscal.

Procesamiento por lotes y rendimiento

render_batch() procesa varios XML reutilizando la instancia (templates compilados una sola vez) y puede paralelizar WeasyPrint con múltiples procesos:

from cfdi_pdf import CFDIPDF

pdf = CFDIPDF()
results = pdf.render_batch(
    ["enero/a.xml", "enero/b.xml"],
    output_dir="./pdfs",
    workers=4,  # None/1 = secuencial; >1 = multiproceso
)

for result in results:
    # BatchResult(source, output | None, error | None)
    print(result.source.name, result.output or result.error)

Telemetría (logging JSON + hook de post-render)

Para entornos de servicio, emite logs en una línea JSON por evento:

from cfdi_pdf.utils.logging import setup_json_logging

setup_json_logging()  # los logs de cfdi_pdf.* salen como JSON a stdout

Y registra cada render con un hook on_render(cfdi, output):

from cfdi_pdf import CFDIPDF


def track(cfdi, output):
    print("uuid:", cfdi.timbre_fiscal.uuid, "->", output)


pdf = CFDIPDF(on_render=track)

Recursos del SAT (XSLT/XSD) — descarga en runtime

La biblioteca no empaqueta los XSLT/XSD del SAT (son grandes y el SAT los actualiza con frecuencia). Se descargan bajo demanda, se cachean en disco y se verifican por SHA-256 contra un manifiesto empaquetado:

  • Origen: primero www.sat.gob.mx; si está bloqueado (geo-bloqueo), un mirror verificado. Configurables con CFDI_PDF_BASE_URLS.
  • Caché: ~/.cache/cfdi-pdf (configurable con CFDI_PDF_CACHE_DIR).
  • Predescarga para deploys sin red:
    cfdi-pdf --download-resources        # XSLT de la cadena original (~400 KB)
    cfdi-pdf --download-resources --all  # + esquemas XSD incl. catálogos (~7 MB)
    
    o desde Python: CFDIPDF().ensure_resources(all_resources=True).

Si el SAT actualiza un archivo, el hash no coincidirá y se lanza SATResourceError con el hash nuevo (detecta el cambio en vez de usar contenido no verificado). Ver doc/seguridad.md para los detalles de procedencia y el proceso de actualización del manifiesto.

Variables disponibles en templates Jinja2

Variable Tipo Descripción
cfdi CFDI Objeto completo del CFDI
formatted.uuid str UUID formateado
formatted.fecha str Fecha de expedición
formatted.fecha_timbrado str | None Fecha de timbrado
formatted.total str Total formateado con moneda
formatted.sub_total str Subtotal formateado
formatted.descuento str | None Descuento formateado
formatted.sello_cfd str | None Sello CFD completo, dividido en líneas de 64 chars
formatted.sello_sat str | None Sello SAT completo, dividido en líneas de 64 chars
catalogs.tipo_comprobante str Descripción del tipo
catalogs.forma_pago str Descripción forma de pago
catalogs.metodo_pago str Descripción método de pago
catalogs.uso_cfdi str Descripción uso CFDI
catalogs.regimen_fiscal_emisor str Régimen del emisor
catalogs.regimen_fiscal_receptor str Régimen del receptor
catalogs.moneda str Descripción de moneda
qr_data str QR SAT en base64 (PNG)
logo_data str Logo en base64 data URL
cadena_original str Cadena original del timbre
format_currency(amount, moneda) callable Formatea importe
format_tax_rate(rate) callable Formatea tasa de impuesto

Crear Template Personalizado

  1. Crea un directorio con el nombre de tu template:
mis_templates/
└── mi_empresa/
    ├── template.html
    └── styles.css
  1. styles.css — usa siempre tamaño carta:
@page {
    size: letter;          /* 8.5 × 11 in — tamaño carta México */
    margin: 15mm 15mm 20mm 15mm;
}
  1. template.html — usa las variables Jinja2 estándar:
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <h1>{{ catalogs.tipo_comprobante }}</h1>
    <p>UUID: {{ formatted.uuid }}</p>
    <p>Emisor: {{ cfdi.emisor.nombre }}</p>
    <p>Total: {{ formatted.total }}</p>
    {% if qr_data %}
        <img src="data:image/png;base64,{{ qr_data }}" alt="QR SAT">
    {% endif %}
</body>
</html>
  1. Registra la ruta y usa tu template:
from pathlib import Path
from cfdi_pdf import CFDIPDF

pdf = CFDIPDF(
    template="mi_empresa",
    custom_template_paths=[Path("./mis_templates")],
)
output_path = pdf.render(xml_path="factura.xml")

Estructura del Proyecto

.
├── src/cfdi_pdf/     # Código de la biblioteca
├── tests/            # Suite de tests (pytest)
├── examples/         # Ejemplos de uso (incluye integración FastAPI)
├── doc/              # Auditoría y documentación técnica
│   ├── analisis.md   #   Arquitectura y decisiones de diseño
│   ├── hallazgos.md  #   Bugs/defectos priorizados
│   ├── mejoras.md    #   Mejoras recomendadas
│   ├── seguridad.md  #   Análisis de seguridad y procedencia SAT
│   └── calidad.md    #   Tests, cobertura y CI
└── pyproject.toml

Detalle del paquete:

src/cfdi_pdf/
├── api.py              # API principal (CFDIPDF)
├── cli.py              # Interfaz de línea de comandos
├── exceptions.py       # Excepciones personalizadas
├── crypto/             # Verificación de sellos
│   └── verifier.py     #   SelloVerifier (RSA/SHA-256)
├── models/             # Modelos Pydantic v2
│   ├── cfdi.py
│   ├── emisor.py
│   ├── receptor.py
│   ├── concepto.py
│   ├── impuestos.py
│   ├── timbre.py
│   ├── pagos.py        #   Complemento de Pago 2.0
│   ├── nomina.py       #   Complemento de Nómina 1.2
│   └── carta_porte.py  #   Complemento de Carta Porte 3.1
├── parser/             # Parser XML seguro
│   ├── xml_parser.py
│   ├── sanitizer.py
│   └── xsd_validator.py #  Validación contra cfdv40.xsd
├── qr/                 # Generador QR SAT oficial
│   └── generator.py
├── render/             # Motor de renderizado
│   ├── engine.py
│   └── template.py
├── sat/                # Catálogos SAT
│   ├── catalogs.py
│   ├── helpers.py
│   ├── cadena_original.py  # XSLT oficiales (cadena original)
│   └── resources.py        # Descarga runtime + verificación SHA-256
├── utils/              # Utilidades
│   └── formatters.py
└── templates/          # Templates incluidos
    ├── minimal/
    │   ├── template.html
    │   └── styles.css
    ├── corporativo/
    │   ├── template.html
    │   └── styles.css
    └── clasico/
        ├── template.html
        └── styles.css

Requisitos

  • Python 3.12+
  • WeasyPrint >= 60.0
  • Pydantic >= 2.0.0
  • Jinja2 >= 3.1.0
  • qrcode >= 7.4
  • Pillow >= 10.0.0
  • lxml >= 5.0.0
  • cryptography >= 41.0.0

Desarrollo

Configuración del Entorno

git clone https://github.com/jesusmrv81/xmltopdf.git
cd xmltopdf

python -m venv venv
source venv/bin/activate      # Linux/macOS
# venv\Scripts\activate       # Windows

pip install -e ".[dev]"

# Predescargar los recursos del SAT (XSLT/XSD) para la cadena original y la
# validación XSD; de lo contrario se descargan en la primera ejecución
cfdi-pdf --download-resources --all

Las dependencias se fijan en requirements.lock (con hashes) para reproducibilidad de CI/deploys. Para regenerarlo:

pip-compile pyproject.toml --extra dev --generate-hashes -o requirements.lock

Ejecutar Tests

# Todos los tests
pytest

# Con cobertura HTML
pytest --cov=cfdi_pdf --cov-report=html

# Tests específicos
pytest tests/test_parser.py -v

Linting y Formateo

ruff check .          # linter
ruff check --fix .    # auto-fix
ruff format .         # formatter (incluye bloques de código en Markdown)
mypy src              # type checker

Build

python -m build
twine upload dist/*   # requiere credenciales PyPI

Especificaciones Técnicas

CFDI 4.0

  • Namespace: http://www.sat.gob.mx/cfd/4
  • Timbre Fiscal Digital: Versión 1.1
  • Catálogos SAT: Completos y actualizados

QR SAT

URL de verificación: https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx

Parámetros: id (UUID), re (RFC emisor), rr (RFC receptor), tt (total 6 decimales), fe (últimos 8 chars del sello).

Seguridad

  • Protección XXE: resolve_entities=False en lxml
  • XML Bombs: no_network=True, huge_tree=False
  • Sandboxing: SandboxedEnvironment de Jinja2
  • Sanitización: Regex compilado contra caracteres inválidos XML 1.0

Compatibilidad CSS

Los templates evitan intencionalmente propiedades CSS experimentales para máxima compatibilidad con motores de impresión:

Propiedad Estado
@page size: letter Soportado en todos
display: table Soportado en todos
display: flex Solo en zonas decorativas no-fiscales
display: grid No usado
CSS variables (var(--)) No usado
:nth-child en tablas No usado — zebra con clases explícitas
border-radius (clasico) No usado

Roadmap

  • Soporte para complemento Pagos 2.0
  • Soporte para complemento Nómina 1.2
  • Soporte para complemento Carta Porte 3.1 (subconjunto esencial)
  • Cadena original oficial del SAT (XSLT) y validación contra esquemas XSD
  • Validación de sellos contra el SAT (verificación completa SelloSAT con certificados del SAT actualizados)
  • API REST lista para deploy (ver ejemplo examples/fastapi_service.py)
  • Integración con PACs

Licencia

MIT License — ver archivo LICENSE para detalles.

Soporte


Nota: Esta biblioteca no está afiliada oficialmente con el SAT. Verifica siempre la validez de los CFDIs en el portal oficial del SAT.

Metadata

Release files for cfdi-pdf 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cfdi-pdf 0.3.0
File Size Uploaded Provenance Actions
cfdi_pdf-0.3.0.tar.gz 94.8 kB With provenance Details for cfdi_pdf-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cfdi-pdf 0.3.0
File Interpreter ABI Platform Actions
cfdi_pdf-0.3.0-py3-none-any.whl Python 3 none any Details for cfdi_pdf-0.3.0-py3-none-any.whl

Total release size: 182.5 kB

Release files / cfdi_pdf-0.3.0.tar.gz

Download URL cfdi_pdf-0.3.0.tar.gz
Size 94.8 kB
Tags Source
SHA-256 checksum
How to use checksums
193a05bd265e701948bb0ed4b0bf85e5575f96dc9dae51753a9ee9b40423c177
BLAKE2b-256 checksum
How to use checksums
08036b363cddfb701cab9b7ae387c6ea501439fd2c1829642d7373b42409ae70
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 10, 2026.

Transparency log

Release files / cfdi_pdf-0.3.0-py3-none-any.whl

Download URL cfdi_pdf-0.3.0-py3-none-any.whl
Size 87.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9fc0077506059d0bb7d10d46174704c9bce30710c1d46c804090c7b62abf8cb8
BLAKE2b-256 checksum
How to use checksums
c1cd956384358d5db62df2a1b665965dcbfa642040497ea2bfaf1166d976a3fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 10, 2026.

Transparency log

Security for cfdi-pdf 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cfdi_pdf-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page