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:
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: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: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)
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 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
| 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 |
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). Essa janela é fixa e não configurável. Construa sua UX em torno dela — consulte 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-Idempotencyem cada chamada parainitiate,processecancel. 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) para códigos de erro com retry (
BTF-1000,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
transferIdquantoconfirmationNumberarmazenados — Necessários para reconciliação e auditoria. Para TED OUT, armazene também ocontrolNumber.
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 | Código de erro | Recuperável | Ação |
|---|---|---|---|---|
| Fora do horário | ”Transferências TED estão disponíveis de segunda a sexta, das 06:30 às 17:00. Próximo horário: [data/hora].” | BTF-0010 | Sim | Aguardar próxima janela |
| Saldo insuficiente | ”Sua conta não tem saldo suficiente para esta transferência.” | BTF-0001 | Sim | Cliente adiciona fundos ou reduz o valor |
| Limite diário atingido | ”Você atingiu seu limite diário de transferências de R$ [X]. O limite é resetado à meia-noite.” | BTF-0011 | Sim | Aguardar reset |
| Destinatário inválido | ”Conta de destino não encontrada. Verifique os dados da conta e tente novamente.” | BTF-0500 | Sim | Cliente corrige os dados |
| Serviço indisponível | ”Serviço de transferência temporariamente indisponível. Tente novamente em alguns minutos.” | BTF-1000 | Sim | Retry com backoff |
| Transferência duplicada | ”Uma transferência idêntica foi enviada recentemente. Se foi intencional, aguarde um momento e tente novamente.” | BTF-0012 | Condicional | Aguardar a janela de deduplicação encerrar |