Manual Técnico de Operación de la Plataforma

Este manual describe la operación técnica de la plataforma de imprenta digital de ZENTTO GLOBAL TECHNOLOGY, C.A.: recepción del documento, asignación del número de control, validación de la estructura, registro automatizado, consulta y reportes. Documenta la plataforma tal como se encuentra implementada y desplegada, conforme a la Providencia Administrativa SNAT/2024/000102.

1. Arquitectura de servicios y rutas

La plataforma se expone como un servicio HTTP versionado, con dominios de ruta separados según el actor. El servicio se monta sobre Express con endurecimiento de cabeceras (helmet), CORS por lista blanca y limitación de tasa.

Base de ruta	Actor	Autenticación
`/v1/imprenta`	Operación autenticada (emisor / operador)	Cookie httpOnly o Bearer (servidor)
`/v1/imprenta/backoffice`	Administración (series, consumo, tarifas, integradores)	Cookie httpOnly + rol
`/api`	Integradores autorizados (terceros emisores)	Token de integrador (Bearer)
`/seniat`	Consulta regulatoria del SENIAT	`X-Seniat-Key`
`/health`	Verificación de salud del servicio	Sin autenticación

2. Flujo de emisión y asignación del número de control

El flujo principal recibe el documento canónico, valida su estructura, asigna el número de control de forma atómica, lo encadena con la cadena de integridad y registra el consumo y el documento:

sequenceDiagram
  participant E as Emisor / Integrador
  participant API as Imprenta digital
  participant Z as Validación (Zod)
  participant DB as PostgreSQL
  participant H as Cadena de integridad
  participant A as Bitácora (AccessLog)
  E->>API: POST /v1/imprenta (o POST /api/emit) — documento canónico
  API->>Z: Validar estructura
  Z-->>API: Estructura válida
  API->>DB: fn_assign_control_serie (atómico)
  DB-->>API: Número de control + SerieId
  API->>H: computeHash (SHA-256 por RIF)
  API->>DB: INSERT ConsumoControl + DigitalInvoice
  API->>A: Registrar evento (INVOICE_CREATED)
  API-->>E: Número de control asignado

3. Asignación de series (backoffice)

Las series de números de control son recursos propios que el backoffice administra. Cada serie es un rango [Desde, Hasta] asignado a una empresa-cliente para un tipo de documento. Rutas verificadas del backoffice (base /v1/imprenta/backoffice):

Ruta	Función
`GET/POST /series`	Consulta y creación de series de números de control
`POST /series/:id/reasignar`	Reasignación de una serie a otra empresa-cliente
`POST /series/:id/extender`	Extensión del rango de una serie
`GET /consumo` · `GET /consumo/resumen`	Consumo de números de control (metering) y su resumen
`GET/POST /tarifas`	Tarifas por número de control y por bloque
`GET/POST /integradores`	Alta y administración de integradores
`POST /integradores/:id/tokens`	Emisión y revocación de tokens de integrador

4. Metering (registro del consumo)

Cada número de control emitido desde una serie propia genera un registro en imprenta."ConsumoControl", que constituye el registro verificable del consumo por empresa-cliente y período. El conteo de registros por empresa-cliente y período permite determinar el volumen de números de control asignados. El resumen de consumo se consulta desde el backoffice (GET /consumo/resumen).

5. API de integradores

Los integradores autorizados asignan número de control a través de la API de integradores. El flujo de autenticación emite un token de vida corta; el identificador de empresa se deriva siempre del token, nunca del cuerpo de la solicitud:

Ruta	Función
`POST /api/Autenticacion`	Autenticación con `tokenUsuario` y `secret`; emite un token de integrador (Bearer)
`POST /api/emit`	Asignación de número de control a un documento canónico
`GET /api/documentos/:id/status`	Estado del documento
`GET /api/documentos/:id/pdf`	Representación del documento
`POST /api/documentos/:id/annul`	Anulación lógica del documento
`GET /api/numeraciones`	Consulta de las series y numeraciones disponibles

6. Consulta y verificación

La consulta de documentos se realiza por número de control, por RIF y período, o por libro de ventas. La integridad de la cadena de un emisor se verifica recalculando la secuencia completa (verifyChainIntegrity), lo que permite confirmar que ningún registro fue alterado. El detalle del canal de consulta del SENIAT se desarrolla en el anexo de acceso permanente y reporte al SENIAT.

7. Reportes

Libro de ventas por período: GET /seniat/libro-ventas/:rif/:periodo (período AAAA-MM), con totales de base imponible, IVA, IGTF y total.
Listado de documentos: GET /seniat/listado por RIF y rango de fechas.
Resumen de consumo: GET /consumo/resumen en el backoffice.

8. Despliegue y operación

graph TD
  GIT["Repositorio Git"] -->|push| CI["GitHub Actions — type-check + tests"]
  CI -->|imagen Docker| REG["Registro ghcr.io"]
  REG -->|SSH deploy| SRV["Servidor Hetzner — Ubuntu"]
  SRV --> DOCK["Contenedor zentto-imprenta (puerto 4900)"]
  SRV --> NGX["Nginx — TLS"]
  DOCK --> PG[("PostgreSQL 16 — zentto_imprenta_prod")]
  DOCK --> VAULT["HashiCorp Vault — secretos"]

El servicio se ejecuta en el contenedor zentto-imprenta (puerto 4900), con reinicio automático y verificación de salud (/health). El despliegue es exclusivamente por integración y entrega continuas (CI/CD): cada cambio supera la verificación de tipos y las pruebas antes de construirse la imagen y desplegarse al servidor. No existen despliegues manuales.

9. Mantenimiento y migraciones

El esquema de base de datos se gestiona con migraciones idempotentes que se aplican al arranque del servicio (src/db/migrations/): la tabla y función de numeración (fiscal."NcfdSequence", fiscal.fn_assign_ncfd), el almacén de documentos con cadena de integridad (fiscal."DigitalInvoice"), la bitácora inmutable (audit."AccessLog") y el dominio de series, consumo y tarifas (imprenta."ControlSerie", imprenta."ConsumoControl", imprenta."TarifaPlan", imprenta.fn_assign_control_serie). Cada cambio relevante para el ámbito fiscal se versiona en el repositorio y se despliega por CI/CD.

ZENTTO GLOBAL TECHNOLOGY, C.A. — RIF J-50849797-0 — Manual técnico de operación de la imprenta digital (SNAT/2024/000102) — v1.0.0.