Tenedores de tokens

Requisitos previos de acceso

• Permiso (módulo): manageToken
• Licencia/Feature: Ninguna
• Contenedor del menú: GENERAL → grupo Usuarios

Qué es / cuándo usar

Pantalla de consulta que lista quién tiene saldo de un token específico y cuánto posee cada cliente. El operador elige un token en el cuadro de selección y la pantalla devuelve, para ese token, el saldo de cada billetera (con el correo electrónico del titular). Úsela para auditoría de distribución de un token, verificación de circulación, levantamiento de tenedores para un evento (snapshot, distribución) o simplemente para investigar la posición de un activo en la base.

Es una pantalla de solo lectura: no acredita, debita ni mueve saldos. Para operar sobre el saldo de un cliente, use las acciones en Detalles del usuario.

Requisitos previos

• Permiso: manageToken registrado para el rol del operador (control de acceso del ítem de menú). El permiso es doble — enum estático CPM + módulo dinámico en la DB; ambos deben estar asociados al rol para que la pantalla aparezca. En el API-Gateway, el endpoint de saldos por unidad (readAllForUnit) es validado por viewGeneralJournal — asegúrese de que el rol del operador también lo tenga para que la consulta no devuelva error.
• Licencia/Feature: ninguna.
• Dependencias de otras pantallas: el token debe existir (registrado en Tokenización → Gestionar Tokens) para aparecer en el cuadro de selección.

Paso a paso

1. Acceda al menú Usuarios → Tenedores de tokens (/manage-owners).
2. En el cuadro de selección, elija el token cuyos tenedores desea consultar.
3. La tabla carga automáticamente los tenedores con su correo electrónico y saldo.
4. Haga clic en el ícono de visualizar (ojo) en una fila para abrir los Detalles del usuario de ese tenedor.
5. Opcional: haga clic en Exportar para descargar la lista de tenedores del token en CSV.

Filtros y columnas

Filtro / Columna	Qué muestra	Origen del dato
Selección de token	Lista todos los tokens registrados; al cambiar, dispara la búsqueda (search)	getTokens (TokenController / obs-lib)
Columna Correo (Nombre)	Correo electrónico del titular de la billetera tenedora	Cruce customerId → user.email (lista de usuarios cargada en initData)
Columna Valor (Saldo)	Saldo del token en esa billetera, mostrado con 2–8 decimales	balance de cada AccountBalance devuelto por readAllForUnit(unitOfMoney) (FinLib) — considera solo movimientos de billetera (CREDIT/DEBIT)
Acción Visualizar	Abre los Detalles del usuario del tenedor	Navega a /users/informations/details?userEmail=...

Acciones y modales

• Seleccionar token: cambiar el token en el cuadro de selección re-ejecuta la consulta readAllForUnit para la nueva unidad.
• Exportar (CSV): genera un CSV en el navegador con las columnas name (correo) y amount (saldo) de los tenedores listados. El archivo se construye en el front (sin llamada extra al backend) y se nombra transactions_<fecha>.csv.
• Visualizar (ojo): abre los Detalles del usuario del tenedor, donde están las acciones administrativas individuales.

Reglas de negocio / consideraciones

Atención

• Saldo ≠ disponible para retiro. El número mostrado es el saldo contable de la billetera para ese token. Bloqueos como billetera en captación (estado de captación del captador), holds u órdenes abiertas no se descuentan en esta vista — un tenedor puede aparecer con saldo aquí y aun así estar bloqueado para retiro/transferencia. Para el estado operacional del cliente, verifique los Detalles del usuario.
• La lista depende del cruce con la base de usuarios. El correo proviene del emparejamiento customerId → usuario; billeteras técnicas/de sistema (ej.: propietario del token, sinks) pueden aparecer sin correo legible.

• Valores financieros: los saldos provienen de FinLib y se tratan con precisión (BigNumber) — la UI solo los formatea a 2–8 decimales para la visualización. Para una verificación exacta, use el saldo bruto (exportar/CSV) y respete los decimales del token.

Pantallas relacionadas

• Detalles del usuario — acciones administrativas sobre el saldo de un tenedor.
• Gestionar Tokens — donde se registran los tokens listados en la selección.
• Saldos (Dashboard) — vista agregada de saldos de la plataforma.