API de facturación con registros encadenados

Problema

Cada aplicación que factura acaba reimplementando lo mismo: series, numeración, cálculo de impuestos, PDF y registro de lo ocurrido. Reimplementarlo cinco veces significa cinco sitios donde el redondeo puede diferir.

Decisión

Un único servicio donde se emite una factura. Las aplicaciones piden; no calculan.

Una factura emitida no se actualiza ni se borra: se corrige emitiendo una rectificativa. Cada registro guarda el hash del anterior, de forma que la cadena entera es verificable y cualquier manipulación directa de la base de datos queda a la vista.

Implementación

Los importes se guardan en céntimos como enteros, nunca en coma flotante. El redondeo se aplica por tipo impositivo agregado, no línea a línea, que es el criterio de la AEAT y donde aparecen las diferencias de un céntimo en cuanto una factura tiene veinte líneas.

La numeración es correlativa y sin huecos por serie y año, con el contador incrementado dentro de una transacción con bloqueo. Si falla la generación del PDF, la factura ya existe: se reintenta el PDF, no se devuelve el número.

El PDF se renderiza en HTML y se convierte en un contenedor de Gotenberg aparte; el resultado se guarda en almacenamiento S3 y se sirve mediante URL firmada con caducidad.

El servicio no está expuesto a internet: solo es alcanzable desde la red privada de Docker, de forma que el componente que custodia los registros fiscales no tiene puerta pública.