tenantId) y controla el aislamiento de infraestructura, como la resolución de base de datos de la plataforma de multi-tenancy y los secretos con alcance de tenant. X-Organization-Id es el alcance de la organización Midaz utilizado por las rutas de transferencia con alcance de organización dentro de ese tenant; es requerido en esas rutas en todos los modos de despliegue, y un valor ausente o que no sea un UUID devuelve 400. Los workers en segundo plano (el poller de TED IN y la reconciliación) no tienen header de solicitud y, en modo single-tenant, recurren a la variable de entorno ORGANIZATION_ID.
Niveles de configuración
La configuración del plugin Bank Transfer se divide en tres niveles:
- Configuración de infraestructura (gestionada por DevOps) controla URLs, credenciales, configuraciones de autenticación y timeouts. Los cambios requieren un reinicio del servicio.
- Configuración de tenant (gestionada a través de la Admin API por el equipo de producto) controla límites de transferencia, políticas de tarifas y anulaciones de horario operativo. Los cambios tienen efecto sin reiniciar el servicio.
- Configuración de cuenta (gestionada a través de la Admin API por el equipo de producto) controla límites y restricciones para cuentas individuales. Los cambios tienen efecto sin reiniciar el servicio.
Decisiones de negocio que puedes configurar
Estas son las configuraciones que interesan a los GPMs y equipos de producto. Todas se gestionan a través de la Admin API en tiempo de ejecución — sin necesidad de despliegue.
Límites de transferencia
Establece límites de volumen diario y mensual en dos niveles:- Por organización — aplica a las transferencias de una organización Midaz dentro del tenant resuelto
- Por cuenta — aplica a una cuenta de usuario final específica (anula los valores predeterminados de la organización)
Política de tarifas
Controla si el plugin cobra una tarifa en las transferencias TED OUT, TED IN y P2P. Las reglas de tarifas se definen en el Fees Engine y se aplican por organización. Consulta Fees Engine para detalles de configuración.Fail-open vs. fail-closed
Si el servicio de cálculo de tarifas no está disponible al momento de una transferencia, tienes dos opciones:- Fail-open — permite que la transferencia proceda sin cobrar una tarifa
- Fail-closed — bloquea la transferencia hasta que el servicio de tarifas esté disponible nuevamente
FEES_FAIL_CLOSED_DEFAULT=false). Cambia esto por organización a través de la Admin API cuando necesites que las interrupciones del servicio de tarifas bloqueen las transferencias. TED IN tiene su propio interruptor de seguridad, BTF_FEES_TED_IN_FAIL_OPEN, que por defecto es true para que los fondos entrantes se acrediten con tarifa=0 si plugin-fees no está disponible.
Recepción de TED IN
Las transferencias entrantes están deshabilitadas por defecto. Habilita TED IN por organización una vez que tus credenciales JD SPB estén configuradas y el worker de polling esté activo.Anulaciones de horario operativo
El plugin aplica la ventana operativa TED del BACEN por defecto. Puedes configurar ventanas personalizadas por política de tenant — por ejemplo, restringir las transferencias solo al horario comercial — dentro de los límites del BACEN.Configuración de infraestructura
Las variables de entorno definidas en el despliegue (URLs, credenciales, TLS, persistencia, integraciones, claves de seguridad) las establece DevOps y requieren un reinicio del servicio. Consulta la referencia completa en Variables de entorno.
Configuración en tiempo de ejecución (Admin API)
La configuración a nivel de tenant y de cuenta se gestiona a través de la Admin API — sin necesidad de reinicio. Los cambios tienen efecto inmediato (sujeto al TTL de caché para la configuración del tenant). Las configuraciones disponibles incluyen:
- Límites de transferencia (diario y mensual, por organización y por cuenta)
- Comportamiento de tarifas (fail-open o fail-closed cuando el servicio de tarifas no está disponible)
- Recepción de TED IN (habilitada o deshabilitada por organización)
- Anulaciones de horario operativo (ventanas personalizadas dentro de los límites del BACEN)
Configuraciones gestionadas por systemplane
Las configuraciones a continuación se gestionan en tiempo de ejecución a través del systemplane (Admin API), no en el momento del despliegue. Cada una tiene un nombre de variable de entorno correspondiente que aún existe en el código, pero el cargador de configuración ignora estas variables de entorno y emite un WARN de deprecación si están definidas — asignarlas vía el entorno no tiene efecto. Usa el systemplane para cambiarlas.| Área | Configuraciones |
|---|---|
| Rate limiting | RATE_LIMIT_ENABLED, RATE_LIMIT_MAX, RATE_LIMIT_EXPIRY_SEC |
| CORS | CORS_ALLOWED_ORIGINS, CORS_ALLOWED_METHODS, CORS_ALLOWED_HEADERS (el origen por defecto es el wildcard * cuando no está configurado; no se valida al inicio) |
| Política de tarifas | FEES_FAIL_CLOSED_DEFAULT, FEES_MAX_FEE_AMOUNT_CENTS, FEES_REFUND_ON_DEVOLUCAO, BTF_FEES_TED_IN_FAIL_OPEN |
| Límites de uso | USAGE_LIMITS_ENABLED, USAGE_LIMIT_DAILY_CENTS, USAGE_LIMIT_MONTHLY_CENTS |
| Horarios operativos | TRANSFER_OPERATING_OPEN, TRANSFER_OPERATING_CLOSE, TRANSFER_OPERATING_TIMEZONE |
| Idempotencia / duplicate guard | IDEMPOTENCY_REQUIRE_REDIS, DUPLICATE_GUARD_TTL_SEC |
| Enrutamiento | ROUTING_* (todas las configuraciones de reglas de enrutamiento) |
| Tuning de timeout y reintentos JD | JD_TIMEOUT_MS, JD_MAX_RETRIES, JD_VALIDATE_EXTERNAL_SIGNATURE |
| Tuning de polling JD | JD_POLL_MAX_MESSAGES_PER_CYCLE, JD_POLL_RECOVERY_BATCH_SIZE, JD_POLL_DISABLE_OPERATING_HOURS_WINDOW |
| Tuning de reconciliación | BTF_RECONCILIATION_BATCH_SIZE, BTF_RECONCILIATION_MAX_ATTEMPTS, BTF_RECONCILIATION_STALE_AFTER_SEC, BTF_RECONCILIATION_TICK_DEADLINE_SECONDS, RECONCILIATION_PENDING_ALERT_THRESHOLD |
| Tuning de publicación RabbitMQ | RABBITMQ_MAX_RETRIES, RABBITMQ_PUBLISH_TIMEOUT_MS, RABBITMQ_RETRY_BACKOFF_MS, RABBITMQ_ROUTING_KEY_PREFIX |
| Tuning de entrega de webhooks | WEBHOOK_TIMEOUT_MS, WEBHOOK_MAX_RETRIES, WEBHOOK_RETRY_BACKOFF_MS, WEBHOOK_ALLOW_UNSIGNED_BROKER_EVENTS, WEBHOOK_UNSIGNED_BROKER_EVENTS_GRACE_SEC |
Definir cualquiera de los nombres anteriores vía el entorno no tiene efecto y se registra como WARN de deprecación. Existen únicamente como gemelos de entorno deprecados de configuraciones gestionadas en runtime/systemplane.