> ## 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 consolidados ao integrar o Bank Transfer — mostre tarifas antes da confirmação, lide com janelas de liquidação e reduza reclamações.
Este guia cobre as principais decisões que seu time precisa tomar ao integrar o Bank Transfer, e as boas práticas para garantir uma experiência confiável e em conformidade para seus clientes.
## 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.
### Exiba a tarifa antes do cliente confirmar
O fluxo de duas etapas (`initiate` → `process`) foi projetado para isso: seu sistema recebe o valor da tarifa antes de qualquer movimentação de fundos. Use esse intervalo para exibir uma tela de confirmação clara:
```
Confirmar transferência
Destinatário: Maria Silva — Bradesco (237)
Valor: R$ 1.000,00
Tarifa: R$ 1,50
─────────────────────
Total: R$ 1.001,50
[ Cancelar ] [ Confirmar ]
```
Isso reduz reclamações e cancelamentos de clientes surpreendidos com tarifas após a conclusão.
### Trate os horários de funcionamento com clareza
O TED OUT está disponível de segunda a sexta-feira, das 06:30 às 17:00 (horário de Brasília). Quando um cliente tentar iniciar uma transferência fora desse horário, não exiba apenas um erro — informe quando ele poderá tentar novamente:
```
Transferências TED estão disponíveis de segunda a sexta-feira, das 06:30 às 17:00.
Próximo horário disponível: segunda-feira às 06:30.
```
Para evitar chamadas desnecessárias, valide os horários de funcionamento no lado do cliente antes de chamar a API.
Não é necessário manter sua própria lista de feriados — o plugin já bloqueia automaticamente fins de semana e feriados do BACEN. A fonte da verdade em runtime é a tabela `bacen_holidays`, com seed para 2026–2099. O refresher diário roda por padrão e reaplica a seed embutida; ele não busca dados em tempo real da ANBIMA, porque a ANBIMA só publica uma planilha legada não legível por máquina — a seed é a fonte autoritativa até que isso mude.
Se uma transferência for rejeitada por feriado, exponha esse motivo ao cliente. Em vez de replicar 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
Exiba o limite diário restante do cliente em sua interface de transferência — antes que ele tente uma transferência que será rejeitada. Por exemplo:
```
Limite diário: R$ 50.000,00
Utilizado hoje: R$ 45.000,00
Disponível: R$ 5.000,00
```
### Exiba comprovantes após a conclusão
Após a conclusão de uma transferência TED OUT ou P2P, exiba — ou ofereça para download — um comprovante com:
* Data e hora da transferência
* Dados do remetente e destinatário
* Valor, tarifa e total
* `confirmationNumber` (sua referência interna)
* `controlNumber` (referência JD SPB, somente para TED OUT)
Fornecer essas informações proativamente reduz contatos de suporte do tipo "minha transferência foi concluída?".
### Mantenha os clientes informados em tempo real
Use webhooks para enviar atualizações de status da transferência para sua interface assim que elas acontecem. Não faça os clientes atualizarem a página ou se perguntarem se a transferência foi concluída. Consulte [Webhooks do TED](/pt/rails/ted/jd/ted-webhooks) para 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. Certifique-se de que sua política de privacidade cubra explicitamente os dados de transações financeiras. Evite registrar CPF/CNPJ em texto simples; mascare-os nas interfaces como `***.***.***-00`.
Um endpoint dedicado de anonimização para solicitações de direito ao esquecimento da LGPD está planejado para uma versão futura. Até lá, coordene as solicitações de anonimização com sua equipe de administração de banco de dados.
### Retenção de dados
Os dados de transferência devem ser retidos por **5 anos** conforme a Resolução 4.753/2019 do BACEN. Isso não é configurável e não pode ser reduzido.
| Tipo de dado | Período de retenção |
| ---------------------- | --------------------------------- |
| Registros de transação | 5 anos (requisito BACEN) |
| Logs de aplicação | 90 dias |
| Dados de auditoria | 5 anos (anonimizados após 2 anos) |
### Trilha de auditoria e reconciliação
Cada transferência gera dois números de referência que você deve armazenar:
| Campo | O que é | Quando usar |
| -------------------- | ------------------------------- | ------------------------------------------------ |
| `transferId` | Identificador interno Lerian | Consultas na API, casos de suporte |
| `confirmationNumber` | Referência legível pelo usuário | Comprovantes, comunicação com o cliente |
| `controlNumber` | Referência JD SPB (só TED OUT) | Trilha de auditoria BACEN, reportes regulatórios |
Mantenha tanto o `transferId` quanto o `confirmationNumber` em seus próprios registros para reconciliação. Para TED OUT, armazene também o `controlNumber`.
### Horários de funcionamento
O BACEN determina que o TED opera de segunda a sexta-feira, das 06:30 às 17:00 (horário de Brasília, UTC-3). O plugin impõe essa janela por padrão; os horários de abertura/fechamento são ajustáveis pelo operador em runtime (dentro dos limites do BACEN) via systemplane, mas trate 06:30–17:00 como a norma. Construa sua UX em torno dela — consulte [Trate os horários de funcionamento com clareza](#trate-os-horários-de-funcionamento-com-clareza) acima.
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 UUID v4 `X-Idempotency` em cada chamada para `initiate`, `process` e `cancel`. Isso evita transferências duplicadas por tentativas de retry ou duplo clique.
* [ ] **Endpoint de webhook ativo antes do lançamento** — Seu endpoint de webhook deve estar implantado e acessível antes de entrar em produção. Os eventos de transferência começam a disparar imediatamente na primeira transação real.
* [ ] **Expiração de 24 horas tratada** — Uma transferência iniciada expira se não for confirmada em 24 horas. Se seu fluxo permite que um cliente inicie uma transferência e retorne depois, trate o caso de expiração explicitamente.
* [ ] **Backoff exponencial em erros 5xx** — Implemente retry com backoff (ex: 2s, 4s, 8s) quando a resposta for `503` ou `500`. A indisponibilidade do JD SPB aparece como `503` com o código de fornecedor JD sem transformação (`TRANSPORT`, `ACE95`, …); a indisponibilidade do ledger Midaz aparece como `BTF-2000`. Não tente novamente imediatamente em loop.
* [ ] **Horários de funcionamento validados no lado do cliente** — Verifique os horários na interface antes de chamar a API. Reduz chamadas de API desnecessárias e proporciona uma melhor experiência ao cliente.
* [ ] **Tanto `transferId` quanto `confirmationNumber` armazenados** — Necessários para reconciliaçã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 ao cliente | Recuperação |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| **Fora do horário de funcionamento** (`BTF-0010`) | "Transferências TED estão disponíveis de segunda a sexta, das 06:30 às 17:00. Próximo horário: \[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ências de R\$ \[X]. O limite é resetado à meia-noite." | Recuperável — aguarde o reset |
| **Destinatário inválido** (`BTF-0500`) | "Conta de destino não encontrada. Verifique os dados da conta e tente novamente." | Recuperável — o cliente corrige os dados |
| **Serviço indisponível** (`TRANSPORT`, HTTP `503`, código JD sem transformação) | "Serviço de transferência temporariamente indisponível. Tente novamente em alguns minutos." | Recuperável — retry com backoff |
| **Transferência duplicada** (`BTF-0012`) | "Uma transferência idêntica foi enviada recentemente. Se foi intencional, aguarde um momento e tente novamente." | Condicional — aguarde a janela de deduplicação encerrar |
Para a lista completa de códigos de erro e seus significados, consulte a [lista de erros do TED](/pt/reference/midaz/plugins/ted/ted-error-list).