Endpoints principales

La API contiene cientos de rutas y evoluciona junto con el ERP. Esta página no intenta duplicar el contrato completo: muestra cómo navegarlo y recoge operaciones representativas comprobadas en web/contracts/openapi.yaml.

Cómo encontrar la operación correcta

1. Parte del módulo o proceso de negocio.
2. Busca su tag en /docs o en openapi.yaml.
3. Elige el path y el método HTTP exactos.
4. Revisa security, parámetros, requestBody y respuestas antes de implementar.
5. Prueba con una sesión y empresa autorizadas; una ruta existente todavía puede responder 403 si el alcance no corresponde.

/docs y /openapi.json solo están disponibles para administradores autenticados cuando DOCS_ENABLED está activo. Si ese ambiente devuelve 404, consulta el contrato versionado en el repositorio.

Autenticación

Método	Ruta	Uso
POST	/v1/auth/login	Inicia sesión y emite la cookie JWT
POST	/v1/auth/register	Registra un usuario
GET / POST	/v1/auth/verify-email	Verifica el correo mediante token
POST	/v1/auth/resend-verification	Reenvía la verificación
POST	/v1/auth/forgot-password	Solicita recuperación
POST	/v1/auth/reset-password/confirm	Aplica el token de recuperación
GET	/v1/auth/me	Devuelve la identidad autenticada
POST	/v1/auth/change-password	Cambia la contraseña propia

El contrato ERP actual no publica endpoints de refresh ni logout.

Maestros e inventario

Recurso	Colección	Detalle o acción
Clientes	GET/POST /v1/clientes	GET/PUT/DELETE /v1/clientes/{codigo}
Proveedores	GET/POST /v1/proveedores	GET/PUT/DELETE /v1/proveedores/{codigo}
Inventario	GET/POST /v1/inventario	GET/PUT/DELETE /v1/inventario/{codigo}
Artículos (alias de lectura)	GET /v1/articulos	GET /v1/articulos/{codigo}

Ejemplo de listado, usando únicamente parámetros declarados por esa operación:

GET /v1/clientes?search=ferreteria&page=1&limit=20
Authorization: Bearer <jwt>

La respuesta se rige por OkPagedRows; no asumas el mismo esquema para otros listados.

Ventas y compras

Proceso	Método y ruta	Uso
Listado de ventas	GET /v1/documentos-venta	Requiere tipoOperacion; acepta búsqueda, fechas, página y límite
Emitir venta	POST /v1/documentos-venta/emitir-tx	Registra documento, detalle, pagos y emisión fiscal opcional
Anular venta	POST /v1/documentos-venta/anular-tx	Anulación transaccional
Listado de compras	GET /v1/documentos-compra	Lista documentos por tipo y filtros declarados
Emitir compra	POST /v1/documentos-compra/emitir-tx	Registra la compra de forma transaccional
Recibir compra	POST /v1/documentos-compra/recibir-tx	Registra recepción de mercancía

No uses /api/invoices, /api/purchase-orders o /api/products: esas rutas pertenecían a una descripción genérica y no aparecen en el contrato vigente.

Cuentas por cobrar y pagar

Método	Ruta	Uso
POST	/v1/cxc/aplicar-cobro-tx	Aplica un cobro transaccional
GET/POST	/v1/cxc/manual	Gestiona cuentas por cobrar manuales
GET	/v1/cxc/documentos	Consulta documentos de CxC
GET/POST	/v1/cxp/manual	Gestiona cuentas por pagar manuales
GET	/v1/cxp/documentos	Consulta documentos de CxP

Contabilidad y bancos

Área	Rutas representativas
Plan de cuentas	/v1/contabilidad/cuentas, /v1/contabilidad/cuentas/{codCuenta}
Asientos	/v1/contabilidad/asientos, /v1/contabilidad/asientos/{id}/anular
Estados financieros	/v1/contabilidad/reportes/balance-comprobacion, /estado-resultados, /balance-general
Cuentas bancarias	/v1/bancos/cuentas/list, /v1/bancos/cuentas/{nroCta}/movimientos
Conciliación	/v1/bancos/conciliaciones, /crear, /conciliar, /cerrar
Caja chica	/v1/bancos/caja-chica, /v1/bancos/caja-chica/{boxId}/gastos

Los sufijos anteriores comparten el prefijo mostrado en la primera ruta de cada grupo; confirma siempre el path completo en OpenAPI.

CRM

El CRM tiene una superficie amplia. Algunos grupos útiles son:

• Empresas y contactos: /v1/crm/companies, /v1/crm/contacts.
• Negocios: /v1/crm/deals, /v1/crm/deals/{id}/timeline, /move-stage, /close-won y /close-lost.
• Leads: /v1/crm/leads, /v1/crm/leads/{id}/convert.
• Búsqueda: /v1/crm/search.
• Reportes: /v1/crm/reports/win-loss.

La gestión de API keys públicas vive en /v1/crm/public-keys; está implementada en el router y en CRM → Integraciones, pero aún no tiene operaciones propias en OpenAPI. Consulta Autenticación para sus límites.

Configuración verificable

Método	Ruta	Uso
GET	/v1/config/tasas	Consulta tasas BCV actuales
POST	/v1/config/tasas/sync	Fuerza sincronización manual
GET/POST	/v1/config/countries	Lista o guarda países
GET/POST	/v1/config/cash-registers	Lista o configura cajas fiscales

Metadatos que debes revisar

Para cada operación, el contrato puede definir:

• security: sesión JWT, key del tenant u otro esquema específico.
• parameters: path, query y headers obligatorios.
• requestBody: campos y estructura del payload.
• responses: códigos y schemas posibles.
• extensiones como x-db-agnostic cuando aplican.

No generalices parámetros como pageSize, sortBy o fechas a toda la API. Si no aparecen en la operación, el cliente no debe enviarlos esperando que surtan efecto.