Manual Técnico del Sistema Zentto ERP

Manual técnico del sistema Zentto ERP, presentado en cumplimiento del artículo 4 de la Providencia Administrativa SNAT/2024/000121. Describe cómo está construido y cómo opera el sistema, con énfasis en los componentes que intervienen en los procesos documentales y fiscales vinculados al SENIAT.

1. Componentes del ecosistema

ERP principal — repositorio zentto-web

Ubicación base de la API: web/api. Responsabilidades:

• autenticación del usuario;
• resolución de empresa y sucursal activa;
• ejecución de los módulos de negocio;
• procesos de ventas, compras, cuentas por cobrar, cuentas por pagar, bancos y contabilidad;
• registro de auditoría y acciones de negocio.

Imprenta digital — repositorio zentto-imprenta-seniat

Responsabilidades: panel operativo del vertical; administración de sucursales y puntos de facturación; series, numeraciones y asignaciones; emisión y anulación documental; reportes del vertical; API para integradores externos.

Compliance fiscal — repositorio zentto-seniat-compliance

Responsabilidades: registrar eventos fiscales en bitácora inmutable; verificar integridad por contribuyente; generar libros fiscales; registrar accesos y consultas; habilitar la consulta de verificación para el SENIAT bajo clave controlada.

graph LR
  subgraph ERP["ERP — zentto-web"]
    AUTH["Autenticación /v1/auth"]
    VENTAS["Documentos de venta /v1/documentos-venta"]
    COMPRAS["Compras y retenciones"]
    CONTAB["Contabilidad"]
    AUDIT["Auditoría audit.*"]
  end
  subgraph IMP["Imprenta — zentto-imprenta-seniat"]
    EMIT["Emisión /v1/imprenta"]
    BO["Backoffice /v1/imprenta/backoffice"]
    APIINT["API integradores /api"]
  end
  subgraph CMP["Compliance — zentto-seniat-compliance"]
    EV["/v1/events"]
    LG["/v1/ledger (verify)"]
    RP["/v1/reports (libros)"]
    SK["/seniat/* (consulta)"]
  end
  VENTAS -->|evento fiscal| EV
  EMIT -->|evento fiscal| EV
  EV --> LG
  LG --> RP
  SK -.->|X-Seniat-Key| LG
    

2. Flujo técnico de autenticación y sesión

El ERP expone POST /v1/auth/login. El payload se valida con Zod: usuario, clave, companyId (opcional), branchId (opcional) y captchaToken (opcional según configuración).

Comportamiento real:

• el usuario se normaliza en mayúsculas;
• se valida el bloqueo (lockout) y la verificación de correo;
• se autentica contra el registro de usuario (verificación de contraseña con bcrypt en Node);
• se calculan permisos, módulos y accesos de empresa;
• se emite el JWT;
• se fija la cookie zentto_token httpOnly, sameSite=lax, con vida útil de 2 horas.

GET /v1/auth/profile enriquece un JWT válido con permisos, módulos y empresas accesibles. POST /v1/auth/switch-company emite un nuevo token con otra empresa activa.

3. Flujo técnico de documentos de venta

El módulo documentos-venta está implementado en web/api/src/modules/documentos-venta/routes.ts. Rutas verificadas:

• GET /v1/documentos-venta
• GET /v1/documentos-venta/:tipoOperacion/:numFact
• GET /v1/documentos-venta/:tipoOperacion/:numFact/detalle
• POST /v1/documentos-venta/emitir-tx
• POST /v1/documentos-venta/anular-tx
• POST /v1/documentos-venta/facturar-desde-pedido-tx

El payload de emisión se valida con Zod y exige tipoOperacion, documento, detalle (al menos una línea), formasPago (opcional) y options (opcional). El comportamiento técnico es: emisión transaccional del documento; integración contable para facturas; notificación de negocio; registro de observabilidad y auditoría; anulación con reversión contable.

sequenceDiagram
  participant U as Usuario
  participant API as ERP API
  participant DB as PostgreSQL (SP)
  participant CMP as Compliance Ledger
  U->>API: POST /v1/documentos-venta/emitir-tx (Zod)
  API->>DB: ejecución transaccional (stored procedure)
  DB-->>API: documento + número de control
  API->>DB: fiscal."Record" + audit.AuditLog
  API->>CMP: evento fiscal (POST /v1/events)
  CMP-->>API: HashActual (cadena íntegra)
  API-->>U: documento emitido (inalterable)
    

4. Flujo técnico de imprenta digital

El dominio operativo está implementado en zentto-imprenta-seniat, archivo src/modules/imprenta/routes.ts. Bases de ruta: /v1/imprenta/* (operación autenticada), /v1/imprenta/backoffice/* (administración de series, tarifas e integradores), /api/* (terceros integradores) y /seniat/* (consulta regulatoria controlada).

La emisión documental usa EmitDocumentRequest, cuyo cuerpo contiene environment (opcional: demo o production) y document, que responde al esquema CanonicalDocument.

5. API de integradores

Implementada en zentto-imprenta-seniat, archivo src/modules/integrador-api/routes.ts. Flujo: POST /api/Autenticacion con tokenUsuario y secret; se verifica la credencial y se emite un JWT corto; el integrador usa Authorization: Bearer; el companyId se toma siempre del token, nunca del payload del cliente. Rutas: POST /api/emit, GET /api/documentos/:id/status, GET /api/documentos/:id/pdf, POST /api/documentos/:id/annul, GET /api/numeraciones.

6. Bitácora inmutable y compliance

El microservicio zentto-seniat-compliance usa tres bases funcionales: /v1/events, /v1/ledger y /v1/reports. La publicación de eventos usa POST /v1/events con X-API-Key y payload validado por eventPublishSchema (rifEmisor, eventType, referenceType, referenceId, payload, occurredAt). Cada evento se inserta en compliance."EventLedger" con PayloadHash, HashAnterior, HashActual, OccurredAt, ReceivedAt y SeniatDispatchStatus. La verificación de integridad se expone en GET /v1/ledger/verify/:rif y GET /seniat/verify/:tenantId.

7. Libros y reportes fiscales

• GET /v1/reports/libro-ventas/:rif/:periodo
• GET /v1/reports/libro-compras/:rif/:periodo
• GET /v1/reports/libro-retenciones/:rif/:periodo

8. Seguridad técnica

• helmet en la API principal;
• CORS por lista blanca;
• middleware CSRF por validación de origen;
• JWT por cookie httpOnly y Bearer;
• permisos por módulo y acción;
• rate limiting en autenticación;
• claves separadas para integración técnica y para consulta SENIAT;
• validación estructural de payloads con Zod;
• bloqueo temporal de cuentas por intentos fallidos.

La sesión usa JWT en cookie httpOnly/Secure/SameSite con verificación dual RS256 (contra el JWKS del servicio de autenticación) y HS256 (legado). La gestión de vulnerabilidades en el pipeline CI/CD, la centralización de secretos en HashiCorp Vault y el modelo de monitoreo permanente del SENIAT se detallan en la página de seguridad, CI/CD y monitoreo.

Aislamiento de dispositivos no fiscales (Art. 8)

La emisión de documentos fiscales se canaliza exclusivamente por el motor de imprenta digital y las rutas fiscales del ecosistema. Los dispositivos o procesos no fiscales no participan en la asignación de número de control ni en el registro del ledger inmutable, de modo que la operación fiscal queda aislada de cualquier flujo paralelo.

9. Despliegue y operación

graph TD
  DEV["Repositorio Git (control de versiones)"] -->|push| CI["GitHub Actions — build + test"]
  CI -->|imagen Docker| REG["Registro de contenedores ghcr.io"]
  REG -->|SSH deploy| SRV["Servidor Hetzner CX33 — Ubuntu"]
  SRV --> DOCK["Docker — API + frontend"]
  SRV --> NGX["Nginx — TLS + reverse proxy"]
  SRV --> PGH[("PostgreSQL 16 en host")]
    

La documentación técnica del repositorio indica: despliegue productivo sobre Hetzner CX33; Nginx como reverse proxy; Docker para los servicios; PostgreSQL 16 en host para producción; pipelines de GitHub Actions para API y frontend; esquema de despliegue incremental sobre PostgreSQL y SQL Server para el ERP.

10. Mantenimiento y cambios controlados

Cambios de datos y esquema en el ERP: migraciones en web/api/migrations/postgres/; funciones y procedimientos en web/api/sqlweb-pg/ y web/api/sqlweb/; contratos OpenAPI bajo control de versiones. Cambios de imprenta y compliance: migraciones propias en cada repositorio; contratos y rutas versionadas en Git; despliegues por CI/CD. Cada versión que afecte el alcance fiscal se somete a homologación conforme a los artículos 9 a 12 de la Providencia.

ZENTTO GLOBAL TECHNOLOGY, C.A. — RIF J-50849797-0 — Manual técnico (Art. 4 SNAT/2024/000121) — v1.0.0.