Documentación de API y Contratos

Documentación de la interfaz de programación (API) del sistema Zentto ERP, presentada en cumplimiento del artículo 4 de la Providencia Administrativa SNAT/2024/000121. Describe la autenticación, los endpoints clave, la estructura de datos, los contratos formales y la clave de consulta dispuesta para el acceso del SENIAT (artículo 3 y Disposiciones Finales).

1. Fuentes contractuales

La documentación se sustenta en contratos OpenAPI versionados y en las rutas implementadas:

Componente	Repositorio	Contrato
ERP	`zentto-web`	`web/contracts/openapi.yaml`
Imprenta digital	`zentto-imprenta-seniat`	`contracts/openapi.imprenta.yaml` (50 rutas, 103 esquemas)
Compliance fiscal	`zentto-seniat-compliance`	`src/routes/` (eventos, ledger, reportes, consulta SENIAT)

La referencia navegable de la API de imprenta digital se encuentra publicada en docs.zentto.net/imprenta-digital/referencia-api.

2. Autenticación del ERP

Base principal: /v1/auth. La sesión se gestiona con JWT transportado en una cookie httpOnly, no accesible desde JavaScript del navegador, lo que reduce la superficie de robo de sesión.

Rutas verificadas: POST /v1/auth/login, GET /v1/auth/login-options, GET /v1/auth/companies, GET /v1/auth/profile, POST /v1/auth/switch-company, POST /v1/auth/change-password, GET /v1/auth/me, POST /v1/auth/register, GET /v1/auth/verify-email, POST /v1/auth/forgot-password, POST /v1/auth/reset-password/confirm, entre otras.

Ejemplo — solicitud de login

POST /v1/auth/login HTTP/1.1
Host: api.zentto.net
Content-Type: application/json

{
  "usuario": "OPERADOR.DEMO",
  "clave": "********",
  "companyId": 12
}

Ejemplo — respuesta

HTTP/1.1 200 OK
Set-Cookie: zentto_token=<jwt>; HttpOnly; Secure; SameSite=Lax; Domain=.zentto.net; Max-Age=7200

{
  "userId": 1001,
  "userName": "Operador Demo",
  "isAdmin": false,
  "permisos": ["ventas.emitir", "ventas.consultar"],
  "modulos": ["ventas", "compras"],
  "defaultCompany": 12,
  "companyAccesses": [12]
}

La sesión usa cookie zentto_token httpOnly, vida útil de 2 horas, sameSite=lax y dominio .zentto.net en producción.

3. Endpoints de negocio del ERP

El ERP expone módulos de negocio bajo /v1/*, entre ellos: /v1/clientes, /v1/proveedores, /v1/inventario, /v1/bancos, /v1/contabilidad, /v1/documentos-venta, /v1/documentos-compra, /v1/cxc, /v1/cxp, /v1/retenciones, /v1/auditoria, /v1/empresa y /v1/usuarios.

Caso real — emisión de documento de venta

POST /v1/documentos-venta/emitir-tx HTTP/1.1
Host: api.zentto.net
Cookie: zentto_token=<jwt>
Content-Type: application/json

{
  "tipoOperacion": "FACT",
  "documento": { "clienteRif": "J-12345678-9", "moneda": "VES", "fecha": "2026-06-30" },
  "detalle": [
    { "codigo": "ART-001", "cantidad": 2, "precio": 100.00, "alicuotaIva": 16 }
  ],
  "formasPago": [ { "tipo": "EFECTIVO", "monto": 232.00 } ]
}

HTTP/1.1 200 OK

{
  "ok": true,
  "numeroControl": "00-01-00012345",
  "numeroDocumento": "FACT-000123",
  "baseImponible": 200.00,
  "iva": 32.00,
  "total": 232.00
}

4. Dominio de imprenta digital

Contrato OpenAPI en zentto-imprenta-seniat, ruta contracts/openapi.imprenta.yaml. Servidores declarados: https://imprenta.zentto.net, https://imprentadev.zentto.net y el entorno local de integración. Bases funcionales: /v1/imprenta/*, /v1/imprenta/backoffice/*, /api/* y /seniat/*.

La API para integradores autentica con POST /api/Autenticacion (tokenUsuario + secret), emite un JWT corto y opera con Authorization: Bearer; el companyId se deriva siempre del token.

5. Compliance fiscal y bitácora

El microservicio expone POST /v1/events (publicación de eventos con X-API-Key), GET /v1/ledger/verify/:rif (verificación de integridad), y los libros fiscales GET /v1/reports/libro-ventas/:rif/:periodo, libro-compras y libro-retenciones.

6. Clave de consulta del SENIAT

En cumplimiento del artículo 3 de la Providencia, el sistema dispone de un canal de consulta exclusivo para la Administración Tributaria. El acceso se realiza mediante la cabecera X-Seniat-Key sobre las rutas /seniat/*, que permiten verificar la integridad del ledger y consultar la información fiscal del contribuyente sin exponer credenciales operativas.

GET /seniat/verify/<tenantId> HTTP/1.1
Host: imprenta.zentto.net
X-Seniat-Key: <clave-de-consulta-emitida-al-SENIAT>

HTTP/1.1 200 OK

{
  "tenantId": "...",
  "rifEmisor": "J-50849797-0",
  "integridad": "OK",
  "totalEventos": 12480,
  "ultimoHash": "9f3a...c1",
  "verificadoEn": "2026-06-30T14:05:00Z"
}

La clave de consulta se emite y entrega de forma controlada al SENIAT mediante el procedimiento descrito en el anexo de acceso controlado; no se publica en documentación abierta.

7. Estructura de datos y convenciones

Todos los payloads se validan estructuralmente con Zod antes de procesarse.
Las fechas se manejan en UTC-0; la visualización convierte a la zona horaria de la empresa.
Las respuestas de error siguen un formato controlado, sin exposición de trazas internas.
Los listados devuelven el conteo total para paginación consistente.

ZENTTO GLOBAL TECHNOLOGY, C.A. — RIF J-50849797-0 — Documentación de API (Art. 4 SNAT/2024/000121) — v1.0.0.