API — Introducción

La API de Zentto es el backend REST del ERP, de sus aplicaciones modulares y de las integraciones autorizadas. El contrato vigente está en web/contracts/openapi.yaml; úsalo como fuente de verdad para rutas, métodos, parámetros y esquemas.

URL base y versión

Entorno	URL base
Producción	https://api.zentto.net
Desarrollo local	http://localhost:4000

Las operaciones de negocio documentadas usan el prefijo /v1:

GET https://api.zentto.net/v1/clientes
GET https://api.zentto.net/v1/inventario
POST https://api.zentto.net/v1/documentos-venta/emitir-tx

Existe un alias de compatibilidad /api/v1 en el montaje del servidor, pero las integraciones nuevas deben seguir las rutas /v1 publicadas en OpenAPI. Rutas como /api/products o /api/invoices no forman parte del contrato actual.

Cómo se procesa una solicitud

1. El cliente llama una operación publicada en OpenAPI.
2. Las rutas protegidas validan la sesión, el alcance de empresa y los permisos.
3. Express dirige la solicitud al módulo correspondiente.
4. La capa de datos usa callSp(), callSpOut() o callSpTx() para ejecutar funciones de PostgreSQL.
5. La API devuelve la respuesta definida por esa operación o un error HTTP.

La base de datos activa es PostgreSQL. Los directorios SQL Server que permanecen en el repositorio son legado congelado y no describen la arquitectura vigente.

Autenticación

El contrato declara bearerAuth como esquema general. En el navegador, la sesión se transporta primero mediante una cookie HttpOnly; el middleware conserva Authorization: Bearer <token> como compatibilidad para clientes no interactivos. Consulta Autenticación para ver el flujo real y las API keys públicas limitadas por scopes.

Respuestas y errores

No existe un único envoltorio obligatorio para todas las operaciones. Cada ruta define su esquema en OpenAPI: algunas devuelven { ok, data }, otras una colección o un objeto de dominio. El cliente debe consumir el esquema de la operación concreta.

Los errores usan códigos HTTP y un identificador legible por máquina. Por ejemplo, una ruta protegida sin sesión responde:

{
  "error": "missing_token"
}

Los códigos más habituales son:

Código	Significado
200 / 201	Lectura o creación correcta
400	Payload o parámetros inválidos
401	Falta una sesión válida
403	La identidad no tiene alcance o permiso
404	Recurso o ruta no disponible
409	Conflicto con el estado actual
429	Límite de solicitudes excedido en una ruta limitada
500 / 503	Error interno o dependencia no disponible

Paginación y filtros

Los parámetros no son universales. Según el módulo encontrarás combinaciones como limit, offset, page, pageSize, búsquedas o rangos de fechas. Revisa el bloque parameters de la operación antes de construir un cliente y no supongas que todos los listados aceptan los mismos nombres.

Fechas

La API normaliza las fechas de las rutas /v1 a UTC para procesarlas y localiza las respuestas según la zona horaria de la empresa. Envía fechas ISO 8601 con zona explícita cuando el campo lo permita.

Límites de solicitudes

Los límites se configuran por flujo, no como una cuota global idéntica. El login aplica actualmente 30 intentos por minuto por IP; registro, recuperación y verificación tienen ventanas propias. Una respuesta 429 indica que debe respetarse el tiempo de espera antes de reintentar.

Explorar el contrato

• web/contracts/openapi.yaml: fuente versionada del contrato.
• /docs: Swagger UI, solo cuando DOCS_ENABLED está activo y el usuario autenticado es administrador.
• /openapi.json: contrato completo, con la misma protección de sesión y administración.
• /v1/report-contract: catálogo autenticado y filtrado de operaciones GET aptas para Report Studio; no reemplaza el contrato completo.

No dependas de que /docs esté habilitado en todos los ambientes: el servidor puede desactivarlo y responder 404.

Secciones

Sección	Descripción
Autenticación	Cookie HttpOnly, JWT de compatibilidad y API keys públicas
Endpoints	Cómo localizar y elegir operaciones reales por módulo