Sincronizaciones de Depósitos

Requisitos previos de acceso

• Permiso (módulo): viewDeposits — y, para el modo Por hash de la transacción, también syncDepositFromChain
• Licencia/Feature: DEPOSITS_HANDLING
• Contenedor del menú: GENERAL → grupo Operaciones

Qué es / cuándo usar

Herramienta de recuperación de depósitos on-chain que no llegaron a la billetera del cliente. La pantalla tiene dos modos:

• Por hash de la transacción (recomendado) — usted indica la red y el hash. El sistema lee la transacción on-chain, acredita el depósito y además verifica si el webhook de esa billetera está configurado correctamente en Tatum, creando o corrigiendo lo que esté mal. Es el modo que resuelve la causa raíz del ticket.
• Por bloque — reprocesa un bloque entero. Úselo cuando no tenga el hash, cuando la red no esté cubierta por el modo por hash, o cuando necesite barrer varias transacciones a la vez.

Por qué el depósito no llegó

La acreditación automática depende de un webhook que Tatum dispara cuando la billetera del cliente recibe valor. Si esa billetera no tiene webhook registrado, o si el webhook apunta a una URL de callback antigua (cambio de dominio o de ambiente), el valor entra en la blockchain y no ocurre nada en la plataforma. Reprocesar el bloque acredita ese depósito, pero el siguiente depósito en la misma billetera vuelve a fallar. El modo por hash corrige la configuración, y por eso es el preferido.

Requisitos previos

• Permiso: viewDeposits para abrir la pantalla; syncDepositFromChain para usar el modo por hash (permiso doble — enum CPM + módulo dinámico en DB). Sin syncDepositFromChain, el selector de modo no aparece y solo queda disponible el modo por bloque.
• Licencia/Feature: DEPOSITS_HANDLING habilitada (sin ella el ítem ni siquiera aparece en el menú).
• Dependencias de otras pantallas: el usuario destino del depósito on-chain debe tener una billetera mapeada; la transacción debe tener como destinatario una billetera monitoreada para generar el crédito.

Modo 1 — Por hash de la transacción

Redes cubiertas

Ethereum, Polygon, BSC, TRON y Bitcoin. Para Solana, XRPL y las demás redes, use el modo por bloque — en el selector, las redes no cubiertas aparecen deshabilitadas.

Paso a paso

1. Acceda al menú Operaciones → Sincronizaciones de Depósitos.
2. Mantenga seleccionado el modo Por hash de la transacción.
3. Seleccione la Red en la que se hizo el depósito.
4. Pegue el Hash de la transacción, tal como aparece en el explorador de la red (el campo es recortado; obligatorio).
5. Confirme en Sincronizar transacción y espere — la consulta es sincrónica y puede tardar algunos segundos.
6. Lea el informe que aparece debajo del formulario.

Cómo leer el informe

El informe tiene dos tablas. La primera, Depósitos, muestra qué pasó con cada valor recibido por una billetera del sistema:

Estado	Qué significa	Qué hacer
Acreditado	El depósito acaba de registrarse en el saldo del cliente	Nada — cierre el ticket
Ya acreditado	El depósito ya se había registrado antes	Nada — revise el saldo/extracto del cliente para confirmar
Ignorado	No hay crédito que hacer: transferencia interna entre billeteras de la plataforma, valor cero, o moneda/token no registrado	Lea la columna Detalle; si dice que la moneda no está soportada, registre el token antes de reintentar
Falló	El sistema intentó acreditar y no pudo	Lea la columna Detalle y siga con el crédito manual (abajo)

La segunda, Webhooks en Tatum, muestra la verificación de la configuración de la billetera:

Acción	Qué significa
Ya correcto	El webhook existía y apuntaba a la URL correcta — no se modificó nada
Creado	La billetera no tenía ningún webhook; se creó ahora
Corregido	El webhook apuntaba a otra URL; se recreó con la URL correcta (la URL anterior aparece en el detalle)
Falló	Tatum rechazó la operación — lea el detalle y escale al equipo técnico

Cuando haya Creado o Corregido, la pantalla destaca un aviso: a partir de ahí los próximos depósitos de esa billetera llegan solos.

Webhook corregido, pero la transacción no se procesó

Son dos cosas independientes, y es normal que una funcione y la otra no.

Si el informe dice que el webhook fue Creado o Corregido, pero el depósito queda como Falló (o no aparece ninguna fila en Depósitos), el resultado igual es útil: la configuración de la billetera está arreglada y los próximos depósitos entrarán normalmente. Solo falta el valor de esta transacción.

Para ese valor, siga con el crédito manual en la ficha del cliente:

1. Abra Usuarios → Lista de usuarios y entre en Detalles del usuario - General.
2. Use la acción Acreditar saldo (requiere el módulo ADMIN_BALANCE_CONTROL).
3. Indique el token y el valor exactamente como están en el informe (columnas Importe y Activo) — respete todos los decimales.
4. Describa el ticket y el hash de la transacción en la justificación, para que el registro quede rastreable en la auditoría.

Antes de acreditar manualmente, confirme que no hubo crédito

El crédito manual no es idempotente: si el valor ya entró, lo acreditará dos veces y no hay rollback automático.

Antes de registrar, confirme que la fila del informe no esté como Acreditado ni Ya acreditado, y revise el extracto del cliente buscando el hash de la transacción. Ante la duda, no acredite — escale al equipo técnico.

Modo 2 — Por bloque

Paso a paso

1. Acceda al menú Operaciones → Sincronizaciones de Depósitos.
2. Seleccione el modo Por bloque.
3. Seleccione la Red (ej.: Ethereum, BSC, Polygon, Arbitrum, Optimism, Avalanche, Base, Moonbeam) — la lista proviene de getNetworks().
4. Ingrese el Número de bloque a reprocesar (el campo es recortado; obligatorio).
5. Confirme en Reprocesar bloque — llama a reprocessBlock({ network, blockNumber }).
6. Observe el feedback (snackbar) de éxito o error.

El modo por bloque no corrige la configuración

Reprocesar el bloque recupera el depósito de esa vez, pero no revisa el webhook de la billetera. Si la causa es un webhook ausente o con URL incorrecta, el problema vuelve en el próximo depósito. Siempre que tenga el hash a mano y la red esté cubierta, prefiera el modo por hash.

Campos

Campo	Qué es	¿Obligatorio?	Efecto en el sistema/backend
Red	Blockchain objetivo	Sí	Define la chain consultada por ExternalBlockchainProvider; valida contra la lista de redes habilitadas. En el modo por hash, las redes no cubiertas quedan deshabilitadas
Hash de la transacción	Identificador de la transacción on-chain	Sí (modo por hash)	Dispara syncTransactionByHash({ network, txHash }): lee la transacción, acredita las patas destinadas a billeteras del sistema y audita los webhooks de las billeteras involucradas
Número de bloque	Bloque a reprocesar	Sí (modo por bloque)	Dispara la relectura del bloque; las transacciones hacia billeteras monitoreadas generan crédito vía FMS (idempotente por txHash)

Acciones y modales

• Sincronizar transacción: valida el formulario, hace trim en el hash y llama a syncTransactionByHash. El formulario no se limpia en caso de éxito — el hash permanece en pantalla para que usted lo copie en el ticket. El informe aparece debajo del formulario.
• Reprocesar bloque: valida el formulario, hace trim en el número de bloque y llama a reprocessBlock. En caso de éxito, limpia el formulario; en error, muestra el mensaje devuelto por el backend.

Reglas de negocio / precauciones

Atención

• La red y el hash deben coincidir. Un hash válido consultado en la red equivocada devuelve "transacción no encontrada". Verifique en el explorador antes de abrir un ticket técnico.
• En el modo por bloque, ingrese el número de bloque exacto — reprocesar el rango incorrecto no creará el crédito faltante.
• Si la lista de redes no carga, la pantalla muestra un error — verifique la disponibilidad del servicio antes de intentar.
• Las transferencias nativas hechas por llamada interna de contrato no son detectadas por el modo por hash; en esos casos use el modo por bloque. Las transferencias de token aparecen normalmente.
• La moneda fiduciaria predeterminada del tenant y el puente USD→EUR afectan la lectura/conciliación de los montos acreditados.

• Valores financieros: tratados como BigNumber — sin redondeo. Al copiar un valor del informe hacia el crédito manual, mantenga todos los decimales.
• Idempotencia: el crédito es idempotente por txHash — sincronizar la misma transacción (o reprocesar el mismo bloque) varias veces no duplica el crédito. Si FinLib devuelve E00021 "already processed", ese depósito ya había sido acreditado (éxito). El crédito manual no tiene esa protección.
• Transacción con más de un destinatario: si la misma transacción paga a dos billeteras del sistema, la idempotencia por hash hace que solo la primera pata genere registro. El informe avisa cuando esto ocurre — las demás necesitan crédito manual.
• Estado APPROVED: el crédito al usuario presupone un usuario con estado APPROVED.
• Corrección puntual, no masiva: el modo por hash corrige el webhook de las billeteras de esa transacción. Para una corrección amplia, escale al equipo técnico.

Pantallas relacionadas

• Detalles del usuario - General — donde está el crédito manual de saldo
• Gestionar Pagos Manuales
• Gestionar Retiros
• Volver al índice Financiero