API — Introduction

La API de Zentto es una interfaz REST que expone toda la funcionalidad del ERP para integraciones externas, aplicaciones móviles y el propio frontend modular.

URL base

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

Todas las rutas de la API tienen el prefijo /api:

https://api.zentto.net/api/auth/login
https://api.zentto.net/api/products
https://api.zentto.net/api/invoices

Arquitectura

La API está construida con:

• Node.js + Express + TypeScript.
• Stored Procedures: toda la lógica de datos reside en SP (SQL Server o PostgreSQL).
• Helpers de DB: callSp(), callSpOut(), callSpTx() en web/api/src/db/query.ts.
• Dual database: soporta SQL Server y PostgreSQL, controlado por DB_TYPE en .env.

Convenciones

Formato de respuesta

Todas las respuestas siguen un formato consistente:

{
  "ok": true,
  "data": { ... },
  "message": "Operación exitosa"
}

En caso de error:

{
  "ok": false,
  "message": "Descripción del error",
  "errors": ["detalle1", "detalle2"]
}

Códigos HTTP

Código	Significado
200	Operación exitosa
201	Recurso creado
400	Solicitud inválida (validación)
401	No autenticado
403	Sin permisos
404	Recurso no encontrado
500	Error interno del servidor

📸 Captura: Documentación Swagger/OpenAPI de la API

Paginación

Los endpoints de listado soportan paginación:

GET /api/products?page=1&pageSize=20

La respuesta incluye metadatos de paginación:

{
  "ok": true,
  "data": [...],
  "totalCount": 150,
  "page": 1,
  "pageSize": 20
}

Fechas

Todas las fechas se manejan en UTC-0. El middleware datetime.ts convierte automáticamente:

• Request: fechas del cliente se convierten a UTC antes de procesar.
• Response: fechas UTC se convierten a la zona horaria de la empresa antes de enviar.

Rate limiting

La API implementa límites de tasa para prevenir abuso:

Contexto	Límite
General	100 requests / minuto por IP
Autenticación	10 intentos / minuto por IP
Exportaciones	5 requests / minuto por usuario

Al exceder el límite, la API responde con código 429 Too Many Requests y un header Retry-After indicando los segundos de espera.

Contrato OpenAPI

La especificación completa de la API se mantiene en web/contracts/openapi.yaml. Este contrato se actualiza antes de cualquier cambio en el frontend, garantizando que ambos lados estén sincronizados.

Secciones

Sección	Descripción
Autenticación	JWT, refresh tokens y API keys
Endpoints	Lista completa de endpoints por módulo