> ## 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 > Práticas para 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) por padrão. 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 partir do seu calendário de feriados embutido para 2026 a 2028. 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. O plugin conta o valor debitado do remetente (`totalAmount`), e o dia vira às 00:00 UTC (21:00 no horário de Brasília). 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, para TED OUT e TED IN) 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](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-webhooks.md) 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`. O plugin não tem endpoint para solicitações de direito ao apagamento da LGPD. ### Retenção de dados > [!WARNING] > > 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: | 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 (TED OUT e TED IN) | 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 e TED IN, 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 mudar a janela em tempo de execução pela chave do systemplane `operating_hours.window`. 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. > [!NOTE] > > 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 tratada**: uma transferência iniciada expira em `expiresAt`: depois de 24 horas ou, para TED OUT, no fechamento da janela de operação daquele dia. Se o seu fluxo permitir que o cliente comece uma transferência e volte depois, trate o caso de expiração explicitamente. * [ ] **Leia antes de tentar de novo após um 5xx**: um `5xx` deixa o resultado desconhecido. Leia a transferência primeiro e tente de novo com backoff (por exemplo, 2s, 4s, 8s) com uma nova chave `X-Idempotency` apenas se a operação não aconteceu. A indisponibilidade do JD SPB aparece como `503` com `BTF-1000` ou `BTF-1003`. 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 e TED IN, 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`, o ledger recusou o débito) | "Sua conta não tem saldo suficiente para esta transferência." | Recuperável. O cliente adiciona fundos ou reduz o valor | | **Limite atingido** (`BTF-0011`) | "Você atingiu seu limite \[diário/mensal] de transferência de R\$ \[X]." | Recuperável. Aguarde a redefinição: 00:00 UTC para o limite diário, o primeiro dia do mês (UTC) para o limite mensal | | **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** (`BTF-1000` ou `BTF-1003`, HTTP `503`) | "O serviço de transferência está temporariamente indisponível. Manteremos você informado." | Leia a transferência indicada em `transferId` antes de qualquer nova tentativa | | **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](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/ted-error-list.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.