Decisiones de producto
Estas son elecciones que tu equipo de producto toma en la experiencia de cara al cliente. Afectan de forma directa la satisfacción del cliente y el volumen de soporte.
Muestra la comisión antes de que el cliente confirme
El pasoinitiate devuelve el monto de la comisión antes de que se mueva cualquier fondo. Usa esa ventana para mostrar una pantalla de confirmación clara:
Maneja el horario de operación con cuidado
TED OUT está disponible de lunes a viernes, 06:30–17:00 (hora de Brasilia). Cuando un cliente empieza una transferencia fuera de ese horario, no muestres solo un error. Dile cuándo puede intentarlo de nuevo:bacen_holidays, que el plugin carga para 2026–2028. El refrescador diario se ejecuta de forma predeterminada y vuelve a aplicar la carga incorporada. No consulta en vivo a ANBIMA, porque ANBIMA publica solo una hoja de cálculo heredada que las máquinas no pueden leer. La carga sigue siendo la fuente autorizada hasta que eso cambie.
Cuando un feriado rechaza una transferencia, muestra ese motivo al cliente. No repliques el calendario del lado del cliente. Confía en el plugin como fuente de verdad para evitar inconsistencias con el tiempo.
Comunica los límites de transferencia antes de que los clientes los alcancen
Muestra el límite diario restante del cliente en tu interfaz de transferencias. Muéstralo antes de que intente una transferencia que el plugin rechaza. Por ejemplo:Muestra comprobantes de confirmación después de completarse
Después de que una transferencia TED OUT o P2P se completa, muestra (u ofrece descargar) un comprobante con:- Fecha y hora de la transferencia
- Datos del emisor y del receptor
- Monto, comisión y total
confirmationNumber(referencia de cara al cliente)controlNumber(referencia de JD SPB, solo para TED OUT)
Mantén a los clientes informados en tiempo real
Usa webhooks para enviar las actualizaciones de estado de la transferencia a tu interfaz a medida que ocurren. No hagas que los clientes actualicen la página o se pregunten si su transferencia se hizo. Consulta webhooks de TED para la configuración.Decisiones de cumplimiento
Estos son requisitos que se aplican a tu integración sin importar tus elecciones de producto.
LGPD y datos personales
Los registros de transferencia contienen datos personales: nombres de clientes, CPF/CNPJ y datos bancarios. Confirma que tu política de privacidad cubra de forma explícita los datos de transacciones financieras. No registres el CPF/CNPJ en texto plano. Enmascáralo en las interfaces como***.***.***-00.
Un endpoint dedicado de anonimización para las solicitudes de derecho al olvido de la LGPD llegará en una versión futura. Hasta entonces, coordina las solicitudes de anonimización con tu equipo de administración de bases de datos.
Retención de datos
Registro de auditoría y conciliación
Cada transferencia genera dos números de referencia que debes almacenar:
Guarda el
transferId y el confirmationNumber en tus propios registros para la conciliación. Para TED OUT, almacena también el controlNumber.
Horario de operación
BACEN exige que TED opere de lunes a viernes, 06:30–17:00 (hora de Brasilia, UTC-3). El plugin aplica esa ventana de forma predeterminada. Un operador puede ajustar las horas de apertura y cierre en tiempo de ejecución a través del systemplane, dentro de los límites de BACEN. Toma 06:30–17:00 como la norma y construye tu experiencia de usuario alrededor de ella. Consulta Maneja el horario de operación con cuidado más arriba.Las transferencias P2P no están sujetas a restricciones de horario de operación y funcionan 24/7.
Lista de verificación de la integración
Antes de salir a producción, verifica lo siguiente:
- Claves de idempotencia en todas las operaciones de escritura: envía un encabezado
X-Idempotencycon un UUID v4 en cada llamada ainitiate,processycancel. Esto evita transferencias duplicadas por reintentos o dobles clics. - Endpoint de webhook activo antes del lanzamiento: despliega tu endpoint de webhook y hazlo alcanzable antes de salir a producción. Los eventos de transferencia empiezan a dispararse de inmediato en la primera transacción real.
- Expiración de 24 horas manejada: una transferencia iniciada expira si el cliente no la confirma en 24 horas. Si tu flujo permite que un cliente empiece una transferencia y vuelva más tarde, maneja el caso de expiración de forma explícita.
- Backoff exponencial en errores 5xx: implementa reintentos con backoff (por ejemplo, 2s, 4s, 8s) cuando la respuesta sea
503o500. La indisponibilidad de JD SPB se expresa como503con un código propio del proveedor JD (TRANSPORT,ACE95, …). La indisponibilidad del ledger de Midaz se expresa comoBTF-2000. No reintentes de inmediato en un bucle. - Horario de operación validado del lado del cliente: revisa el horario en la interfaz antes de llamar a la API. Esto reduce las llamadas fallidas a la API y da una mejor experiencia al cliente.
-
transferIdyconfirmationNumberalmacenados: obligatorios para la conciliación y la auditoría. Para TED OUT, almacena también elcontrolNumber.
Manejo de errores
Usa estos escenarios de error para asignar los errores de la API a mensajes claros para el cliente y definir la ruta de recuperación correcta.
Para la lista completa de códigos de error y sus significados, consulta la lista de errores de TED.