> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Boas práticas > Aplique padrões comprovados ao integrar o Bank Transfer: mostre as tarifas antes da confirmação, trate as janelas de liquidação e reduza as reclamações dos clientes. 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: ``` Confirm transfer Recipient: Maria Silva — Bradesco (237) Amount: R$ 1,000.00 Fee: R$ 1.50 ───────────────────── Total: R$ 1,001.50 [ Cancel ] [ Confirm ] ``` 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: ``` TED transfers are available Monday to Friday, 06:30 to 17:00. Next available time: Monday at 06:30. ``` 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: ``` Daily limit: R$ 50,000.00 Used today: R$ 45,000.00 Available: R$ 5,000.00 ``` ### 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](/pt/interfaces/ted-jd/ted-webhooks) 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. | Tipo de dado | Período de retenção | | ---------------------- | --------------------------------- | | Registros de transação | 5 anos (exigência do BACEN) | | Logs da aplicação | 90 dias | | Dados de auditoria | 5 anos (anonimizados após 2 anos) | ### Trilha de auditoria e conciliação Cada transferência gera dois números de referência que você deve armazenar: | Campo | O que é | Quando usar | | -------------------- | ------------------------------------- | ----------------------------------------------------- | | `transferId` | Identificador interno da Lerian | Consultas de API, casos de suporte | | `confirmationNumber` | Referência legível pelo usuário | Comprovantes, comunicação com o cliente | | `controlNumber` | Referência do JD SPB (apenas TED OUT) | Trilha de auditoria do BACEN, relatórios regulatórios | 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](#handle-operating-hours-gracefully) 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. | Cenário | Mensagem para o cliente | Recuperação | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | **Fora do horário de funcionamento** (`BTF-0010`) | "As transferências TED estão disponíveis de segunda a sexta, 06:30–17:00. Próximo horário disponível: \[data/hora]." | Recuperável — aguarde a próxima janela | | **Saldo insuficiente** (`BTF-2003`, HTTP `422`) | "Sua conta não tem saldo suficiente para esta transferência." | Recuperável — o cliente adiciona fundos ou reduz o valor | | **Limite diário atingido** (`BTF-0011`) | "Você atingiu seu limite diário de transferência de R\$ \[X]. O limite é redefinido à meia-noite." | Recuperável — aguarde a redefinição | | **Destinatário inválido** (`BTF-0500`) | "Conta de destino não encontrada. Verifique os dados da conta e tente de novo." | Recuperável — o cliente corrige os dados | | **Serviço indisponível** (`TRANSPORT`, HTTP `503`, código bruto da JD) | "O serviço de transferência está temporariamente indisponível. Tente de novo em alguns minutos." | Recuperável — nova tentativa com backoff | | **Transferência duplicada** (`BTF-0012`) | "Uma transferência idêntica foi enviada há pouco. Se isso foi intencional, espere um momento e tente de novo." | Condicional — aguarde a janela de deduplicação passar | Para a lista completa de códigos de erro e seus significados, veja a [lista de erros TED](/pt/reference/interfaces/ted-jd/ted-error-list).