Responde quien puede ejecutar un proceso del negocio, sin mirar pantallas ni recursos.
Nebula opera un modelo dual de autorizacion:
| Eje | Pregunta que responde | Donde vive |
|---|---|---|
Usuario -> Rol -> Recurso -> Accion |
Que pantallas y botones ve una persona | Simappe (plataforma) |
Rol -> Permiso de operacion |
Que procesos de negocio puede ejecutar un rol | Esta API (nebula-masters) |
El permiso de operacion es propio del negocio y no existe en Simappe: aprobar una disponibilidad, anular un compromiso, aprobar una orden de pago. La verificacion es sin recurso: no consulta opciones de menu ni acciones de Simappe.
El rol no se replica. rolCodigo es el authority del rol de Simappe. El espejo local del rol se dio de baja el 27-ago-2026: el rol tiene una sola fuente de verdad y es la plataforma.
| Servicio | nebula-masters |
| Context path | /nebula-masters |
| Version de la API | v1 |
| Version del servicio | 1.7.0-SNAPSHOT |
| Endpoints base | /api/v1/permiso · /api/v1/rol-permiso |
| Contratos (modelos) | nebula-models 0.50.0-SNAPSHOT — paquetes masters.permiso y masters.rolpermiso |
| Clientes compartidos | nebula-shared 0.7.0-SNAPSHOT — PermisoOperacionBlockingClient / PermisoOperacionReactiveClient |
| api-docs (DEV) | https://api-dev.centricasoluciones.com/nebula-masters/api-docs |
| Swagger UI (DEV) | https://api-dev.centricasoluciones.com/nebula-masters/swagger-ui.html |
| Aislamiento | Multitenant por token; consultas nativas con paginador de tenant |
| Tablas | simappe_rra_permiso, simappe_rra_rol_permiso (esquema MASTERS) |
| Vistas aplanadas | v_simappe_rra_permiso, v_simappe_rra_rol_permiso |
Para quien la consume, esta API es de SOLO CONSULTA. Un modulo de negocio pregunta si un rol, una sesion o una persona puede ejecutar un proceso, y lista quien puede hacerlo. Nada mas.
| Naturaleza | Operaciones | Quien |
|---|---|---|
| Consulta | read, get, get-record, page, page-response, by-rol, by-token, by-usuario, verificar, verificar-token, verificar-usuario, usuarios-con-permisos |
Cualquier consumidor autenticado del tenant |
| Gestion | create, update, delete — del permiso y de la asignacion rol-permiso |
Rol administrativo. Es configuracion del tenant, no operacion de un modulo |
Crear un permiso, asignarlo a un rol o revocarlo cambia quien puede aprobar y anular documentos en todo el ERP. Esa potestad es administrativa y se ejerce desde la configuracion, no desde un flujo de negocio.
El estado actual del ambiente permite la gestion a cualquier token valido del tenant. No hay todavia un rol administrativo que separe la consulta de la escritura, asi que la contencion es de acuerdo, no de mecanismo.
Es una concesion de desarrollo, no el estado final. Mientras dure:
| Regla | Detalle |
|---|---|
| Ningun modulo de negocio escribe | Un modulo consulta y verifica. Si necesita un permiso nuevo, se solicita, no se crea sobre la marcha |
| La gestion se ejerce desde la configuracion | Y con conocimiento de lo que cambia: la asignacion decide quien aprueba y quien anula |
| Los permisos base estan blindados | Los sembrados por el sistema rechazan update y delete con 409, aunque el llamado venga autorizado |
| La baja es logica | Revocar y dar de baja no borran la fila: mueven el estado de negocio a INACTIVO |
El par de clientes compartidos de nebula-shared ya materializa la regla: PermisoOperacionBlockingClient y su gemelo reactivo exponen las siete operaciones de consulta y ninguna de escritura. Un microservicio que consuma esta API por el camino canonico no tiene forma de escribir en ella.
Toda llamada de esta API — y el propio api-docs — exige Authorization: Bearer <accessToken>.
TOKEN=$(curl -s -X POST \
https://api-dev.centricasoluciones.com/simappe-oauth2-server/api/v1/login \
-H "Content-Type: application/json" \
-d '{"username":"<USUARIO_DEV>","password":"<PASSWORD_DEV>"}' \
| jq -r '.accessToken')
El tenant sale del token. No hay parametro de compania en ninguna ruta: la misma URL responde el catalogo de la compania de la sesion. Detalle completo en Consulta de Documentacion OpenAPI.
/api/v1/permisoCatalogo de permisos de operacion del tenant.
| Metodo | Ruta | Que hace | Entrada | Salida |
|---|---|---|---|---|
GET |
/read |
Lista los permisos ACTIVOS del tenant | — | List<PermisoDto> · 204 si no hay |
GET |
/get |
Obtiene un permiso por id | id (query) |
PermisoDto · 404 |
POST |
/create |
Crea el permiso | PermisoDto |
PermisoDto · 409 si el codigo ya existe |
PUT |
/update |
Actualiza nombre y descripcion | id (query) + PermisoDto |
PermisoDto · 404 |
DELETE |
/delete |
Baja LOGICA (estado a INACTIVO) | id (query) |
204 · 404 |
POST |
/page |
Pagina DTO con busqueda y orden | SimappeRequestQuery |
PageDto<PermisoDto> |
POST |
/page-response |
Pagina de records planos (estandar ERP) | SimappeRequestQuery |
PageResponse<PermisoResponse> |
GET |
/get-record |
Record plano por id (estandar ERP) | id (query) |
PermisoResponse · 404 |
Reglas:
update solo toca nombre y descripcion.^[A-Za-z]\w{1,99}$ — arranca en letra, maximo 100 caracteres.es_sistema = 1, los sembrados) se rechazan en update y delete: sostienen la operacion base. Los que anexe el cliente entran sin la marca y si se administran.INACTIVO./api/v1/rol-permisoAsignacion rol -> permiso, y resolucion de la pregunta de autorizacion.
| Metodo | Ruta | Que hace | Entrada | Salida |
|---|---|---|---|---|
POST |
/usuarios-con-permisos |
Consulta inversa: quienes pueden ejecutar unos procesos | List<String> de codigos |
List<UsuarioConPermisosResponse> · 204 |
GET |
/by-rol |
Permisos ACTIVOS de un rol | rolCodigo (query) |
List<RolPermisoResponse> · 204 |
GET |
/by-token |
Permisos de la sesion en curso | — | List<RolPermisoResponse> · 204 |
GET |
/by-usuario |
Permisos de una persona | codigoUsuario (query) |
List<RolPermisoResponse> · 204 |
GET |
/verificar |
Verifica un permiso de un ROL | rolCodigo, permisoCodigo |
PermisoVerificacionResponse |
GET |
/verificar-token |
Verifica un permiso de la SESION | permisoCodigo |
PermisoVerificacionResponse |
GET |
/verificar-usuario |
Verifica un permiso de una PERSONA | codigoUsuario, permisoCodigo |
PermisoVerificacionResponse |
Como resuelve cada uno:
/by-token y /verificar-token no consultan Simappe: el JWT ya publica los roles de negocio con su codigo y su clase./by-usuario y /verificar-usuario si resuelven identidad y roles contra Simappe, y cruzan contra el catalogo local.permisoCodigo es libre: la fuente de verdad es el catalogo del tenant, no el enum de referencia. Un permiso creado por el negocio se verifica igual que uno de sistema.| Metodo | Ruta | Que hace | Entrada | Salida |
|---|---|---|---|---|
GET |
/read |
Asignaciones ACTIVAS del tenant | — | List<RolPermisoDto> · 204 |
GET |
/get |
Asignacion por id | id (query) |
RolPermisoDto · 404 |
POST |
/create |
Asigna un permiso a un rol | RolPermisoDto |
RolPermisoDto · 404 · 409 |
PUT |
/update |
Reactiva una asignacion dada de baja | id (query) + RolPermisoDto |
RolPermisoDto · 404 |
DELETE |
/delete |
Revoca (baja LOGICA) | id (query) |
204 · 404 |
POST |
/page |
Pagina DTO | SimappeRequestQuery |
PageDto<RolPermisoDto> |
POST |
/page-response |
Pagina de records aplanados | SimappeRequestQuery |
PageResponse<RolPermisoResponse> |
GET |
/get-record |
Record aplanado por id | id (query) |
RolPermisoResponse · 404 |
Reglas:
(rol, permiso) es unica por tenant e INMUTABLE: update no reasigna, solo devuelve la asignacion al estado ACTIVO.create exige que el rol y el permiso existan y esten ACTIVOS; si ya estan vinculados responde 409.INACTIVO.POST /api/v1/rol-permiso/usuarios-con-permisos
En vez de preguntar que puede hacer alguien, pregunta quien puede hacer algo. Devuelve cada persona con su codigo, su identificacion, su nombre y los permisos consultados que tiene activos, con el rol por el que le llega cada uno. No importa el rol: basta con que alguno se lo conceda.
Peticion:
curl -s -X POST \
https://api-dev.centricasoluciones.com/nebula-masters/api/v1/rol-permiso/usuarios-con-permisos \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '[ "APROBAR_DISPONIBILIDAD", "ANULAR_COMPROMISO" ]'
Respuesta 200:
[
{
"codigoUsuario": "dev001",
"identificacion": "1037613829",
"nombre": "Paula Alejandra Sanchez Restrepo",
"permisos": [
{
"id": 1000,
"codigo": "APROBAR_DISPONIBILIDAD",
"nombre": "Aprobar Disponibilidad",
"rolCodigo": "APROBADOR"
}
]
}
]
204 cuando ninguna persona del tenant tiene activo ninguno de los permisos consultados.
Para que sirve: armar la lista de candidatos de un flujo de aprobacion sin cablear nombres ni roles en el codigo del modulo que aprueba.
PermisoDto — entrada y salida del catalogo| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
id |
Long |
— | Solo lectura. Secuencia |
codigo |
String |
Si | Maximo 100. Patron ^[A-Za-z]\w{1,99}$. Se persiste en MAYUSCULAS. Inmutable |
nombre |
String |
Si | Maximo 150 |
descripcion |
String |
No | Maximo 300 |
PermisoResponse — record plano| Campo | Tipo |
|---|---|
id |
Long |
codigo |
String |
nombre |
String |
descripcion |
String |
estadoPermiso |
String |
RolPermisoDto — entrada de la asignacion| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
id |
Long |
— | Solo lectura. Secuencia |
rolCodigo |
String |
Si | Maximo 100. authority del rol de Simappe |
permisoCodigo |
String |
Si | Maximo 100. Codigo del permiso |
RolPermisoResponse — record aplanado| Campo | Tipo |
|---|---|
id |
Long |
rolCodigo |
String |
permisoCodigo |
String |
permisoNombre |
String |
permisoDescripcion |
String |
estadoRolPermiso |
String |
PermisoVerificacionResponse — resultado de toda verificacion| Campo | Tipo | Contenido |
|---|---|---|
tipoSujeto |
String |
ROL · TOKEN · USUARIO |
sujeto |
String |
Codigo del rol o de la persona |
permisoCodigo |
String |
Permiso consultado |
permitido |
Boolean |
Veredicto |
rolesQueConceden |
List<String> |
Roles por los que pasa el permiso |
{
"tipoSujeto": "TOKEN",
"sujeto": "dev001",
"permisoCodigo": "APROBAR_DISPONIBILIDAD",
"permitido": true,
"rolesQueConceden": [ "APROBADOR" ]
}
UsuarioConPermisosResponse y PermisoConcedidoResponseUsuarioConPermisosResponse |
Tipo |
|---|---|
codigoUsuario |
String |
identificacion |
String |
nombre |
String |
permisos |
List<PermisoConcedidoResponse> |
PermisoConcedidoResponse |
Tipo |
|---|---|
id |
Long |
codigo |
String |
nombre |
String |
rolCodigo |
String |
22 permisos de operacion entran sembrados por compania activa, marcados como de sistema. Son los que el codigo de Nebula referencia desde el enum PermisoOperacion de nebula-models.
| Proceso | Aprobar | Anular |
|---|---|---|
| Disponibilidad presupuestal | APROBAR_DISPONIBILIDAD |
ANULAR_DISPONIBILIDAD |
| Compromiso (registro presupuestal) | APROBAR_COMPROMISO |
ANULAR_COMPROMISO |
| Modificacion presupuestal | APROBAR_MODIFICACION_PRESUPUESTAL |
ANULAR_MODIFICACION_PRESUPUESTAL |
| Anticipo | APROBAR_ANTICIPO |
ANULAR_ANTICIPO |
| Causacion | APROBAR_CAUSACION |
ANULAR_CAUSACION |
| Orden de pago | APROBAR_ORDEN_PAGO |
ANULAR_ORDEN_PAGO |
| Traslado | APROBAR_TRASLADO |
ANULAR_TRASLADO |
| Comprobante de egreso | APROBAR_COMPROBANTE_EGRESO |
ANULAR_COMPROBANTE_EGRESO |
| Comprobante de ingreso | APROBAR_COMPROBANTE_INGRESO |
ANULAR_COMPROBANTE_INGRESO |
| Cuenta por cobrar | APROBAR_CUENTA_POR_COBRAR |
ANULAR_CUENTA_POR_COBRAR |
| Cuenta por pagar | APROBAR_CUENTA_POR_PAGAR |
ANULAR_CUENTA_POR_PAGAR |
La siembra es idempotente por
(tenant, codigo)y no pisa lo que el cliente haya anexado. Un permiso creado por el negocio convive con estos y se verifica exactamente igual.
Un servicio de negocio no llama la API por HTTP a mano: usa el par de clientes compartidos de nebula-shared, que existe en version bloqueante y reactiva.
| Cliente | Metodo | Endpoint que consume |
|---|---|---|
PermisoOperacionBlockingClient |
permisosDeLaSesion(authorization) |
GET /by-token |
permisosDelRol(rolCodigo, authorization) |
GET /by-rol |
|
permisosDelUsuario(codigoUsuario, authorization) |
GET /by-usuario |
|
verificar(rolCodigo, permisoCodigo, authorization) |
GET /verificar |
|
verificarSesion(permisoCodigo, authorization) |
GET /verificar-token |
|
verificarUsuario(codigoUsuario, permisoCodigo, authorization) |
GET /verificar-usuario |
|
usuariosConPermisos(permisoCodigos, authorization) |
POST /usuarios-con-permisos |
|
PermisoOperacionReactiveClient |
Mismas operaciones | Version reactiva del par |
El Authorization se propaga: el cliente reenvia el token de la peticion en curso, y con el viaja el tenant.
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.1.0 | 2026-09-01 | Carlos Torres | Consideraciones de uso: la API es de consulta, la gestion es potestad administrativa y el ambiente que hoy la permite es una concesion de desarrollo |
| 1.0.2 | 2026-09-01 | Carlos Torres | La API queda como pagina propia de la seccion, autocontenida; api-backend es solo el punto de entrada |
| 1.0.1 | 2026-09-01 | Carlos Torres | La documentacion sale de la entrada api-backend |
| 1.0.0 | 2026-09-01 | Carlos Torres | Publicacion de la API: catalogo de permisos de operacion, asignacion rol-permiso, verificacion por rol / sesion / persona y consulta inversa de usuarios con permisos |