Permisos RBAC

NeoPOS implementa un sistema de control de acceso basado en roles (RBAC). Cada usuario tiene un rol, y cada rol tiene permisos CRUD (leer, crear, actualizar, eliminar) sobre módulos específicos dentro de su tenant.

Roles

Rol	ID	Descripción
Administrador	1	Admin del tenant — puede gestionar usuarios y permisos de su tenant
Asistente	2	Acceso limitado a ventas, productos, clientes
Superadmin	3	Cross-tenant — gestión de todos los tenants (solo operaciones de infraestructura)

Módulos vs Roles

Cada módulo define qué acciones puede realizar cada rol. Los permisos se almacenan en la tabla permisos_rol y se verifican en cada endpoint.

Módulo	Leer	Crear	Actualizar	Eliminar
`ventas`	✅	✅	✅	✅
`productos`	✅	✅	✅	✅
`categorias`	✅	✅	✅	✅
`clientes`	✅	✅	✅	✅
`proveedores`	✅	✅	✅	✅
`caja`	✅	✅	✅	✅
`egresos`	✅	✅	✅	✅
`impuestos`	✅	✅	✅	✅
`jornadas`	✅	✅	✅	✅
`saldo_inicial`	✅	✅	✅	✅
`cotizaciones`	✅	✅	✅	✅
`creditos`	✅	✅	✅	✅
`usuarios`	✅	✅	✅	✅
`configuracion`	✅	✅	✅	✅
`logs`	✅	❌	❌	❌
`dashboard`	✅	❌	❌	❌
`reportes`	✅	❌	❌	❌
`permisos`	✅	✅	✅	✅
`tenants`	✅	✅	✅	✅

Nota: El Superadmin (rol=3) tiene acceso a todos los módulos sin restricción. El Asistente (rol=2) solo tiene permisos específicos según la configuración del tenant.

Cómo consultar permisos del usuario

Cada vez que un usuario se autentica, la respuesta de login incluye su objeto usuario con rol y tenant_id. Para consultar los permisos específicos de su rol:

curl "http://localhost/api/permisos-rol?id_tipo_usuario=2" \
  -H "Authorization: Bearer <token>"

Respuesta:

{
  "data": [
    {
      "modulo": "ventas",
      "permiso_crear": true,
      "permiso_leer": true,
      "permiso_actualizar": true,
      "permiso_eliminar": false
    }
  ]
}

Jerarquía de verificación

El endpoint recibe el token JWT → extrae tenant_id, rol, user_id
Si el rol es Superadmin (3) → acceso concedido sin verificar permisos
Si no → consulta permisos_rol para el tenant y rol actual
Verifica el permiso específico (permiso_leer, permiso_crear, etc.)
Si no tiene permiso → responde 403 Forbidden

Cómo gestionar permisos

Los administradores de tenant pueden gestionar permisos mediante el endpoint /api/permisos-rol. Para reemplazar todos los permisos de un rol de una sola vez:

curl -X PUT "http://localhost/api/permisos-rol/upsert/2" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"permisos": [{"modulo": "ventas", "permiso_crear": false, "permiso_leer": true, "permiso_actualizar": false, "permiso_eliminar": false}]}'

Para más detalles, consulta la referencia de endpoints de permisos.