Conexión de Cuentas Bancarias

El módulo de Banca permite conectar sus cuentas bancarias a ALTUM ERP mediante la API de open banking Belvo, de modo que los movimientos se importen automáticamente y puedan conciliarse con los registros del sistema.

Requisitos previos

• Contar con credenciales de la institución bancaria que desea vincular.
• Tener el permiso de autenticación JWT activo (la ruta /banca/cuentas está protegida por JwtAuthGuard).
• Un máximo de 10 conexiones activas por empresa (tenant). Si se alcanza el límite, debe desconectar alguna cuenta antes de agregar una nueva.

Nota

El módulo de Banca sólo está disponible si el administrador de la plataforma configuró las variables de entorno BELVO_SECRET_KEY_ID y BELVO_SECRET_KEY_PASSWORD. Si las tarjetas no cargan, contacte a su administrador.

Pantalla principal

Acceda al módulo desde el menú lateral: Banca. Verá cuatro indicadores clave:

Indicador	Descripción
Conexiones activas	Cuentas actualmente vinculadas / total
Transacciones este mes	Total importadas en el mes actual
Tasa de conciliación	Porcentaje de movimientos emparejados
Pendientes de conciliar	Movimientos que requieren atención

Desde la pantalla principal también puede acceder a:

• Cuentas bancarias — lista y gestión de conexiones (/banca/cuentas)
• Transacciones — tabla de movimientos importados (/banca/transacciones)
• Conciliación — emparejamiento de movimientos (/banca/conciliacion)
• Flujo de efectivo — dashboard de entradas y salidas (/banca/flujo-efectivo)

Conectar una cuenta bancaria

Paso 1: Abrir el diálogo de conexión

1. Diríjase a Banca > Cuentas bancarias (botón Conectar banco en la esquina superior derecha).
2. También puede usar el botón Conectar banco desde la pantalla principal del módulo.

Paso 2: Ingresar los datos de conexión

En el diálogo que aparece complete los tres campos:

Campo	Descripción	Ejemplo
ID de institución	Identificador de Belvo para el banco	banamex, bbva, santander
Token público	Token generado por el widget de Belvo para la sesión de conexión	public-sandbox-xxxx...
Alias de cuenta (opcional)	Nombre que distinguirá esta cuenta en el sistema	Cuenta corriente principal

Precaución

El token público es generado por el widget de Belvo durante el flujo de autenticación con su banco. Nunca comparta ni reutilice tokens de sesiones anteriores.

Paso 3: Confirmar la conexión

Haga clic en Conectar. El sistema:

1. Crea un token de acceso mediante la API de Belvo.
2. Consulta las cuentas asociadas al enlace (puede haber más de una por banco).
3. Crea un registro BankConnection por cada cuenta encontrada, con estado ACTIVE.
4. Registra la operación en el log de auditoría del módulo BANCA.

Si la conexión es exitosa, las cuentas aparecerán en la lista con estado Activa.

Información de cada cuenta

Cada tarjeta de cuenta muestra:

• Institución y alias (si se configuró)
• Número de cuenta enmascarado (sólo los últimos 4 dígitos)
• Saldo actual y saldo disponible en MXN
• Última sincronización y próxima sincronización programada
• Estado de la conexión (ver tabla siguiente)

Estados de conexión

Estado	Descripción
Activa	Funcionando correctamente
Inactiva	Desactivada; no sincroniza
Error	Fallo en la última sincronización
Requiere reautenticación	La sesión expiró; reinicie el flujo con Belvo
Sincronizando	Importación en progreso

Sincronizar manualmente

Desde la tarjeta de cada cuenta, haga clic en Sincronizar para importar movimientos de inmediato.

El sistema calcula el rango de fechas automáticamente:

• Si la cuenta ya fue sincronizada antes: desde la fecha de la última sincronización hasta hoy.
• Primera vez: últimos 90 días como retroalimentación inicial.

La frecuencia automática configurada por defecto es diaria a las 6:00 AM (hora del servidor).

También puede usar el botón Sincronizar todo en la pantalla principal para sincronizar todas las cuentas activas en secuencia.

Reautenticar una conexión

Si una cuenta muestra el estado Requiere reautenticación:

1. Localice la tarjeta de la cuenta afectada.
2. Haga clic en Reautenticar.
3. Complete el flujo de autenticación con su banco en el widget de Belvo.

Esto actualiza el enlace sin eliminar el historial de transacciones existente.

Desconectar una cuenta

1. Haga clic en Desconectar en la tarjeta de la cuenta.
2. Confirme la acción en el diálogo de advertencia.

Nota

Al desconectar, los datos históricos de transacciones se conservan en el sistema. Esta acción sólo elimina la conexión activa con Belvo. No se puede deshacer.

Tipos de cuenta reconocidos

El sistema clasifica automáticamente las cuentas según la respuesta de Belvo:

Tipo Belvo	Tipo en sistema
CHECKING / CUENTA	Cuenta de cheques
SAV / AHORRO	Cuenta de ahorro
CRED / TARJETA	Tarjeta de crédito
(otros)	Cuenta de cheques (predeterminado)

Casos frecuentes

No aparecen cuentas tras conectar Belvo devolvió un enlace pero sin cuentas asociadas. Verifique que la institución bancaria seleccionada tiene cuentas activas en el RFC asociado y vuelva a intentar la conexión.

La tarjeta muestra “Error” después de sincronizar Revise el mensaje de error en la tarjeta. Si menciona código 401, la sesión de Belvo expiró; use Reautenticar. Para otros errores, contacte al soporte.

Se alcanzó el límite de 10 conexiones Desconecte una cuenta que ya no necesite antes de agregar una nueva.

Los saldos no coinciden con el portal del banco Los saldos se actualizan en cada sincronización. Si la última fue hace varias horas, sincronice manualmente para obtener el saldo más reciente.