> ## 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.
# Buenas prácticas
> Aplica patrones probados al integrar Bank Transfer — muestra tarifas antes de confirmar, maneja ventanas de liquidación y reduce reclamos de clientes.
Esta guía cubre las decisiones clave que tu equipo debe tomar al integrar Bank Transfer, y las buenas prácticas para garantizar una experiencia confiable y conforme para tus clientes.
## Decisiones de producto
***
Estas son las decisiones que tu equipo de producto toma en la experiencia orientada al cliente. Afectan directamente la satisfacción del cliente y el volumen de soporte.
### Muestra la tarifa antes de que el cliente confirme
El flujo de dos pasos (`initiate` → `process`) está diseñado para esto: tu sistema recibe el monto de la tarifa antes de que se muevan los fondos. Usa esa ventana para mostrar una pantalla de confirmación clara:
```
Confirmar transferencia
Destinatario: Maria Silva — Bradesco (237)
Monto: R$ 1.000,00
Tarifa: R$ 1,50
─────────────────────
Total: R$ 1.001,50
[ Cancelar ] [ Confirmar ]
```
Esto reduce las reclamaciones y cancelaciones de clientes sorprendidos por las tarifas después del hecho.
### Maneja 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 muestres solo un error — dile cuándo podrá intentarlo de nuevo:
```
Las transferencias TED están disponibles de lunes a viernes, de 06:30 a 17:00.
Próximo horario disponible: lunes a las 06:30.
```
Para evitar viajes de ida y vuelta innecesarios, valida el horario de funcionamiento en el lado del cliente antes de llamar a la API.
No es necesario mantener tu propia lista de feriados — el plugin ya bloquea automáticamente fines de semana y feriados BACEN. La fuente de verdad en runtime es la tabla `bacen_holidays`, con seed para 2026–2099. El job de actualización diaria se ejecuta por defecto y reaplica el seed integrado; no consulta en vivo a ANBIMA, porque ANBIMA solo publica una hoja de cálculo legacy no legible por máquina — el seed es la fuente autoritativa hasta que eso cambie.
Si una transferencia es rechazada por feriado, comunica ese motivo al cliente. En lugar de replicar el calendario en el 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 transferencia — antes de que intente una transferencia que será rechazada. Por ejemplo:
```
Límite diario: R$ 50.000,00
Utilizado hoy: R$ 45.000,00
Disponible: R$ 5.000,00
```
### Muestra comprobantes de confirmación después de la finalización
Después de que se complete una transferencia TED OUT o P2P, muestra — u ofrece descargar — un comprobante con:
* Fecha y hora de la transferencia
* Datos del remitente y destinatario
* Monto, tarifa y total
* `confirmationNumber` (tu referencia interna)
* `controlNumber` (referencia JD SPB, solo para TED OUT)
Proporcionar esta información de forma proactiva reduce los contactos de soporte del tipo "¿se realizó mi transferencia?".
### Mantén a los clientes informados en tiempo real
Usa webhooks para enviar actualizaciones del estado de la transferencia a tu interfaz a medida que ocurren. No hagas que los clientes actualicen la página ni se pregunten si su transferencia fue procesada. Consulta [Webhooks de Bank Transfer](/es/rails/ted/jd/ted-webhooks) para la configuración.
## Decisiones de cumplimiento
***
Estos son los requisitos que aplican a tu integración independientemente de tus decisiones de producto.
### LGPD y datos personales
Los registros de transferencia contienen datos personales — nombres de clientes, CPF/CNPJ y datos bancarios. Asegúrate de que tu política de privacidad cubra explícitamente los datos de transacciones financieras. Evita registrar CPF/CNPJ en texto claro; enmascara 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, coordina las solicitudes de anonimización con tu equipo de administración de base de datos.
### Retención de datos
Los datos de transferencia deben conservarse durante **5 años** conforme a la Resolución 4.753/2019 del BACEN. Esto no es configurable y no puede acortarse.
| 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 debes 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 |
Conserva tanto el `transferId` como el `confirmationNumber` en tus propios registros para la reconciliación. Para TED OUT, también almacena 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). El plugin aplica esta ventana por defecto; los horarios de apertura/cierre son ajustables por el operador en runtime (dentro de los límites de BACEN) vía systemplane, pero trata 06:30–17:00 como la norma. Construye tu UX en torno a ella — consulta [Maneja el horario de funcionamiento con elegancia](#maneja-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, verifica lo siguiente:
* [ ] **Claves de idempotencia en todas las operaciones de escritura** — Envía un header `X-Idempotency` 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** — Tu 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 tu flujo permite que un cliente inicie una transferencia y regrese más tarde, gestiona el caso de expiración explícitamente.
* [ ] **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 aparece como `503` con un código de proveedor JD sin transformar (`TRANSPORT`, `ACE95`, …); la indisponibilidad del ledger Midaz aparece como `BTF-2000`. No reintentes inmediatamente en un bucle.
* [ ] **Horario de funcionamiento validado en el lado del cliente** — Verifica 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 `transferId` y `confirmationNumber` almacenados** — Requeridos para reconciliación y auditoría. Para TED OUT, también almacena `controlNumber`.
## Manejo de errores
***
Usa 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 | Recuperación |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Fuera del horario operativo** (`BTF-0010`) | "Las transferencias TED están disponibles de lunes a viernes, de 06:30 a 17:00. Próximo horario: \[fecha/hora]." | Recuperable — espera la siguiente ventana |
| **Saldo insuficiente** (`BTF-2003`, HTTP `422`) | "Su cuenta no tiene saldo suficiente para esta transferencia." | Recuperable — el cliente agrega fondos o reduce el monto |
| **Límite diario alcanzado** (`BTF-0011`) | "Ha alcanzado su límite diario de transferencias de R\$ \[X]. El límite se restablece a medianoche." | Recuperable — espera el restablecimiento |
| **Destinatario inválido** (`BTF-0500`) | "Cuenta de destino no encontrada. Verifique los datos de la cuenta e intente nuevamente." | Recuperable — el cliente corrige los datos |
| **Servicio no disponible** (`TRANSPORT`, HTTP `503`, código JD sin transformar) | "El servicio de transferencias no está disponible temporalmente. Intente nuevamente en unos minutos." | Recuperable — reintenta con backoff |
| **Transferencia duplicada** (`BTF-0012`) | "Una transferencia idéntica fue enviada recientemente. Si fue intencional, espere un momento e intente de nuevo." | Condicional — espera a que expire la ventana de deduplicación |
Para la lista completa de códigos de error y sus significados, consulta la [lista de errores de Bank Transfer](/es/reference/midaz/plugins/ted/ted-error-list).