Toda plataforma de pagos necesita facturas. Son el rastro documental del que dependen comerciantes, contadores y autoridades fiscales. En 0fee.dev, el sistema de facturas va más allá de simples recibos -- produce documentos PDF profesionales y con marca que los comerciantes pueden enviar directamente a sus clientes.
Modelo de datos de facturas
Una factura en 0fee.dev está vinculada a una transacción pero vive como su propia entidad con su propio ciclo de vida. El formato de referencia está diseñado para auditoría multi-aplicación: {REF}-{AAMMDD}-{APP_SLUG}-{XXXX}.
Plantilla HTML profesional de facturas
El PDF se genera a partir de una plantilla HTML estilizada con CSS. Elegimos HTML-a-PDF sobre bibliotecas PDF directas porque HTML es más fácil de diseñar, mantener y personalizar. La plantilla incluye encabezado con logo del comerciante, información de partes (emisor y destinatario), tabla de artículos con cantidades y precios, totales con impuestos y pie de página.
Generación de PDF con WeasyPrint
Elegimos WeasyPrint para la conversión HTML-a-PDF. Es una biblioteca Python que renderiza HTML/CSS a PDF con excelente soporte CSS, incluyendo flexbox, fuentes personalizadas y estilos a nivel de página.
| Biblioteca | Pros | Contras | Veredicto |
|---|---|---|---|
| WeasyPrint | Python puro, soporte CSS3, sin dependencia de navegador | Más lento que wkhtmltopdf, deps del sistema | Elegido -- mejor soporte CSS |
| wkhtmltopdf | Rápido, maduro | WebKit headless, binario grande | Rechazado |
| Puppeteer/Playwright | Renderizado Chrome completo | Dependencia Node.js, pesado | Rechazado |
| ReportLab | PDF nativo, rápido | Posicionamiento manual, sin HTML/CSS | Rechazado |
Búsqueda y filtro
El endpoint de listado de facturas soporta búsqueda de texto completo y filtrado multi-parámetro: texto en referencia/nombre/email del cliente, estado, rango de fechas, rango de montos y paginación.
Endpoint de duplicación
Los comerciantes frecuentemente necesitan crear facturas similares. El endpoint de duplicación copia una factura existente con una nueva referencia y fecha.
Envío por correo vía SMSING API
Las facturas se envían por correo a los clientes usando la SMSING API (un servicio africano de envío de email/SMS), con el PDF adjunto codificado en base64.
Marca del comerciante desde configuración de la app
Cada app puede personalizar la apariencia de sus facturas a través de la configuración: nombre de empresa, dirección, logo, ID fiscal, color de marca. La marca se captura al momento de creación de la factura para que cambios posteriores no alteren facturas existentes.
Lo que aprendimos
- Las facturas son una señal de confianza. Los comerciantes que pueden enviar facturas profesionales con marca son percibidos como más legítimos por sus clientes.
- El formato de referencia importa para la auditoría. Incluir el slug de la app y la fecha en la referencia hace posible la auditoría multi-aplicación sin abrir cada factura.
- WeasyPrint es la compensación correcta. Es más lento que alternativas binarias pero la flexibilidad CSS lo vale. Un renderizado de PDF de 200ms es perfectamente aceptable.
- Captura la marca al momento de creación. Si renderizas dinámicamente la marca al generar el PDF, cambiar un logo retroactivamente cambia todas las facturas pasadas.
- La búsqueda no es negociable. Una vez que un comerciante tiene más de 100 facturas, poder buscar por referencia, nombre o rango de fechas pasa de ser algo deseable a esencial.
Este artículo es parte de la serie "Cómo construimos 0fee.dev". 0fee.dev es un orquestador de pagos que cubre más de 53 proveedores en más de 200 países, construido por Juste Thales Gnimavo y Claude desde Abiyán sin ingenieros humanos. Sigue la serie para conocer la historia completa de la construcción.