Permisos y Control de Acceso

Zentto implementa un sistema de control de acceso basado en roles (RBAC) que permite configurar permisos granulares por modulo, accion, rol y usuario.

Conceptos

Concepto	Descripcion
Permiso	Autorizacion para realizar una accion en un modulo (ej: ventas.CREATE)
Rol	Agrupacion de permisos (ej: “Vendedor”, “Administrador”)
Override	Excepcion de permiso para un usuario especifico
Restriccion de precio	Limites de descuento y credito por rol/usuario
Regla de aprobacion	Condiciones que activan un flujo de aprobacion

Catalogo de permisos

El catalogo base incluye 120 permisos (15 modulos x 8 acciones):

Modulos

Codigo	Modulo	Descripcion
ventas	Ventas	Facturas, notas, cotizaciones, pedidos, CxC
compras	Compras	Ordenes de compra, recepciones, CxP
inventario	Inventario	Productos, stock, almacenes, movimientos
bancos	Bancos	Cuentas bancarias, movimientos, conciliacion
contabilidad	Contabilidad	Plan de cuentas, asientos, reportes
nomina	Nomina	Procesamiento de nomina, recibos
rrhh	RRHH	Empleados, beneficios, vacaciones
pos	POS	Punto de venta, sesiones, cierres
restaurante	Restaurante	Mesas, ordenes, recetas
auditoria	Auditoria	Logs de auditoria, trazabilidad
crm	CRM	Leads, pipeline, call center
manufactura	Manufactura	BOM, ordenes de produccion
flota	Flota	Vehiculos, mantenimiento, viajes
logistica	Logistica	Recepciones, despachos, devoluciones
permisos	Permisos	Administracion de roles y permisos

Acciones

Codigo	Accion	Descripcion
VIEW	Ver	Consultar y listar registros
CREATE	Crear	Crear nuevos registros
EDIT	Editar	Modificar registros existentes
DELETE	Eliminar	Eliminar registros
VOID	Anular	Anular documentos
APPROVE	Aprobar	Aprobar documentos y solicitudes
EXPORT	Exportar	Exportar datos a Excel/PDF
ADMIN	Administrar	Configuracion avanzada del modulo

Ejemplos de permisos

Permiso	Permite
ventas.VIEW	Ver listado de facturas y documentos de venta
ventas.CREATE	Crear nuevas facturas, cotizaciones, pedidos
ventas.VOID	Anular facturas emitidas
inventario.EDIT	Modificar datos de productos
contabilidad.APPROVE	Aprobar asientos contables
permisos.ADMIN	Gestionar roles y permisos del sistema

Gestion de roles

Crear un rol

1. Ir a Administracion > Roles
2. Crear nuevo rol con nombre descriptivo
3. Asignar permisos individuales o en bloque

Roles sugeridos

Rol	Permisos tipicos
Administrador	Todos (admin flag)
Vendedor	ventas.VIEW, ventas.CREATE, inventario.VIEW, clientes.VIEW
Comprador	compras.VIEW, compras.CREATE, inventario.VIEW, proveedores.VIEW
Contador	contabilidad.*, bancos.VIEW, ventas.VIEW, compras.VIEW
Cajero POS	pos.VIEW, pos.CREATE, inventario.VIEW
Mesero	restaurante.VIEW, restaurante.CREATE
RRHH	rrhh., nomina.VIEW, empleados.
Supervisor	Todos los VIEW + APPROVE de su area
Auditor	auditoria.VIEW, todos los VIEW de modulos

Asignacion masiva de permisos

Para asignar multiples permisos a un rol de una sola vez:

POST /v1/permisos/roles/:roleId/permisos/bulk
{
  "permissions": [
    { "permissionId": 1, "isGranted": true },
    { "permissionId": 2, "isGranted": true },
    { "permissionId": 3, "isGranted": false },
    { "permissionId": 4, "isGranted": true }
  ]
}

Permisos por sucursal

Los permisos pueden restringirse por sucursal. Un vendedor puede tener permiso de crear facturas solo en la sucursal A pero no en la B:

POST /v1/permisos/roles/:roleId/permisos
{
  "permissionId": 2,
  "branchId": 1,
  "isGranted": true
}

Si branchId es null, el permiso aplica a todas las sucursales.

Overrides por usuario

Los overrides permiten dar o quitar un permiso a un usuario especifico, independientemente de su rol.

Casos de uso

• Un vendedor senior necesita poder anular facturas (su rol no lo permite)
• Un empleado en periodo de prueba no debe poder exportar datos (su rol si lo permite)

Aplicar override

POST /v1/permisos/usuarios/:userId/permisos/override
{
  "permissionId": 5,
  "isGranted": true
}

Prioridad de resolucion

1. Usuario admin         --> PERMITIR (siempre)
2. Override de usuario   --> usar valor del override
3. Permiso del rol       --> usar valor del rol
4. Sin configuracion     --> PERMITIR (graceful degradation)

Verificar permiso de un usuario

GET /v1/permisos/usuarios/:userId/verificar/ventas.VOID

Respuesta:

{
  "hasPermission": true,
  "source": "override",
  "permissionCode": "ventas.VOID"
}

Restricciones de precio

Limitan lo que un vendedor puede hacer en terminos de descuentos y credito.

Configuracion

Campo	Descripcion	Ejemplo
maxDiscountPercent	Descuento maximo permitido	15%
minPricePercent	Precio minimo como % del precio lista	85%
maxCreditLimit	Limite de credito maximo otorgable	$50,000
requiresApprovalAbove	Monto que requiere aprobacion	$10,000

Asignar restriccion

Las restricciones se asignan por rol o por usuario:

POST /v1/permisos/precios
{
  "roleId": 3,
  "maxDiscountPercent": 15,
  "minPricePercent": 85,
  "maxCreditLimit": 50000,
  "requiresApprovalAbove": 10000
}

Verificacion en ventas

Cuando un vendedor aplica un descuento o modifica el precio:

1. Frontend consulta /v1/permisos/precios/verificar/:userId
2. Compara el descuento aplicado vs. maxDiscountPercent
3. Si excede el limite:
   • Bloquea la accion, o
   • Solicita aprobacion del supervisor

Ejemplo de flujo

Vendedor aplica 20% de descuento
  --> Restriccion: maxDiscountPercent = 15%
  --> 20% > 15% --> Bloquear
  --> Opcion: crear solicitud de aprobacion al supervisor

Reglas de aprobacion

Definen cuando una operacion requiere aprobacion de un supervisor.

Configuracion

Campo	Descripcion
moduleCode	Modulo (ej: ventas, compras)
documentType	Tipo de documento (ej: FACTURA, ORDEN_COMPRA)
minAmount	Monto minimo que activa la regla
maxAmount	Monto maximo (opcional)
requiredRoleId	Rol que puede aprobar
approvalLevels	Numero de niveles de aprobacion
isActive	Regla activa/inactiva

Ejemplo de regla

POST /v1/permisos/reglas-aprobacion
{
  "moduleCode": "compras",
  "documentType": "ORDEN_COMPRA",
  "minAmount": 5000,
  "requiredRoleId": 2,
  "approvalLevels": 1,
  "isActive": true
}

Esta regla establece que toda orden de compra por mas de $5,000 requiere aprobacion de un usuario con rol ID 2.

Flujo de aprobacion

Crear solicitud

Cuando una operacion activa una regla de aprobacion:

POST /v1/permisos/aprobaciones
{
  "documentModule": "compras",
  "documentType": "ORDEN_COMPRA",
  "documentNumber": "OC-2026-0042",
  "documentAmount": 7500
}

Estados de la solicitud

PENDING --> APPROVED
        --> REJECTED

Aprobar o rechazar

POST /v1/permisos/aprobaciones/:id/accion
{
  "action": "APPROVE",
  "comments": "Aprobado, proveedor verificado"
}

O rechazar:

{
  "action": "REJECT",
  "comments": "Cotizar con al menos 3 proveedores"
}

Consultar solicitudes pendientes

GET /v1/permisos/aprobaciones?status=PENDING&moduleCode=compras

Respuesta:

{
  "rows": [
    {
      "approvalRequestId": 1,
      "documentModule": "compras",
      "documentType": "ORDEN_COMPRA",
      "documentNumber": "OC-2026-0042",
      "documentAmount": 7500,
      "status": "PENDING",
      "requestedBy": "vendedor01",
      "requestedAt": "2026-03-22T10:30:00Z"
    }
  ],
  "totalCount": 1
}

Inicializacion de permisos

Para poblar el catalogo de permisos por primera vez:

POST /v1/permisos/permisos/seed

Este endpoint genera los 120 permisos base (15 modulos x 8 acciones) si no existen.

Comportamiento por defecto

El sistema RBAC usa graceful degradation:

• Si las tablas de permisos no existen: permite todo
• Si el SP de verificacion falla: permite todo
• Si no hay permisos configurados: permite todo
• Usuarios admin: siempre pasan sin verificacion

Esto permite desplegar el sistema sin necesidad de configurar permisos inmediatamente. Los permisos se activan gradualmente a medida que se configuran.

API completa

Endpoint	Metodo	Descripcion
/v1/permisos/permisos	GET	Catalogo de permisos
/v1/permisos/permisos/seed	POST	Inicializar catalogo
/v1/permisos/roles/:roleId/permisos	GET	Permisos de un rol
/v1/permisos/roles/:roleId/permisos	POST	Asignar permiso a rol
/v1/permisos/roles/:roleId/permisos/bulk	POST	Asignacion masiva
/v1/permisos/usuarios/:userId/permisos	GET	Permisos efectivos del usuario
/v1/permisos/usuarios/:userId/permisos/override	POST	Override de permiso
/v1/permisos/usuarios/:userId/verificar/:code	GET	Verificar permiso
/v1/permisos/precios	GET	Listar restricciones de precio
/v1/permisos/precios	POST	Crear/actualizar restriccion
/v1/permisos/precios/verificar/:userId	GET	Verificar restriccion
/v1/permisos/reglas-aprobacion	GET	Listar reglas de aprobacion
/v1/permisos/reglas-aprobacion	POST	Crear/actualizar regla
/v1/permisos/aprobaciones	GET	Listar solicitudes
/v1/permisos/aprobaciones	POST	Crear solicitud
/v1/permisos/aprobaciones/:id	GET	Detalle de solicitud
/v1/permisos/aprobaciones/:id/accion	POST	Aprobar o rechazar