Skip to main content
Este guia cobre as principais decisões que seu time toma ao integrar o Bank Transfer. Ele também traz as boas práticas para uma experiência do cliente confiável e em conformidade.

​
Decisões de produto

Estas são escolhas que seu time de produto faz na experiência voltada ao cliente. Elas afetam diretamente a satisfação do cliente e o volume de suporte.

​
Mostre a tarifa antes de o cliente confirmar

A etapa initiate retorna o valor da tarifa antes de qualquer movimentação de recursos. Use essa janela para mostrar uma tela de confirmação clara:
Isso reduz reclamações e cancelamentos de clientes surpreendidos por tarifas depois do fato.

​
Trate o horário de funcionamento de forma amigável

A TED OUT está disponível de segunda a sexta, 06:30–17:00 (horário de Brasília). Quando um cliente começa uma transferência fora desse horário, não mostre apenas um erro. Diga quando ele pode tentar de novo:
Para evitar idas e vindas desnecessárias, valide o horário de funcionamento no lado do cliente antes de chamar a API. Você não precisa manter sua própria lista de feriados. O plugin bloqueia fins de semana e feriados do BACEN automaticamente. A fonte da verdade em tempo de execução é a tabela bacen_holidays, que o plugin popula para 2026–2028. O atualizador diário roda por padrão e reaplica a carga embutida. Ele não busca dados ao vivo na ANBIMA, porque a ANBIMA publica apenas uma planilha legada que máquinas não conseguem ler. A carga embutida continua a fonte autoritativa até isso mudar. Quando um feriado rejeita uma transferência, mostre esse motivo ao cliente. Não replique o calendário no cliente. Confie no plugin como fonte da verdade para evitar inconsistências ao longo do tempo.

​
Comunique os limites de transferência antes que os clientes os atinjam

Mostre o limite diário restante do cliente na sua interface de transferência. Mostre antes de ele tentar uma transferência que o plugin rejeita. Por exemplo:

​
Mostre comprovantes de confirmação após a conclusão

Depois que uma transferência TED OUT ou P2P é concluída, mostre (ou ofereça para baixar) um comprovante com:
  • Data e hora da transferência
  • Dados do remetente e do destinatário
  • Valor, tarifa e total
  • confirmationNumber (referência voltada ao cliente)
  • controlNumber (referência do JD SPB, apenas para TED OUT)
Quando você fornece essa informação cedo, reduz os contatos de suporte do tipo “minha transferência saiu?”.

​
Mantenha os clientes informados em tempo real

Use webhooks para enviar atualizações de status da transferência para sua interface conforme elas acontecem. Não faça os clientes atualizarem a tela nem ficarem em dúvida se a transferência deles saiu. Veja webhooks TED para a configuração.

​
Decisões de conformidade

Estes são requisitos que se aplicam à sua integração, independentemente das suas escolhas de produto.

​
LGPD e dados pessoais

Os registros de transferência contêm dados pessoais: nomes de clientes, CPF/CNPJ e dados bancários. Garanta que sua política de privacidade cubra explicitamente os dados de transações financeiras. Não registre CPF/CNPJ em texto claro nos logs. Mascare nas interfaces como ***.***.***-00. Um endpoint dedicado de anonimização para solicitações de direito ao apagamento da LGPD chegará em uma release futura. Até lá, coordene as solicitações de anonimização com seu time de administração de banco de dados.

​
Retenção de dados

O plugin nunca apaga nem expira registros de transferência, então a retenção é sua responsabilidade. Retenha os dados de transferência e auditoria por pelo menos 5 anos, conforme os requisitos de guarda de registros do BACEN para instituições financeiras.

​
Trilha de auditoria e conciliação

Cada transferência gera dois números de referência que você deve armazenar: Mantenha o transferId e o confirmationNumber nos seus próprios registros para conciliação. Para TED OUT, armazene também o controlNumber.

​
Horário de funcionamento

O BACEN determina que a TED opera de segunda a sexta, 06:30–17:00 (horário de Brasília, UTC-3). O plugin aplica essa janela por padrão. Um operador pode ajustar os horários de abertura e fechamento em tempo de execução pelo systemplane, dentro dos limites do BACEN. Trate 06:30–17:00 como a norma e construa sua UX em torno disso. Veja Trate o horário de funcionamento de forma amigável acima.
As transferências P2P não estão sujeitas a restrições de horário de funcionamento e funcionam 24/7.

​
Checklist de integração

Antes de entrar em produção, verifique o seguinte:
  • Chaves de idempotência em todas as operações de escrita: envie um header X-Idempotency com UUID v4 em cada chamada a initiate, process e cancel. Isso evita transferências duplicadas por novas tentativas ou cliques duplos.
  • Endpoint de webhook no ar antes do lançamento: faça o deploy do seu endpoint de webhook e deixe-o acessível antes de entrar em produção. Os eventos de transferência começam a disparar de imediato na primeira transação real.
  • Expiração de 24 horas tratada: uma transferência iniciada expira se o cliente não a confirmar em 24 horas. Se o seu fluxo permitir que o cliente comece uma transferência e volte depois, trate o caso de expiração explicitamente.
  • Backoff exponencial em erros 5xx: implemente nova tentativa com backoff (por exemplo, 2s, 4s, 8s) quando a resposta é 503 ou 500. A indisponibilidade do JD SPB aparece como 503 com um código bruto do fornecedor JD (TRANSPORT, ACE95, …). A indisponibilidade do ledger Midaz aparece como BTF-2000. Não repita a tentativa em loop de imediato.
  • Horário de funcionamento validado no cliente: verifique o horário na interface antes de chamar a API. Isso reduz chamadas de API com falha e dá uma experiência melhor ao cliente.
  • transferId e confirmationNumber armazenados: obrigatórios para conciliação e auditoria. Para TED OUT, armazene também o controlNumber.

​
Tratamento de erros

Use estes cenários de erro para mapear erros da API para mensagens amigáveis ao cliente e definir o caminho de recuperação correto. Para a lista completa de códigos de erro e seus significados, veja a lista de erros TED.