API de facturación con registros encadenados

Por qué un servicio y no una librería

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.

La API es el único punto donde se emite una factura. Las aplicaciones piden; no calculan.

Inmutabilidad y cadena de hash

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.

Es el modelo que exige Verifactu (RD 1007/2023) y, a la vez, la manera de que la palabra "auditoría" signifique algo más que una tabla de logs.

Decisiones de cálculo

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.

Generación del PDF

La plantilla se renderiza en HTML con los mismos tokens de diseño que el resto de aplicaciones y se convierte a PDF en un contenedor de Gotenberg aparte. El resultado se guarda en almacenamiento S3 y se sirve mediante URL firmada con caducidad.

Superficie de ataque

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.