> ## 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. # Mejores prácticas > Aplica patrones probados al integrar Bank Transfer: muestra las comisiones antes de la confirmación, maneja las ventanas de liquidación y reduce los reclamos de los clientes. Esta guía cubre las decisiones clave que toma tu equipo cuando integras Bank Transfer. También da las mejores prácticas para una experiencia de cliente confiable y conforme a la normativa. ## 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 paso `initiate` 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: ``` Confirm transfer Recipient: Maria Silva — Bradesco (237) Amount: R$ 1,000.00 Fee: R$ 1.50 ───────────────────── Total: R$ 1,001.50 [ Cancel ] [ Confirm ] ``` Esto reduce los reclamos y las cancelaciones de clientes sorprendidos por comisiones después del hecho.

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: ``` TED transfers are available Monday to Friday, 06:30 to 17:00. Next available time: Monday at 06:30. ``` Para evitar viajes de ida y vuelta innecesarios, valida el horario de operación del lado del cliente antes de llamar a la API. No necesitas mantener tu propia lista de feriados. El plugin bloquea los fines de semana y los feriados de BACEN de forma automática. La fuente de verdad en tiempo de ejecución es la tabla `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: ``` Daily limit: R$ 50,000.00 Used today: R$ 45,000.00 Available: R$ 5,000.00 ``` ### 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) Cuando das esta información temprano, reduces los contactos de soporte del tipo "¿se hizo mi transferencia?". ### 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](/es/interfaces/ted-jd/ted-webhooks) 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 El plugin nunca borra ni hace expirar los registros de transferencia, así que su retención es tuya. Conserva los datos de transferencias y de auditoría durante al menos **5 años**, según los requisitos de conservación de registros de BACEN para instituciones financieras. | Tipo de dato | Período de retención | | -------------------------- | --------------------------------------- | | Registros de transacciones | 5 años (requisito de BACEN) | | Logs de la aplicación | 90 días | | Datos de auditoría | 5 años (anonimizados después de 2 años) | ### Registro de auditoría y conciliación Cada transferencia genera dos números de referencia que debes almacenar: | Campo | Qué es | Cuándo usarlo | | -------------------- | ----------------------------------- | ----------------------------------------------------- | | `transferId` | Identificador interno de Lerian | Consultas de API, casos de soporte | | `confirmationNumber` | Referencia legible por personas | Comprobantes, comunicación con el cliente | | `controlNumber` | Referencia de JD SPB (solo TED OUT) | Registro de auditoría de BACEN, informes regulatorios | 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](#handle-operating-hours-gracefully) 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-Idempotency` con un UUID v4 en cada llamada a `initiate`, `process` y `cancel`. 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 `503` o `500`. La indisponibilidad de JD SPB se expresa como `503` con un código propio del proveedor JD (`TRANSPORT`, `ACE95`, …). La indisponibilidad del ledger de Midaz se expresa como `BTF-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. * [ ] **`transferId` y `confirmationNumber` almacenados**: obligatorios para la conciliación y la auditoría. Para TED OUT, almacena también el `controlNumber`. ## 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. | Escenario | Mensaje de cara al cliente | Recuperación | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | **Fuera del horario de operación** (`BTF-0010`) | "Las transferencias TED están disponibles de lunes a viernes, 06:30–17:00. Próximo horario disponible: \[fecha/hora]." | Recuperable — espera la próxima ventana | | **Saldo insuficiente** (`BTF-2003`, HTTP `422`) | "Tu cuenta no tiene saldo suficiente para esta transferencia." | Recuperable — el cliente agrega fondos o reduce el monto | | **Límite diario alcanzado** (`BTF-0011`) | "Alcanzaste tu límite diario de transferencias de R\$ \[X]. El límite se restablece a medianoche." | Recuperable — espera el restablecimiento | | **Receptor inválido** (`BTF-0500`) | "No se encontró la cuenta de destino. Revisa los datos de la cuenta e inténtalo de nuevo." | Recuperable — el cliente corrige los datos | | **Servicio no disponible** (`TRANSPORT`, HTTP `503`, código propio de JD) | "El servicio de transferencias no está disponible temporalmente. Inténtalo de nuevo en unos minutos." | Recuperable — reintenta con backoff | | **Transferencia duplicada** (`BTF-0012`) | "Se envió una transferencia idéntica hace poco. Si fue intencional, espera un momento e inténtalo de nuevo." | Condicional — espera a que se libere la ventana de deduplicación | Para la lista completa de códigos de error y sus significados, consulta la [lista de errores de TED](/es/reference/interfaces/ted-jd/ted-error-list).