Decisiones de producto
Estas son las decisiones que su equipo de producto toma en la experiencia orientada al cliente. Afectan directamente la satisfacción del cliente y el volumen de soporte.
Muestre la tarifa antes de que el cliente confirme
El flujo de dos pasos (initiate → process) está diseñado para esto: su sistema recibe el monto de la tarifa antes de que se muevan los fondos. Use esa ventana para mostrar una pantalla de confirmación clara:
Maneje el horario de funcionamiento con elegancia
TED OUT está disponible de lunes a viernes, de 06:30 a 17:00 (horario de Brasilia). Cuando un cliente intenta iniciar fuera de ese horario, no muestre solo un error — dígale cuándo podrá intentarlo de nuevo:Comunique los límites de transferencia antes de que los clientes los alcancen
Muestre el límite diario restante del cliente en su interfaz de transferencia — antes de que intente una transferencia que será rechazada. Por ejemplo:Muestre comprobantes de confirmación después de la finalización
Después de que se complete una transferencia TED OUT o P2P, muestre — u ofrezca descargar — un comprobante con:- Fecha y hora de la transferencia
- Datos del remitente y destinatario
- Monto, tarifa y total
confirmationNumber(su referencia interna)controlNumber(referencia JD SPB, solo para TED OUT)
Mantenga a los clientes informados en tiempo real
Use webhooks para enviar actualizaciones del estado de la transferencia a su interfaz a medida que ocurren. No haga que los clientes actualicen la página ni se pregunten si su transferencia fue procesada. Consulte Webhooks de TED para la configuración.Decisiones de cumplimiento
Estos son los requisitos que aplican a su integración independientemente de sus decisiones de producto.
LGPD y datos personales
Los registros de transferencia contienen datos personales — nombres de clientes, CPF/CNPJ y datos bancarios. Asegúrese de que su política de privacidad cubra explícitamente los datos de transacciones financieras. Evite registrar CPF/CNPJ en texto claro; enmascare en interfaces como***.***.***-00.
Un endpoint dedicado de anonimización para solicitudes de derecho al olvido de la LGPD está planificado para una versión futura. Hasta entonces, coordine las solicitudes de anonimización con su equipo de administración de base de datos.
Retención de datos
| Tipo de dato | Período de retención |
|---|---|
| Registros de transacción | 5 años (requisito BACEN) |
| Logs de aplicación | 90 días |
| Datos de auditoría | 5 años (anonimizados después de 2 años) |
Registro de auditoría y reconciliación
Cada transferencia genera dos números de referencia que debe almacenar:| Campo | Qué es | Cuándo usarlo |
|---|---|---|
transferId | Identificador interno de Lerian | Consultas a la API, casos de soporte |
confirmationNumber | Referencia legible para el usuario | Comprobantes, comunicación con el cliente |
controlNumber | Referencia JD SPB (solo TED OUT) | Registro de auditoría BACEN, reportes regulatorios |
transferId como el confirmationNumber en sus propios registros para la reconciliación. Para TED OUT, también almacene el controlNumber.
Horario de funcionamiento
El BACEN establece que TED opera de lunes a viernes, de 06:30 a 17:00 (horario de Brasilia, UTC-3). Esta ventana es fija y no es configurable. Construya su UX en torno a ella — consulte Maneje el horario de funcionamiento con elegancia arriba.Las transferencias P2P no están sujetas a restricciones de horario de funcionamiento y funcionan 24/7.
Lista de verificación de integración
Antes de salir en producción, verifique lo siguiente:
- Claves de idempotencia en todas las operaciones de escritura — Envíe un header
X-IdempotencyUUID v4 en cada llamada ainitiate,processycancel. Esto evita transferencias duplicadas por reintentos o dobles clics. - Endpoint de webhook activo antes del lanzamiento — Su endpoint de webhook debe estar desplegado y accesible antes de salir en producción. Los eventos de transferencia comienzan a dispararse inmediatamente en la primera transacción real.
- Expiración de 24 horas manejada — Una transferencia iniciada expira si no se confirma dentro de las 24 horas. Si su flujo permite que un cliente inicie una transferencia y regrese más tarde, gestione el caso de expiración explícitamente.
- Backoff exponencial en errores 5xx — Implemente reintentos con backoff (por ejemplo, 2s, 4s, 8s) para códigos de error reintentables (
BTF-1000,BTF-2000). No reintente inmediatamente en un bucle. - Horario de funcionamiento validado en el lado del cliente — Verifique el horario en la interfaz antes de llamar a la API. Reduce llamadas innecesarias a la API fallidas y brinda una mejor experiencia al cliente.
- Ambos
transferIdyconfirmationNumberalmacenados — Requeridos para reconciliación y auditoría. Para TED OUT, también almacenecontrolNumber.
Manejo de errores
Use estos escenarios de error para mapear errores de la API a mensajes amigables para el cliente y definir la ruta de recuperación correcta.
| Escenario | Mensaje para el cliente | Código de error | Recuperable | Acción |
|---|---|---|---|---|
| Fuera del horario operativo | ”Las transferencias TED están disponibles de lunes a viernes, de 06:30 a 17:00. Próximo horario: [fecha/hora].” | BTF-0010 | Sí | Esperar la siguiente ventana |
| Saldo insuficiente | ”Su cuenta no tiene saldo suficiente para esta transferencia.” | BTF-0001 | Sí | El cliente agrega fondos o reduce el monto |
| Límite diario alcanzado | ”Ha alcanzado su límite diario de transferencias de R$ [X]. El límite se restablece a medianoche.” | BTF-0011 | Sí | Esperar el restablecimiento |
| Destinatario inválido | ”Cuenta de destino no encontrada. Verifique los datos de la cuenta e intente nuevamente.” | BTF-0500 | Sí | El cliente corrige los datos |
| Servicio no disponible | ”El servicio de transferencias no está disponible temporalmente. Intente nuevamente en unos minutos.” | BTF-1000 | Sí | Reintentar con backoff |
| Transferencia duplicada | ”Una transferencia idéntica fue enviada recientemente. Si fue intencional, espere un momento e intente de nuevo.” | BTF-0012 | Condicional | Esperar a que expire la ventana de deduplicación |