> ## 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 toma al integrar Bank Transfer. También ofrece las buenas prácticas para una experiencia de cliente confiable y conforme.
## 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 paso `initiate` devuelve el monto de la tarifa antes de que se muevan los fondos. Usa esta 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 inicia una transferencia 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 necesitas mantener tu propia lista de feriados. El plugin bloquea automáticamente fines de semana y feriados BACEN. La fuente de verdad en runtime es la tabla `bacen_holidays`, que el plugin puebla con seed para 2026–2028. 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 que las máquinas no pueden leer. El seed sigue siendo la fuente autoritativa hasta que eso cambie.
Cuando un feriado rechaza una transferencia, comunica ese motivo al cliente. No repliques 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. Muéstralo antes de que intente una transferencia que el plugin rechaza. 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` (referencia visible para el cliente)
* `controlNumber` (referencia JD SPB, solo para TED OUT)
Cuando proporcionas esta información de forma anticipada, reduces 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. No registres CPF/CNPJ en texto claro. Enmascáralo en interfaces como `***.***.***-00`.
Un endpoint dedicado de anonimización para 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 base de datos.
### Retención de datos
El plugin nunca elimina ni caduca los registros de transferencia, así que tú controlas su retención. Conserva los datos de transferencia y auditoría durante al menos **5 años**, conforme a los requisitos de conservación de registros del BACEN para instituciones financieras.
| 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. Un operador puede ajustar los horarios de apertura y cierre en runtime a través de systemplane, dentro de los límites de BACEN. Trata 06:30–17:00 como la norma y 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** — Despliega tu endpoint de webhook y hazlo 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 el cliente no la 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. Esto reduce llamadas fallidas a la API 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).