CFDI.BuildPdf 2.0.8

📦 CFDI.BuildPdf

Descripción general

CFDI.BuildPdf es una librería .NET 6+ que genera una representación impresa en PDF a partir de un XML CFDI 4.0. Detecta automáticamente el tipo de complemento y soporta actualmente:

• Complemento Carta Porte 3.1
• Complemento Nómina 1.2

Es cross-platform (Windows, Linux, macOS, contenedores) y no tiene dependencias nativas: usa QuestPDF como motor de renderizado y QRCoder para el código QR del timbre fiscal.

📥 Instalación

dotnet add package CFDI.BuildPdf

🚀 Características

• ✔️ Soporte para CFDI 4.0 con complementos Carta Porte 3.1 y Nómina 1.2.
• ✔️ Detección automática del tipo de complemento.
• ✔️ Traducción automática de claves SAT (c_FormaPago, c_RegimenFiscal, c_UsoCFDI, c_TipoDeComprobante, c_TipoRelacion, etc.): el PDF muestra clave - descripción legible en lugar de códigos crudos. Ver CATALOGOS_SAT_MAPEADOS.md.
• ✔️ Catálogos del Complemento Nómina 1.2 traducidos: c_TipoContrato, c_TipoRegimen, c_PeriodicidadPago, c_RiesgoPuesto, c_Estado, c_TipoPercepcion, c_TipoDeduccion, c_TipoOtroPago, c_TipoIncapacidad, c_TipoHoras.
• ✔️ Soporte para <cfdi:CfdiRelacionados>: render condicional de los UUIDs relacionados con su TipoRelacion descrito.
• ✔️ Identificación del PAC timbrador por RFC (Buzón E, InvoiceOne, SAT pruebas; ampliable).
• ✔️ Múltiples formatos de entrada: ruta de archivo, string, byte[] y Stream.
• ✔️ Escritura directa a archivo o Stream de salida (ideal para respuestas HTTP).
• ✔️ Opciones configurables: mostrar/ocultar mercancías, condiciones del contrato, addenda; logotipo en Base64; orientación portrait/landscape.
• ✔️ Inyección de dependencias con Microsoft.Extensions.DependencyInjection.
• ✔️ Integración opcional con ILogger para diagnóstico.
• ✔️ Excepciones de dominio claras (CfdiXmlInvalidoException, CfdiComplementoNoSoportadoException).

📁 Estructura del PDF generado

• Datos del emisor y receptor (con Régimen Fiscal traducido).
• Datos de Emisión: fecha, serie/folio, moneda, tipo de cambio, lugar de expedición, Exportación (traducida) y sub-bloque CFDI Relacionados cuando el XML lo incluye.
• Forma / Método de Pago: con FormaPago, MetodoPago y TipoDeComprobante traducidos.
• Conceptos facturados: clave producto/servicio, ClaveUnidad traducida, descripción, importes formateados (N2 es-MX), descuentos y ObjetoImp descrito.
• Totales e impuestos (c_Impuesto: 001 ISR, 002 IVA, 003 IEPS).
• Addenda genérica (opcional).
• Complemento Carta Porte: ubicaciones, mercancías (detalle o resumen), autotransporte (c_TipoPermiso, c_ConfigAutotransporte descritos), seguros, remolques (c_SubTipoRem descrito), figuras de transporte (c_FiguraTransporte descrito), página de condiciones del contrato.
• Complemento Nómina: datos del empleado, percepciones, deducciones, otros pagos, incapacidades, totales.
• Bloque fiscal: UUID, fechas, certificados, PAC que timbró identificado por RFC.
• QR y sellos digitales (sello CFDI, sello SAT, cadena original del complemento de certificación).

⚠️ Licencia QuestPDF (léeme antes de producción)

Esta librería usa QuestPDF, que tiene licencia dual:

• Community (gratuita) — apta para la mayoría de proyectos open-source y empresas que cumplan los criterios de elegibilidad vigentes del proveedor.
• Professional / Enterprise (de pago) — requerida por QuestPDF para el resto de organizaciones.

El consumidor de esta librería es responsable de elegir y adquirir la licencia correcta. Consulta los términos vigentes en https://www.questpdf.com/license/.

Por defecto, CFDI.BuildPdf declara Community. Para cambiarlo:

Con la fachada estática

using CFDI.BuildPdf.Abstractions;
using CFDI.BuildPdf.Service;

// Llamar una sola vez al iniciar el proceso, antes de generar cualquier PDF
CfdiPdf.ConfigureQuestPdfLicense(CfdiPdfLicenseType.Professional);

Con inyección de dependencias

builder.Services.AddCfdiPdfServices(
    configure: opts => opts.MostrarMercancias = true,
    licenseType: CfdiPdfLicenseType.Professional);

📚 Requisitos

• .NET 6.0 o superior.
• Sin dependencias nativas (no requiere wkhtmltopdf ni binarios de sistema).

🔵 Uso básico (fachada estática)

Desde una ruta de archivo

using CFDI.BuildPdf.Service;

var pdfBytes = await CfdiPdf.DesdeRutaAsync(@"C:\facturas\cfdi.xml");
await File.WriteAllBytesAsync("cfdi_output.pdf", pdfBytes);

Desde un string XML

var pdfBytes = await CfdiPdf.DesdeXmlStringAsync(xmlString);

Desde bytes

var pdfBytes = await CfdiPdf.DesdeXmlBytesAsync(xmlBytes);

Desde un Stream (por ejemplo, IFormFile en ASP.NET Core)

await using var stream = archivoXml.OpenReadStream();
var pdfBytes = await CfdiPdf.DesdeStreamAsync(stream);

Guardar directamente a archivo

await CfdiPdf.GuardarDesdeRutaAsync(
    rutaXml: @"C:\facturas\cfdi.xml",
    rutaPdfDestino: @"C:\facturas\cfdi.pdf");

Escribir en un Stream de salida (respuesta HTTP)

[HttpPost("generar-pdf")]
public async Task<IActionResult> GenerarPdf(IFormFile xml)
{
    Response.ContentType = "application/pdf";
    await using var xmlStream = xml.OpenReadStream();
    await CfdiPdf.EscribirEnStreamAsync(xmlStream, Response.Body);
    return new EmptyResult();
}

🗂️ Traducción automática de catálogos SAT

El PDF traduce las claves del SAT a su descripción legible en tiempo de render — no necesitas pre-procesar el XML. Ejemplos del output:

Si una clave no está en el catálogo embebido se renderiza tal cual (fallback seguro, sin excepción). Catálogos soportados (23 helpers / 36 campos): c_ClaveUnidad, c_Impuesto, c_ObjetoImp, c_UsoCFDI, c_RegimenFiscal, c_FormaPago, c_MetodoPago, c_Exportacion, c_TipoDeComprobante, c_TipoRelacion, c_CveTransporte, c_TipoPermiso, c_ConfigAutotransporte, c_SubTipoRem, c_FiguraTransporte, c_TipoContrato, c_TipoRegimen, c_PeriodicidadPago, c_RiesgoPuesto, c_Estado, c_TipoPercepcion, c_TipoDeduccion, c_TipoOtroPago, c_TipoIncapacidad, c_TipoHoras. Inventario completo en CATALOGOS_SAT_MAPEADOS.md.

Agregar un PAC propio al diccionario

El RFC del PAC se traduce a nombre comercial para mostrarlo en el bloque fiscal. Si tu PAC no está en el diccionario embebido, el PDF mostrará "PAC no identificado". Envía un PR agregando la entrada en PdfBuilders/Common/CfdiPdfSections.cs (diccionario PacsConocidos) o ábrenos un issue con el RFC y nombre comercial.

⚙️ Opciones de generación

var options = new CfdiPdfOptions
{
    MostrarMercancias = true,            // Carta Porte: mostrar detalle de mercancías
    MostrarCondicionesContrato = true,   // Carta Porte: incluir página de condiciones
    MostrarAddenda = true,               // Incluir sección de addenda
    LogoBase64 = logoBase64,             // Logo de la empresa (opcional)
    Orientacion = PdfOrientation.Portrait
};

var pdfBytes = await CfdiPdf.DesdeRutaAsync(rutaXml, options);

💉 Uso con inyección de dependencias

Registro de servicios

using CFDI.BuildPdf.Abstractions;
using CFDI.BuildPdf.Configuration;

builder.Services.AddCfdiPdfServices(
    configure: opts =>
    {
        opts.MostrarMercancias = true;
        opts.MostrarCondicionesContrato = true;
    },
    licenseType: CfdiPdfLicenseType.Community);

Consumo desde un servicio

using CFDI.BuildPdf.Abstractions;

public class FacturaService
{
    private readonly ICfdiPdfGenerator _generator;

    public FacturaService(ICfdiPdfGenerator generator)
    {
        _generator = generator;
    }

    public Task<byte[]> GenerarPdfAsync(string rutaXml)
        => _generator.GenerarDesdeRutaAsync(rutaXml);
}

🛑 Manejo de errores

Los métodos públicos lanzan excepciones de dominio específicas para facilitar el diagnóstico:

try
{
    var pdf = await CfdiPdf.DesdeRutaAsync(ruta);
}
catch (CfdiXmlInvalidoException ex)
{
    logger.LogWarning(ex, "XML no válido: {Mensaje}", ex.Message);
}
catch (CfdiComplementoNoSoportadoException ex)
{
    logger.LogWarning(ex, "Complemento no soportado: {Mensaje}", ex.Message);
}

📝 Licencia

Este proyecto está bajo licencia MIT. Recuerda que QuestPDF (dependencia interna) tiene su propia licencia dual — ver sección arriba.

👤 Autor

• @Juliocbm