Arquitectura de facturación electrónica multiempresa

Emitir un comprobante parece un flujo lineal, pero en una plataforma multiempresa intervienen aislamiento, numeración, firma, reintentos, reglas tributarias y trazabilidad. El objetivo no es sólo obtener una respuesta del proveedor: es poder demostrar quién emitió qué documento, con qué datos y cuál fue el resultado.

Resolver el tenant antes del negocio

El tenant se identifica al inicio mediante dominio, subdominio o membresía. Desde ese momento usuarios, permisos, sucursales, series, archivos, caché y trabajos en cola comparten el mismo contexto.

final class TenantContext
{
    public function __construct(public readonly Company $company) {}
}

No confío únicamente en filtros de interfaz. Las consultas, políticas y pruebas deben impedir que una empresa consulte documentos de otra, incluso modificando manualmente un identificador.

Separar venta, comprobante y transmisión

La venta es un hecho interno. El comprobante es su representación fiscal y la transmisión es una integración externa. Separarlos permite registrar la operación aunque el proveedor tributario esté caído.

Venta confirmada
  └─ Comprobante pendiente
       └─ Trabajo de envío
            ├─ aceptado
            ├─ observado
            └─ reintentable

El envío ocurre en una cola. La respuesta completa se conserva con datos sensibles protegidos y un identificador de correlación.

Numeración segura

Serie y correlativo requieren una operación transaccional. Dos solicitudes simultáneas no pueden recibir el mismo número.

START TRANSACTION;
SELECT next_number FROM document_series
WHERE company_id = ? AND series = ? FOR UPDATE;
UPDATE document_series SET next_number = next_number + 1 WHERE id = ?;
COMMIT;

Una clave idempotente enlaza el intento con el documento interno. Si el cliente repite la solicitud o la cola reintenta, se consulta el resultado existente en vez de emitir otro comprobante.

Estados y correcciones

Uso estados explícitos: borrador, pendiente, enviado, aceptado, observado, rechazado y anulado. Un rechazo no es lo mismo que un error temporal. Las notas de crédito y anulaciones se modelan como documentos relacionados, nunca editando el comprobante aceptado.

Prepararse para cambios

Las reglas tributarias evolucionan. Encapsulo cada proveedor detrás de un contrato propio y versiono catálogos, formatos y validaciones. Ventas e inventario no deberían conocer nombres de campos externos.

Finalmente, pruebo restauraciones, reenvíos, concurrencia y aislamiento entre tenants. En facturación, una arquitectura útil no sólo emite en el caso feliz: también explica y recupera cada estado intermedio.