Arquitectura

Zentto Imprenta Digital se implementa como el microservicio zentto-imprenta-seniat (Node/Express + TypeScript + PostgreSQL), que actúa como gateway de emisión fiscal. El sistema cliente (ERP, POS o un integrador) construye un documento canónico y lo envía al gateway; Zentto genera el número de control NCF-D desde sus series propias, encadena el registro con hash SHA-256 y persiste el resultado.

Componentes

Componente	Descripción
Sistema cliente (ERP / POS / Integrador)	Construye el documento canónico y consume el gateway. Persiste el número de control y los datos de consulta.
Gateway /v1/fiscal/gateway	Capa de operaciones fiscales: ping, emit, status, download, annul, numbering/assign, numbering/query. Autenticado por X-API-Key (canal interno).
Dominio /v1/imprenta	API del vertical web: dashboard, sucursales, puntos de facturación, numeraciones, asignaciones, documentos, reportes, usuarios, auditoría, configuración. Autenticado por JWT de zentto-auth.
Backoffice /v1/imprenta/backoffice	Administración de series propias, metering (consumo facturable), tarifas, integradores, distribuidores y comisiones.
API de Integradores /api/*	API pública para terceros: autenticación tokenUsuario+secret → JWT corto; emisión contra series propias.
Generación propia (provider propio)	Asigna el NCF-D localmente desde imprenta."ControlSerie", encadena con hash SHA-256 y registra el evento facturable en imprenta."ConsumoControl".
Endpoints SENIAT /seniat/*	Consulta de solo lectura (por NCF-D, listado, libro de ventas) protegida con X-Seniat-Key.
Cola de transmisión	fiscal."SeniatDispatch" — reintento con backoff exponencial (fn_backoff_next) hacia el SENIAT.

Principios de diseño

• Generación propia del número de control. Zentto asigna el NCF-D desde sus series internas, con correlativo atómico (SELECT ... FOR UPDATE), sin huecos ni colisiones bajo concurrencia.
• Integridad encadenada. Cada documento guarda el hash del registro anterior del mismo RIF emisor (hash-chain SHA-256), formando una cadena verificable de extremo a extremo.
• Aislamiento. El microservicio tiene base de datos propia (esquemas fiscal, imprenta, audit, ops) y dominio propio (imprenta.zentto.net). Si está fuera de servicio, el ERP continúa operando.
• Multi-tenant. Las series se asignan por empresa-cliente (CompanyId); el backoffice administra series y consumo de todas las empresas.
• No bloqueante. La indisponibilidad nunca bloquea la venta: el documento se encola y un worker reintenta con backoff.

Capa de emisión

La emisión implementa la interfaz FiscalProvider con las operaciones ping, emit, getStatus, download, annul, assignNumbering y queryNumbering. El cliente envía un documento canónico (CanonicalDocument) y Zentto lo traduce a su modelo interno.

En el modo de imprenta propia (provider propio):

1. emit invoca imprenta.fn_assign_control_serie(companyId, tipoDocumento, serie), que toma el siguiente número de la serie activa con bloqueo de fila (FOR UPDATE).
2. Se calcula el hash SHA-256 encadenado al hash anterior del RIF emisor.
3. Se inserta un evento facturable en imprenta."ConsumoControl" (metering).
4. Se devuelve controlNumber, y documentos.service persiste el documento.

Modelo de negocio

Zentto cobra a la empresa-cliente por la cantidad de números de control emitidos (metering), con tarifas por número o por bloque. El consumo se mide en imprenta."ConsumoControl" y se factura desde el backoffice.

Esquemas de base de datos

Esquema	Tablas principales	Uso
fiscal	NcfdSequence, DigitalInvoice, SeniatDispatch	Secuencia NCF-D, almacén de documentos con hash-chain, cola de transmisión.
imprenta	ControlSerie, ConsumoControl, TarifaPlan, Integrador, IntegradorCredential, Distribuidor, DistribuidorCartera, ComisionPlan, ComisionLiquidacion, Documento, Sucursal, PuntoFacturacion	Dominio de negocio de la imprenta.
audit	AuditLog	Bitácora de operaciones.
ops	Config, Tenant	Configuración runtime y registro de empresas.