Lo que el plugin gestiona por ti
- Envía TEDs salientes a cualquier banco brasileño (TED OUT)
- Recibe y acredita TEDs entrantes automáticamente (TED IN)
- Procesa transferencias internas instantáneas entre cuentas (P2P)
- Calcula y aplica tarifas automáticamente antes de que el cliente confirme
- Detecta y previene transferencias duplicadas dentro de una ventana configurable
- Valida días hábiles BACEN contra el calendario
bacen_holidays(seed estático para 2026–2028; el refresher en vivo de ANBIMA está pendiente) - Firma mensajes con el certificado digital de tu institución, según lo exige el BACEN
- Reintenta operaciones fallidas automáticamente
- Notifica a tu sistema a través de webhooks en tiempo real ante cada cambio de estado
Cómo funciona TED OUT
TED OUT utiliza un flujo de dos pasos para que el cliente pueda revisar la tarifa antes de confirmar.
Paso 1 — Iniciar
Tu sistema llama al plugin con los detalles de la transferencia (monto, destinatario, cuenta del remitente).
El plugin valida la cuenta del remitente, verifica el horario de funcionamiento y ejecuta la detección de duplicados.
Paso 2 — Procesar
Cómo funciona TED IN
- Un banco externo envía un TED a tu institución a través de JD Consultores.
- El plugin consulta a JD cada 60 segundos (valor por defecto) para detectar nuevas transferencias entrantes.
- El plugin valida al destinatario contra el CRM para encontrar la cuenta correcta.
- El plugin acredita la cuenta en Midaz y crea un registro de transferencia completado.
- Tu sistema recibe un webhook confirmando el crédito.
La recepción de TED IN está deshabilitada por defecto. Habilítala por organización a través de la Admin API una vez que tus credenciales JD y el worker de polling estén configurados.
Cómo funciona P2P
Las transferencias P2P mueven fondos entre dos cuentas dentro de la misma organización, sin pasar por la red SPB. La liquidación es instantánea.
- Tu sistema llama al plugin con la cuenta del remitente, la cuenta del destinatario y el monto.
- El plugin calcula la tarifa (si está configurada) y la presenta para confirmación.
- Tras la confirmación, el plugin ejecuta la transferencia en Midaz.
- Ambas cuentas se actualizan inmediatamente. Tu sistema recibe un webhook.
Modelos de despliegue
El plugin TED admite dos modelos de despliegue, definidos a través de la variable de entorno
DEPLOYMENT_MODE.
SaaS (gestionado por Lerian)
En los despliegues SaaS, Lerian gestiona la integración con JD Consultores, incluyendo la gestión de credenciales y el mantenimiento de certificados. Tu equipo solo necesita configurar los ajustes a nivel de negocio, como límites de transacción, tarifas y webhooks, a través de la Admin API. No se requiere gestión de infraestructura ni de conexiones. Al ejecutarse en modosaas, el plugin opera como un servicio multi-tenant. La identidad del tenant, las credenciales JD, los secretos de webhook y ciertos ajustes de configuración se resuelven dinámicamente a través del servicio de la plataforma de multi-tenancy. En este modo, las variables MULTI_TENANT_* y AWS_REGION son obligatorias y utilizadas activamente por el plugin.
BYOC (trae tus propias credenciales)
En los despliegues BYOC, tu institución es responsable de proporcionar las credenciales de JD Consultores y la clave privada RSA utilizada para firmar los mensajes. Estos valores son configurados por tu equipo de DevOps a través de variables de entorno, lo que te otorga control total sobre la conexión JD y permite que el plugin se ejecute completamente dentro de tu propia infraestructura. Este es el modo de despliegue predeterminado (byoc). Toda la configuración —incluyendo credenciales JD, secretos de webhook y ajustes relacionados con tarifas— se carga desde variables de entorno durante el arranque de la aplicación.
Resolución de organización
En los despliegues single-tenant, la organización de Midaz se identifica a través del header requeridoX-Organization-Id en las rutas de API con alcance de organización.
Para los procesos en segundo plano que no reciben headers de solicitud, como el poller de TED IN y los workers de reconciliación, el plugin recurre a la variable de entorno ORGANIZATION_ID.
Las variables relacionadas con multi-tenancy (
MULTI_TENANT_*) y AWS_REGION se ignoran cuando el plugin se ejecuta en modo byoc.Integración con Midaz
Todos los movimientos financieros pasan a través del ledger de Midaz. El plugin crea transacciones en Midaz para cada transferencia:
- TED OUT — los fondos se retienen cuando la transferencia es confirmada (paso de proceso, vía
pending: true), luego se debitan al recibir la confirmación de liquidación. - TED IN — los fondos se acreditan después de que la transferencia sea validada y confirmada por JD.
- P2P — una única transacción de Midaz debita al remitente y acredita al destinatario de forma atómica.
Para desarrolladores
Arquitectura
El plugin utiliza arquitectura Hexagonal (Puertos y Adaptadores) combinada con CQRS. La lógica de negocio está aislada de la infraestructura, lo que facilita agregar nuevos adaptadores (por ejemplo, un proveedor SPB diferente) sin cambiar el comportamiento del núcleo.
Detección de duplicados
El plugin genera una huella (fingerprint) de detección de duplicados a partir desenderAccountId, los datos del destinatario (ISPB, agencia, cuenta, documento del titular), el monto y el propósito, y la almacena en Redis con un TTL configurable (por defecto: 300 segundos vía DUPLICATE_GUARD_TTL_SEC). La organización no forma parte de la huella; el aislamiento de tenant proviene del prefijo de clave de Redis. Las solicitudes duplicadas dentro de la ventana son rechazadas con 409 Conflict y el código de error BTF-0012.
Aislamiento de datos multi-tenant
El aislamiento de tenant proviene de la resolución de base de datos de la plataforma de multi-tenancy. EltenantId se extrae del claim JWT o del contexto autenticado y nunca se proporciona a través de X-Organization-Id. La caché de Redis usa prefijos de clave por tenant (tenant:{tenantId}:{key}), y las tablas de negocio usan los campos de organización Midaz solo para la autorización de alcance de negocio dentro del tenant resuelto.