Sincronismos de Depósitos

Pré-requisitos de acesso

• Permissão (módulo): viewDeposits — e, para o modo Por hash da transação, também syncDepositFromChain
• Licença/Feature: DEPOSITS_HANDLING
• Contêiner do menu: GERAL → grupo Operações

O que é / quando usar

Ferramenta de recuperação de depósitos on-chain que não chegaram à carteira do cliente. A tela tem dois modos:

• Por hash da transação (recomendado) — você informa a rede e o hash. O sistema lê a transação on-chain, credita o depósito e ainda confere se o webhook daquela carteira está configurado corretamente na Tatum, criando ou corrigindo o que estiver errado. É o modo que resolve a causa raiz do chamado.
• Por bloco — reprocessa um bloco inteiro. Use quando não tiver o hash, quando a rede não for coberta pelo modo por hash, ou quando precisar varrer várias transações de uma vez.

Por que o depósito não chegou

O crédito automático depende de um webhook que a Tatum dispara quando a carteira do cliente recebe valor. Se aquela carteira não tem webhook cadastrado, ou se o webhook aponta para uma URL de callback antiga (troca de domínio, de ambiente), o valor entra na blockchain e nada acontece na plataforma. Reprocessar o bloco credita aquele depósito, mas o próximo depósito na mesma carteira falha de novo. O modo por hash conserta a configuração, e é por isso que ele é o preferido.

Pré-condições

• Permissão: viewDeposits para abrir a tela; syncDepositFromChain para usar o modo por hash (permissão dupla — enum CPM + módulo dinâmico no DB). Sem syncDepositFromChain, o seletor de modo não aparece e só o modo por bloco fica disponível.
• Licença/Feature: DEPOSITS_HANDLING habilitada (sem ela o item nem aparece no menu).
• Dependências de outras telas: o usuário-destino do depósito on-chain deve ter carteira mapeada; a transação precisa ter como destinatário uma carteira monitorada para gerar crédito.

Modo 1 — Por hash da transação

Redes cobertas

Ethereum, Polygon, BSC, TRON e Bitcoin. Para Solana, XRPL e demais redes, use o modo por bloco — no seletor, as redes não cobertas aparecem desabilitadas.

Passo a passo

1. Acesse o menu Operações → Sincronismos de Depósitos.
2. Mantenha o modo Por hash da transação selecionado.
3. Selecione a Rede em que o depósito foi feito.
4. Cole o Hash da transação, exatamente como aparece no explorador da rede (o campo é trimado; obrigatório).
5. Confirme em Sincronizar transação e aguarde — a consulta é síncrona e pode levar alguns segundos.
6. Leia o laudo que aparece abaixo do formulário.

Lendo o laudo

O laudo tem duas tabelas. A primeira, Depósitos, mostra o que aconteceu com cada valor recebido por uma carteira do sistema:

Situação	O que significa	O que fazer
Creditado	O depósito foi lançado agora no saldo do cliente	Nada — encerre o chamado
Já creditado	O depósito já havia sido lançado antes	Nada — confira o saldo/extrato do cliente para confirmar
Ignorado	Não há crédito a fazer: transferência interna entre carteiras da plataforma, valor zero, ou moeda/token não cadastrado	Ler a coluna Detalhe; se disser que a moeda não é suportada, cadastre o token antes de repetir
Falhou	O sistema tentou creditar e não conseguiu	Ler a coluna Detalhe e seguir para o crédito manual (abaixo)

A segunda, Webhooks na Tatum, mostra a conferência da configuração da carteira:

Ação	O que significa
Já correto	O webhook existia e apontava para a URL certa — nada foi alterado
Criado	A carteira não tinha webhook nenhum; foi criado agora
Corrigido	O webhook apontava para outra URL; foi recriado com a URL correta (a URL antiga aparece no detalhe)
Falhou	A Tatum recusou a operação — leia o detalhe e acione o time técnico

Quando houver Criado ou Corrigido, a tela destaca um aviso: a partir dali os próximos depósitos daquela carteira chegam sozinhos.

Webhook corrigido, mas a transação não processou

São duas coisas independentes, e é normal uma dar certo e a outra não.

Se o laudo disser que o webhook foi Criado ou Corrigido, mas o depósito ficar como Falhou (ou nenhuma linha aparecer em Depósitos), o resultado ainda é útil: a configuração da carteira está consertada e os próximos depósitos vão entrar normalmente. Falta só o valor desta transação.

Para esse valor, siga com o crédito manual na ficha do cliente:

1. Abra Usuários → Lista de usuários e entre nos Detalhes do usuário — Geral.
2. Use a ação Creditar saldo (requer o módulo ADMIN_BALANCE_CONTROL).
3. Informe o token e o valor exatamente como estão no laudo (colunas Valor e Ativo) — respeite todas as casas decimais.
4. Descreva o chamado e o hash da transação na justificativa, para o lançamento ficar rastreável na auditoria.

Antes de creditar manualmente, confirme que não houve crédito

O crédito manual não é idempotente: se o valor já entrou, você vai creditar em dobro e não há rollback automático.

Antes de lançar, confira que a linha do laudo não está como Creditado nem Já creditado, e olhe o extrato do cliente procurando o hash da transação. Na dúvida, não credite — acione o time técnico.

Modo 2 — Por bloco

Passo a passo

1. Acesse o menu Operações → Sincronismos de Depósitos.
2. Selecione o modo Por bloco.
3. Selecione a Rede (ex.: Ethereum, BSC, Polygon, Arbitrum, Optimism, Avalanche, Base, Moonbeam) — a lista vem de getNetworks().
4. Informe o Número do bloco a reprocessar (o campo é trimado; obrigatório).
5. Confirme em Reprocessar bloco — chama reprocessBlock({ network, blockNumber }).
6. Acompanhe o feedback (snackbar) de sucesso ou erro.

O modo por bloco não conserta a configuração

Reprocessar o bloco recupera o depósito daquela vez, mas não olha o webhook da carteira. Se a causa for webhook ausente ou com URL errada, o problema volta no próximo depósito. Sempre que tiver o hash em mãos e a rede for coberta, prefira o modo por hash.

Campos

Campo	O que é	Obrigatório?	Efeito no sistema/backend
Rede	Blockchain alvo	Sim	Define a chain consultada pelo ExternalBlockchainProvider; valida contra a lista de redes habilitadas. No modo por hash, redes não cobertas ficam desabilitadas
Hash da transação	Identificador da transação on-chain	Sim (modo por hash)	Dispara syncTransactionByHash({ network, txHash }): lê a transação, credita as pernas destinadas a carteiras do sistema e audita os webhooks das carteiras envolvidas
Número do bloco	Bloco a reprocessar	Sim (modo por bloco)	Dispara a releitura do bloco; transações para carteiras monitoradas geram crédito via FMS (idempotente por txHash)

Ações e modais

• Sincronizar transação: valida o formulário, faz trim no hash e chama syncTransactionByHash. O formulário não é limpo no sucesso — o hash continua na tela para você copiar no chamado. O laudo aparece abaixo do formulário.
• Reprocessar bloco: valida o formulário, faz trim no número do bloco e chama reprocessBlock. Em sucesso, limpa o formulário; em erro, exibe a mensagem retornada pelo backend.

Regras de negócio / cuidados

Atenção

• Rede e hash precisam bater. Um hash válido consultado na rede errada retorna "transação não localizada". Confira no explorador antes de abrir chamado técnico.
• No modo por bloco, informe o número do bloco exato — reprocessar a faixa errada não cria o crédito faltante.
• Se a lista de redes não carregar, a tela exibe erro — verifique a disponibilidade do serviço antes de tentar.
• Transferências nativas feitas por chamada interna de contrato não são detectadas pelo modo por hash; nesses casos use o modo por bloco. Transferências de token aparecem normalmente.
• A moeda fiduciária padrão do tenant e a ponte USD→EUR afetam a leitura/conciliação dos valores creditados.

• Valores financeiros: tratados como BigNumber — sem arredondamento. Ao copiar um valor do laudo para o crédito manual, mantenha todas as casas decimais.
• Idempotência: o crédito é idempotente por txHash — sincronizar a mesma transação (ou reprocessar o mesmo bloco) várias vezes não duplica crédito. Se o FinLib retornar E00021 "already processed", aquele depósito já havia sido creditado (sucesso). O crédito manual não tem essa proteção.
• Transação com mais de um destinatário: se a mesma transação pagar duas carteiras do sistema, a idempotência por hash faz com que apenas a primeira perna gere lançamento. O laudo avisa quando isso acontece — as demais precisam de crédito manual.
• Status APPROVED: o crédito ao usuário pressupõe usuário APPROVED.
• Conserto pontual, não em massa: o modo por hash conserta o webhook das carteiras daquela transação. Para uma correção ampla, acione o time técnico.

Telas relacionadas

• Detalhes do usuário — Geral — onde fica o crédito manual de saldo
• Gerenciar Pagamentos Manuais
• Gerenciar Saques
• Voltar ao índice Financeiro