Appearance
Matriz de Roles y Permisos
PROXIMITI utiliza cuatro roles gestionados por Keycloak. Cada rol otorga acceso a endpoints especificos del BFF y pantallas del portal/app. Los roles estan embebidos en el token JWT bajo realm_access.roles.
Roles
| Rol | Audiencia | Canal de Acceso |
|---|---|---|
USER_PUDO | Operadores de centro PUDO | App Flutter PUDO Manager, Portal Cliente |
USER_CARRIER | Conductores transportistas | App Flutter Transportista, Portal Cliente |
USER_ADMIN | Administradores de plataforma | Portal Cliente (panel de administracion) |
USER_CUSTOMER | Clientes finales / remitentes | Portal Cliente (shell de cliente) |
Matriz de Permisos
| Accion | Endpoint | USER_PUDO | USER_CARRIER | USER_ADMIN | USER_CUSTOMER |
|---|---|---|---|---|---|
| Seguimiento de paquete (publico) | GET /api/v1/public/track/{barcode} | --- | --- | --- | --- |
| Ver dashboard | GET /api/v1/dashboard | Si | Si | Si | No |
| Listar expediciones | GET /api/v1/shipments | Si | Si | Si | No |
| Ver detalle de expedicion | GET /api/v1/shipments/{barcode} | Si | Si | Si | No |
| Crear expedicion | POST /api/v1/shipments | Si | Si | Si | No |
| Generar etiqueta | GET /api/v1/shipments/{barcode}/label | Si | Si | Si | No |
| Recibir expedicion en PUDO | POST /api/v1/shipments/{barcode}/receive | Si | No | Si | No |
| Entregar expedicion con POD | POST /api/v1/shipments/{barcode}/deliver | Si | No | Si | No |
| Token de subida POD | POST /api/v1/shipments/{barcode}/pod/upload-token | Si | No | Si | No |
| Ver metadatos POD | GET /api/v1/shipments/{barcode}/pod | Si | Si | Si | No |
| Ver imagen POD | GET /api/v1/shipments/{barcode}/pod/image/{type} | Si | Si | Si | No |
| Iniciar intercambio transportista | POST /api/v1/shipments/{barcode}/carrier-handshake | No | Si | Si | No |
| Validar sesion QR | POST /api/v1/shipments/qr-session/{token}/validate | Si | No | Si | No |
| Consultar estado de sesion QR | GET /api/v1/shipments/qr-session/{token}/status | Si | Si | Si | No |
| Entrega multiple de paquetes | POST /api/v1/shipments/batch-drop | Si | Si | Si | No |
| Recoger paquete caducado | POST /api/v1/shipments/{barcode}/retrieve | No | Si | Si | No |
| Gestionar incidencias/reclamaciones | GET/POST /api/v1/issues/* | Si | Si | Si | No |
| Ver niveles de precios | GET /api/v1/pricing/* | Si | Si | Si | Si |
| Gestionar precios (CRUD) | POST/PUT/DELETE /api/v1/pricing/admin/* | No | No | Si | No |
| Gestionar usuarios | GET/POST /api/v1/admin/users/* | No | No | Si | No |
| Gestionar centros | GET/POST /api/v1/admin/centers/* | No | No | Si | No |
| Sincronizar catalogos de proveedores | POST /api/v1/admin/adapter/* | No | No | Si | No |
| Ver dashboard de cliente | GET /api/v1/customer/dashboard | No | No | No | Si |
| Ver expediciones de cliente | GET /api/v1/customer/shipments | No | No | No | Si |
| Gestionar direcciones de entrega | GET/POST /api/v1/customer/addresses | No | No | No | Si |
| Ver perfil de cliente | GET /api/v1/customer/profile | No | No | No | Si |
INFO
Seguimiento de paquete es el unico endpoint completamente publico (no requiere autenticacion). Todos los demas endpoints requieren un JWT valido. Las marcas --- indican que el endpoint es accesible sin ningun rol.
Resumen de Reglas de Seguridad
El SecurityConfig.java del BFF define estas reglas en orden de precedencia:
/api/v1/public/**—permitAll()(sin autenticacion)/api/v1/customer/**—hasRole("USER_CUSTOMER")/api/v1/admin/**—hasRole("USER_ADMIN")/api/v1/pricing/admin/**—hasRole("USER_ADMIN")/api/v1/shipments/batch-drop—hasAnyRole("USER_PUDO", "USER_CARRIER", "USER_ADMIN")/api/v1/shipments/*/action—hasAnyRole("USER_PUDO", "USER_CARRIER", "USER_ADMIN")- Todo lo demas —
authenticated()(cualquier JWT valido)
WARNING
USER_CUSTOMER no puede acceder a endpoints de operador/admin aunque la regla por defecto sea authenticated(). La regla /api/v1/customer/** coincide primero, y su JWT solo contiene el rol USER_CUSTOMER — quedan excluidos de las verificaciones hasAnyRole en endpoints de accion de expediciones.