Configuración de Bank Transfer

Configura Bank Transfer a nivel de infraestructura, tenant y cuenta — límites, políticas de tarifas y horarios operativos ajustables en tiempo de ejecución.

La configuración del plugin Bank Transfer ocurre en tres niveles. La mayoría de las decisiones de negocio pueden cambiarse en tiempo de ejecución sin reiniciar el servicio.

La identidad del tenant y el alcance de la organización Midaz son separados. El tenant se resuelve a partir del contexto de la solicitud autenticada y controla el aislamiento de infraestructura, como la resolución de base de datos por el tenant-manager 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. En despliegues single-tenant, los clientes no deben enviar X-Organization-Id; el plugin rechaza los valores proporcionados por el llamador y usa SINGLE_TENANT_ORGANIZATION_ID del entorno en su lugar.

​

Niveles de configuración

---

Nivel	Quién lo gestiona	Qué controla	¿Requiere reinicio?
Infraestructura (variables de entorno)	DevOps	URLs, credenciales, autenticación, timeouts	Sí
Configuración de tenant (Admin API)	Equipo de producto	Límites, política de tarifas, anulaciones de horario	No
Configuración de cuenta (Admin API)	Equipo de producto	Límites y restricciones por cuenta	No

​

Decisiones de negocio que puede 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

Establezca 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 del tenant)

Los límites cubren tanto el monto total como el número de transacciones. Configúrelos para gestionar el riesgo y cumplir con los requisitos del BACEN.

​

Política de tarifas

Controle 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. Consulte 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, tiene 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

La política predeterminada del servicio de tarifas es fail-open (FEES_FAIL_CLOSED_DEFAULT=false). Cambie esto por organización a través de la Admin API cuando necesite 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. Habilite TED IN por organización una vez que sus 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. Puede 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

---

Esta sección es para equipos de DevOps. Estas variables se establecen en el momento del despliegue y requieren un reinicio del servicio para tener efecto.

​

Aplicación

Variable	Por defecto	Requerido	Descripción
ENV_NAME	development	No	Entorno (development, staging, production)
LOG_LEVEL	info	No	Verbosidad de logs (debug, info, warn, error)
DEPLOYMENT_MODE	byoc	No	Sabor de despliegue. byoc = Bring Your Own Cloud (single-tenant, gestionado por el operador). Activa comportamientos internos SaaS vs. BYOC.
SERVER_ADDRESS	:8080	No	Dirección y puerto del servidor HTTP
HTTP_BODY_LIMIT_BYTES	1048576	No	Tamaño máximo del cuerpo de la solicitud HTTP en bytes
INFRA_CONNECT_TIMEOUT_SEC	30	No	Tiempo de espera de conexión para servicios de infraestructura en segundos
ALLOW_PRIVATE_UPSTREAMS	false	No	⚠️ Permite que adaptadores de salida (CRM, Fees, JD, Midaz) resuelvan a IPs RFC1918/loopback. El valor por defecto false es fail-closed: producción bloquea el pivot DNS hacia el espacio privado. Habilítelo en dev o en BYOC in-cluster, donde los upstreams legítimamente viven en IPs privadas. Los endpoints de metadatos en cloud permanecen bloqueados independientemente de este flag.

​

TLS

Variable	Por defecto	Requerido	Descripción
SERVER_TLS_CERT_FILE	-	No	Ruta al archivo de certificado TLS. Debe definirse junto con SERVER_TLS_KEY_FILE.
SERVER_TLS_KEY_FILE	-	No	Ruta al archivo de clave privada TLS. Debe definirse junto con SERVER_TLS_CERT_FILE.
TLS_TERMINATED_UPSTREAM	false	No	Establezca en true cuando el TLS es terminado por un balanceador de carga o proxy inverso.

​

Headers de proxy

Se utilizan cuando el servicio se ejecuta detrás de un balanceador de carga o proxy inverso. Necesarios para extraer la IP real del cliente para rate limiting y logs de auditoría.

Variable	Por defecto	Requerido	Descripción
SERVER_PROXY_HEADER	-	No	Header HTTP que transporta la IP real del cliente (p. ej. X-Forwarded-For, X-Real-IP). Vacío deshabilita el parseo del header de proxy.
SERVER_TRUSTED_PROXIES	-	Si proxy header está definido	Lista separada por coma de IPs/CIDRs de proxies confiables. Requerido cuando SERVER_PROXY_HEADER está definido para evitar spoofing de IP.

​

CORS

Variable	Por defecto	Requerido	Descripción
CORS_ALLOWED_ORIGINS	http://localhost:3000	No	Lista de orígenes permitidos separados por coma. Wildcards (*) y orígenes localhost son rechazados en producción.
CORS_ALLOWED_METHODS	GET,POST,PUT,PATCH,DELETE,OPTIONS	No	Métodos HTTP permitidos.
CORS_ALLOWED_HEADERS	Origin,Content-Type,Accept,Authorization,X-Request-ID,X-Organization-Id,X-Idempotency	No	Headers de solicitud permitidos.

​

Autenticación

Este plugin delega la autorización a plugin-auth. Configure la conexión con las variables a continuación.

Variable	Por defecto	Requerido	Descripción
PLUGIN_AUTH_ENABLED	false	No	Habilita la autorización vía plugin-auth. Establezca en true en producción.
PLUGIN_AUTH_ADDRESS	-	Si habilitado	URL del servicio plugin-auth. Debe usar HTTPS en producción.
PLUGIN_AUTH_CLIENT_ID	plugin-br-bank-transfer	Si habilitado	OAuth client ID utilizado por este plugin.
PLUGIN_AUTH_CLIENT_SECRET	-	Si habilitado	OAuth client secret utilizado por este plugin.
AUTH_CACHE_TTL_SEC	60	No	Duración (en segundos) para almacenar en caché las decisiones de autorización. Las decisiones denegadas se almacenan en caché por TTL/4.

Cuando PLUGIN_AUTH_ENABLED=true, PLUGIN_AUTH_ADDRESS debe usar HTTPS en entornos de producción. Las direcciones HTTP son rechazadas al inicio.

​

Test admin (solo no-producción)

BTF_TEST_ADMIN_ENABLED debe permanecer en false en producción. Expone endpoints administrativos solo de prueba (p. ej. POST /admin/test/circuit-breakers/reset) que no tienen tenant y omiten la autenticación de producción. Solo se habilita en el mock-lane de docker-compose para pruebas E2E; cualquier despliegue con este flag en true fuera de una red de pruebas aislada constituye un error de configuración.

Variable	Por defecto	Requerido	Descripción
BTF_TEST_ADMIN_ENABLED	false	No	⚠️ Expone endpoints administrativos solo de prueba. Debe permanecer en false en producción.
BTF_TEST_ADMIN_TOKEN	-	Si admin habilitado	Token requerido cuando BTF_TEST_ADMIN_ENABLED=true. Se envía en el header X-Test-Admin-Token. Es intencionalmente independiente de la auth de producción (superficie solo de prueba, sin tenant).

​

Rate limiting

Variable	Por defecto	Requerido	Descripción
RATE_LIMIT_ENABLED	true	No	Habilita rate limiting por cliente. Forzado a true en producción.
RATE_LIMIT_MAX	100	No	Máximo de solicitudes por ventana por cliente.
RATE_LIMIT_EXPIRY_SEC	60	No	Duración de la ventana deslizante en segundos.

​

Idempotencia

Variable	Por defecto	Requerido	Descripción
IDEMPOTENCY_RETRY_WINDOW_SEC	300	No	Ventana de tiempo (en segundos) durante la cual una clave de idempotencia es válida.
IDEMPOTENCY_REQUIRE_REDIS	false	No	Cuando es true, rechaza solicitudes si Redis no está disponible en lugar de usar fallback.
DUPLICATE_GUARD_TTL_SEC	300	No	TTL (en segundos) para la ventana de duplicate-guard en Redis. Complementa IDEMPOTENCY_RETRY_WINDOW_SEC; este TTL controla el tiempo de vida de la entrada del duplicate-guard.

​

Multi-tenancy

Variable	Por defecto	Requerido	Descripción
MULTI_TENANT_ENABLED	false	No	Habilita multi-tenancy a nivel de infraestructura con bases de datos aisladas por tenant.
SINGLE_TENANT_ID	-	No	Anulación opcional de compatibilidad para el UUID interno efectivo del tenant en modo single-tenant. Cuando no se define, el plugin deriva un UUID de tenant estable a partir de la identidad de la aplicación y SINGLE_TENANT_ORGANIZATION_ID.
SINGLE_TENANT_SLUG	-	No	Identificador slug single-tenant opcional. DEFAULT_TENANT_SLUG solo se acepta como fallback heredado.
SINGLE_TENANT_ORGANIZATION_ID	-	Sí (single-tenant)	ID de organización Midaz usado cuando MULTI_TENANT_ENABLED=false. Requerido en modo single-tenant y usado como única fuente de organización; los valores X-Organization-Id proporcionados por el llamador son rechazados.
AWS_REGION	-	Si backend de secretos AWS	Región AWS para lecturas de secretos por tenant en Secrets Manager. Requerido cuando MULTI_TENANT_ENABLED=true y el backend de secretos es AWS.
MULTI_TENANT_INTEGRATION_SECRET_NAME_TEMPLATE	tenants/{env}/{tenantId}/{applicationName}/integration/configuration	No	Template del nombre del secreto en AWS Secrets Manager. Placeholders: {env}, {tenantId}, {applicationName}.
TENANT_IDS	-	No	Lista de UUIDs de tenant permitidos, separados por coma. Cuando está definida, las solicitudes de cualquier otro tenant son rechazadas. Déjelo sin definir para permitir todos los tenants configurados.
MULTI_TENANT_URL	-	Sí (cuando habilitado)	URL de la API HTTP del Tenant Manager.
MULTI_TENANT_REDIS_HOST	-	No	Host Redis para descubrimiento de tenants vía Pub/Sub.
MULTI_TENANT_REDIS_PORT	6379	No	Puerto de Redis para Pub/Sub.
MULTI_TENANT_REDIS_PASSWORD	-	No	Contraseña de Redis para Pub/Sub.
MULTI_TENANT_REDIS_TLS	false	No	Habilita TLS para la conexión Redis Pub/Sub.
MULTI_TENANT_TIMEOUT	30	No	Timeout HTTP en segundos para llamadas a la API del Tenant Manager.
MULTI_TENANT_MAX_TENANT_POOLS	100	No	Máximo de pools de conexión simultáneos por tenant.
MULTI_TENANT_IDLE_TIMEOUT_SEC	300	No	Timeout de inactividad en segundos antes de descartar un pool de tenant.
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD	5	No	Número de fallos antes de que el circuit breaker se abra.
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC	30	No	Timeout de recuperación en segundos del circuit breaker.
MULTI_TENANT_SERVICE_API_KEY	-	Sí (cuando habilitado)	Clave de API para el endpoint /settings del Tenant Manager.
MULTI_TENANT_CACHE_TTL_SEC	120	No	TTL en segundos del caché in-memory de configuración de tenant. Recargable vía systemplane API.
MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC	30	No	Intervalo en segundos para revalidación asíncrona de configuraciones de pool. Solo bootstrap (no recargable).

BYOC single-tenant:

SINGLE_TENANT_ORGANIZATION_ID=<su-midaz-organization-uuid>
# Opcional: anular el UUID interno de tenant derivado
SINGLE_TENANT_ID=<su-tenant-uuid>
# Opcional: restringir a UUIDs de tenant específicos
TENANT_IDS=<uuid1>,<uuid2>

SaaS multi-tenant:

MULTI_TENANT_ENABLED=true
MULTI_TENANT_URL=http://tenant-manager:4003
MULTI_TENANT_SERVICE_API_KEY=su-api-key
MULTI_TENANT_REDIS_HOST=redis.example.com

​

PostgreSQL

Variable	Por defecto	Requerido	Descripción
POSTGRES_HOST	localhost	Sí	Host primario de PostgreSQL.
POSTGRES_PORT	5432	No	Puerto primario de PostgreSQL.
POSTGRES_USER	plugin-br-bank-transfer	Sí	Usuario de base de datos.
POSTGRES_PASSWORD	-	Sí	Contraseña de base de datos. Requerido en producción.
POSTGRES_DB	plugin-br-bank-transfer	Sí	Nombre de la base de datos.
POSTGRES_SSLMODE	require	No	Modo SSL. disable es rechazado en producción.
POSTGRES_MAX_OPEN_CONNS	25	No	Máximo de conexiones abiertas.
POSTGRES_MAX_IDLE_CONNS	5	No	Máximo de conexiones inactivas.
POSTGRES_CONN_MAX_LIFETIME_MINS	30	No	Tiempo máximo de vida de la conexión en minutos.
POSTGRES_CONN_MAX_IDLE_TIME_MINS	5	No	Tiempo máximo inactivo de la conexión en minutos.
POSTGRES_CONNECT_TIMEOUT_SEC	10	No	Timeout de conexión en segundos.
MIGRATIONS_PATH	migrations	No	Ruta a los archivos de migración.

​

Réplica PostgreSQL

Configure una réplica de lectura para descarga de consultas. Todos los campos usan valores primarios como fallback cuando no están definidos.

Variable	Por defecto	Requerido	Descripción
POSTGRES_REPLICA_HOST	-	No	Host de la réplica. No definido = sin réplica.
POSTGRES_REPLICA_PORT	-	No	Puerto de la réplica.
POSTGRES_REPLICA_USER	-	No	Usuario de la réplica.
POSTGRES_REPLICA_PASSWORD	-	No	Contraseña de la réplica.
POSTGRES_REPLICA_DB	-	No	Nombre de la base de datos de la réplica.
POSTGRES_REPLICA_SSLMODE	-	No	Modo SSL de la réplica.

​

MongoDB

MongoDB es necesario para la persistencia de eventos de auditoría de transferencias. El servicio no se iniciará sin una conexión MongoDB válida.

Variable	Por defecto	Requerido	Descripción
MONGO_ENABLED	true	Sí	Habilita la conexión MongoDB. Debe ser true en todos los entornos.
MONGO_URI	-	Sí	Cadena de conexión MongoDB (ej: mongodb://user:pass@host:27017). Debe incluir credenciales y TLS en producción.
MONGO_DATABASE	-	Sí	Nombre de la base de datos MongoDB.
MONGO_MAX_POOL_SIZE	25	No	Tamaño máximo del pool de conexiones.
MONGO_SERVER_SELECTION_TIMEOUT_MS	3000	No	Timeout de selección de servidor en milisegundos.
MONGO_HEARTBEAT_INTERVAL_MS	10000	No	Intervalo de heartbeat en milisegundos.
MONGO_TLS_CA_CERT	-	No	Certificado CA codificado en base64 para TLS de MongoDB. Úselo cuando MongoDB requiere TLS con CA personalizado (p. ej. Atlas, instancias privadas con certs autofirmados).

​

Redis

Variable	Por defecto	Requerido	Descripción
REDIS_HOST	localhost:6379	Sí	Host y puerto de Redis.
REDIS_MASTER_NAME	-	No	Nombre del master Redis Sentinel (si usa Sentinel).
REDIS_PASSWORD	-	No	Contraseña de Redis (si la autenticación está habilitada).
REDIS_DB	0	No	Número de base de datos Redis.
REDIS_PROTOCOL	3	No	Versión del protocolo Redis (2 o 3).
REDIS_TLS	false	No	Habilita TLS para conexiones Redis.
REDIS_CA_CERT	-	No	Certificado CA para TLS Redis.
REDIS_POOL_SIZE	10	No	Tamaño del pool de conexiones.
REDIS_MIN_IDLE_CONNS	2	No	Mínimo de conexiones inactivas.
REDIS_READ_TIMEOUT_MS	3000	No	Timeout de lectura en milisegundos.
REDIS_WRITE_TIMEOUT_MS	3000	No	Timeout de escritura en milisegundos.
REDIS_DIAL_TIMEOUT_MS	5000	No	Timeout de conexión en milisegundos.

Redis es una dependencia obligatoria. Si Redis no está disponible al inicio o se vuelve inalcanzable en tiempo de ejecución, el servicio reportará como DOWN a la sonda de readiness de la orquestación y dejará de aceptar solicitudes. Redis es necesario para el caché de claves de idempotencia y la detección de duplicados.

​

Conexión JD SPB

Estas variables son requeridas para despliegues BYOC. En modo SaaS, Lerian gestiona la conexión JD.

Variable	Por defecto	Requerido	Descripción
JD_BASE_URL	-	Si BYOC	URL base de la API JD SPB.
JD_SOAP_PATH	/soap	No	Ruta del endpoint SOAP JD.
JD_ORIGIN_ISPB	-	Si BYOC	Código ISPB de origen.
JD_LEGACY_CODE	-	Si BYOC	Código legacy JD (máx. 10 caracteres).
JD_USER_CODE	-	Si BYOC	Código de usuario JD (máx. 10 caracteres).
JD_PASSWORD	-	Si BYOC	Contraseña JD (encriptada en reposo).
JD_PRIVATE_KEY_PEM	-	Si BYOC	Contenido PEM de clave privada RSA para firma XML.
JD_PUBLIC_KEY_PEM	-	No	PEM de clave pública para validar firmas en respuestas de JD. Requerido cuando JD_VALIDATE_EXTERNAL_SIGNATURE=true.
JD_PRIVATE_KEY_KEYINFO	-	No	Bloque XML <KeyInfo> embebido en la firma SOAP (p. ej. cert X509 codificado en base64). Requerido para el envoltorio WS-Security cuando JD demanda identificación por certificado.
JD_SIGNING_MODE	local_pem	No	Modo de firma SOAP. local_pem firma localmente con JD_PRIVATE_KEY_PEM; external_signer delega a un servicio remoto vía JD_EXTERNAL_SIGNER_URL.
JD_VALIDATE_EXTERNAL_SIGNATURE	true	No	Valida firmas en respuestas de JD (o del firmador externo). El valor por defecto true mantiene la validación activa. Establezca en false solo para debug/sandbox sin PKI configurado.
JD_EXTERNAL_SIGNER_URL	-	Si JD_SIGNING_MODE=external_signer	URL base del servicio de firma externo.
JD_EXTERNAL_SIGNER_AUTH_TOKEN	-	No	Bearer token enviado en el header Authorization para llamadas al firmador externo.
JD_EXTERNAL_SIGNER_TIMEOUT_MS	5000	No	Timeout (en milisegundos) para llamadas al firmador externo.
JD_BACEN_ROUTING_ISPB	00038166	No	ISPB de enrutamiento BACEN (el ISPB de JD/JDSPB). El valor por defecto 00038166 es el ISPB del banco JD. Cámbielo solo si el operador enruta a través de un PSP diferente.
JD_TIMEOUT_MS	8000	No	Timeout de solicitudes SOAP en milisegundos.
JD_MAX_RETRIES	3	No	Máximo de intentos de reintento para solicitudes JD.
JD_SANDBOX_MODE	false	No	Habilita modo sandbox JD. Rechazado en producción.

​

Polling JD

Variable	Por defecto	Requerido	Descripción
JD_POLLING_ENABLED	false	No	Habilita worker de polling TED IN.
JD_POLL_INTERVAL_SECONDS	30	No	Frecuencia (en segundos) de verificación de TEDs entrantes.
JD_POLL_MAX_MESSAGES_PER_CYCLE	50	No	Máximo de mensajes procesados por ciclo de polling.
JD_POLL_MAX_RETRIES	3	No	Máximo de intentos de reintento por ciclo de polling.
JD_POLL_RECOVERY_BATCH_SIZE	200	No	Tamaño del lote para polling de recuperación.
JD_POLL_DISABLE_OPERATING_HOURS_WINDOW	true	No	Cuando es true, el poller RecebeMensagem ignora la ventana de horario operativo (TRANSFER_OPERATING_OPEN/CLOSE) y se ejecuta de forma continua. El valor por defecto es true porque JD puede entregar mensajes fuera de la ventana de transferencia del operador.
BTF_TED_IN_RETORNO_FILTER	-	No	Filtro TpRetorno separado por coma aplicado en el lado del servidor por RecebeMensagem. Vacío = sin filtro (recibe P/R/E/C). Nota: la spec de JD codifica TpRetorno como un solo elemento, por lo que solo el primer valor es respetado actualmente.

JD_POLLING_ENABLED está deshabilitado por defecto para despliegues más seguros. En modo single-tenant, configure SINGLE_TENANT_ORGANIZATION_ID antes de habilitarlo. En modo multi-tenant, el gestor del poller de TED IN inicia un poller por cada tenant activo descubierto a través del tenant-manager y resuelve la configuración JD de cada tenant mediante el resolvedor de integración del tenant.

​

Servicios externos (Midaz)

Variable	Por defecto	Requerido	Descripción
MIDAZ_BASE_URL	-	Sí	URL base del servicio Midaz.
MIDAZ_TRANSACTION_URL	-	Sí	URL del servicio de transacciones Midaz.
MIDAZ_TIMEOUT_MS	3000	No	Timeout de solicitudes Midaz en milisegundos.
MIDAZ_MAX_RETRIES	3	No	Intentos de reintento al Midaz.
MIDAZ_OTEL_ENABLED	true	No	Habilita tracing OpenTelemetry para llamadas Midaz.
MIDAZ_DEBUG	false	No	Habilita logging de debug para llamadas Midaz. Rechazado en producción.
MIDAZ_AUTH_ENABLED	false	No	Habilita autenticación M2M para Midaz.
MIDAZ_AUTH_ADDRESS	-	Si auth	URL del servicio de autenticación para tokens M2M Midaz.
MIDAZ_CLIENT_ID	-	Si auth	OAuth client ID para M2M Midaz.
MIDAZ_CLIENT_SECRET	-	Si auth	OAuth client secret para M2M Midaz.
MIDAZ_BREAKER_FAILURES	3	No	Umbral de fallos del circuit breaker.
MIDAZ_BREAKER_TIMEOUT_SECONDS	30	No	Timeout de recuperación del circuit breaker en segundos.
BTF_MIDAZ_CB_ENABLED	true	No	Kill switch para el circuit breaker del cliente Midaz. Cuando es false, las llamadas a Midaz omiten el breaker (timeouts y reintentos siguen activos). Útil cuando inestabilidades intermitentes se amplifican en 500s sostenidos.

​

Servicios externos (CRM)

Variable	Por defecto	Requerido	Descripción
CRM_BASE_URL	-	Sí	URL del servicio CRM.
CRM_TIMEOUT_MS	2000	No	Timeout de solicitudes CRM en milisegundos.
CRM_MAX_RETRIES	2	No	Intentos de reintento al CRM.
CRM_AUTH_ENABLED	false	No	Habilita autenticación M2M para CRM.
CRM_CLIENT_ID	-	Si auth	OAuth client ID para M2M CRM.
CRM_CLIENT_SECRET	-	Si auth	OAuth client secret para M2M CRM.
CRM_SENDER_LOOKUP_PATH_TEMPLATE	-	No	Template de path para lookup del remitente en el CRM (p. ej. /api/v1/accounts/{accountId}). Los placeholders los define el CRM del operador.
CRM_RECIPIENT_LOOKUP_PATH_TEMPLATE	-	No	Template de path para lookup del destinatario en el CRM.
CRM_HOLDER_LOOKUP_PATH_TEMPLATE	-	No	Template de path para lookup del titular de la cuenta en el CRM.

​

Servicios externos (Fees)

BTF_FEE_ENABLED es el switch maestro. Cuando es false (por defecto), no se construye el adaptador de Fees y cada transferencia procede con tarifa=0 sin llamada HTTP. Las demás variables FEES_* solo tienen efecto cuando BTF_FEE_ENABLED=true.

Variable	Por defecto	Requerido	Descripción
BTF_FEE_ENABLED	false	No	Switch maestro para la integración con plugin-fees. Cuando es false, no se construye el adaptador de Fees y todas las transferencias se ejecutan con tarifa=0 sin llamadas HTTP. Los operadores que ejecutan plugin-fees deben establecer esto explícitamente en true.
FEES_BASE_URL	-	Si habilitado	URL del servicio Fees Engine.
FEES_TIMEOUT_MS	2000	No	Timeout de solicitudes de tarifas en milisegundos.
FEES_MAX_RETRIES	2	No	Intentos de reintento al servicio de tarifas.
FEES_FAIL_CLOSED_DEFAULT	false	No	Modo de fallo por defecto. true = bloquea transferencia cuando tarifas no está disponible.
FEES_MAX_FEE_AMOUNT_CENTS	99999999	No	Monto máximo de tarifa en centavos. Respuestas que exceden este valor son rechazadas.
FEES_REFUND_ON_DEVOLUCAO	false	No	Cuando es true, las tarifas cobradas se reembolsan en devoluciones/reversas de TED. El valor por defecto false mantiene la tarifa retenida incluso en devolución.
FEES_AUTH_ENABLED	false	No	Habilita autenticación M2M para Fees.
FEES_CLIENT_ID	-	Si auth	OAuth client ID para M2M Fees.
FEES_CLIENT_SECRET	-	Si auth	OAuth client secret para M2M Fees.

​

Resiliencia de Fees

BTF_FEES_TED_IN_FAIL_OPEN es true por defecto. Cuando plugin-fees no está disponible, los TEDs entrantes son acreditados con tarifa=0 (fail-open) para que los fondos lleguen al cliente. Operadores con un SLA que exige cobro en cada crédito entrante deben establecer esto en false (fail-closed). TED OUT es incondicionalmente fail-closed independientemente de este flag — el débito al remitente es autoritativo.

Variable	Por defecto	Requerido	Descripción
BTF_FEES_TED_IN_FAIL_OPEN	true	No	⚠️ Cuando es true, TED IN procede con tarifa=0 si plugin-fees es inalcanzable. Cuando es false, TED IN se bloquea hasta que tarifas se recupere. TED OUT es siempre fail-closed.

​

Reconciliación

El worker de reconciliación recoge transferencias pendientes que nunca recibieron retorno de JD y las concilia contra el ledger.

Variable	Por defecto	Requerido	Descripción
BTF_RECONCILIATION_ENABLED	true	No	Habilita el motor de reconciliación interno. Cuando es false, las transferencias sin retorno de JD nunca son conciliadas automáticamente.
BTF_RECONCILIATION_INTERVAL_SEC	30	No	Intervalo (en segundos) entre ciclos de reconciliación.
BTF_RECONCILIATION_BATCH_SIZE	20	No	Número máximo de transferencias procesadas por ciclo de reconciliación.
BTF_RECONCILIATION_MAX_ATTEMPTS	10	No	Máximo de intentos de reconciliación antes de marcar una transferencia como permanentemente fallida.
BTF_RECONCILIATION_STALE_AFTER_SEC	60	No	Tiempo (en segundos) tras el cual una transferencia pendiente se considera obsoleta y elegible para reconciliación.
BTF_DLQ_ENABLED	true	No	Persiste mensajes JD no parseables en la tabla dead-letter jd_incoming_parse_failures. El valor por defecto true se debe a que descartar mensajes silenciosamente nunca es seguro bajo entrega at-most-once.

​

Calendario de feriados (BACEN/ANBIMA)

Alimenta el calendario de feriados bancarios BACEN usado por la puerta de horarios operativos y el clamp del TTL de iniciación. La base de datos es la fuente de verdad; estas variables solo gobiernan el refresher programado.

Variable	Por defecto	Requerido	Descripción
ANBIMA_HOLIDAY_SOURCE_URL	https://www.anbima.com.br/feriados/arqs/feriados_nacionais.xls	No	URL upstream de feriados BACEN/ANBIMA. El refresher de feriados en vivo aún no está cableado (se usa un seed estático para 2026–2028); los operadores pueden repuntar a un mirror interno.
ANBIMA_FETCHER_ENABLED	true	No	Activa el refresher de feriados programado. Cuando es false, el plugin se apoya en una tabla bacen_holidays pre-poblada.
ANBIMA_FETCHER_SCHEDULE	03:00	No	Hora diaria de disparo (HH:MM) del refresher. 03:00 queda fuera del horario BACEN y antes de que abra la ventana de las 06:30, evitando snapshots en medio de un refresh.
HOLIDAY_CACHE_TTL	1h	No	TTL del caché in-process del calendario de feriados (formato time.ParseDuration: 1h, 30m, etc.). Reduzca este valor cuando UPSERTs manuales necesiten propagarse más rápido.

​

RabbitMQ

Los eventos de ciclo de vida de transferencia pueden publicarse en RabbitMQ para consumidores downstream.

Variable	Por defecto	Requerido	Descripción
RABBITMQ_ENABLED	false	No	Habilita publicación de eventos de ciclo de vida de transferencia.
RABBITMQ_URL	-	Si habilitado	URL de conexión AMQP. Debe usar amqps:// fuera de desarrollo.
RABBITMQ_EXCHANGE	bank_transfer.lifecycle	No	Nombre del exchange para eventos de ciclo de vida.
RABBITMQ_ROUTING_KEY_PREFIX	transfer	No	Prefijo de routing key para eventos publicados.
RABBITMQ_EVENT_SIGNING_SECRET	-	Si habilitado	Secreto HMAC para firmar eventos publicados. Mínimo 32 caracteres.
RABBITMQ_PUBLISH_TIMEOUT_MS	5000	No	Timeout de publicación en milisegundos.
RABBITMQ_MAX_RETRIES	3	No	Máximo de intentos de republicación.
RABBITMQ_RETRY_BACKOFF_MS	200	No	Backoff entre republicaciones en milisegundos.

​

Entrega de webhooks

La entrega de webhooks requiere que RabbitMQ esté habilitado. El worker de webhook consume eventos de una cola RabbitMQ y los entrega al endpoint configurado.

Variable	Por defecto	Requerido	Descripción
WEBHOOK_ENABLED	false	No	Habilita entrega de webhooks. Requiere RABBITMQ_ENABLED=true.
WEBHOOK_ENDPOINT_URL	-	Si habilitado	URL de destino. Debe usar HTTPS; IPs loopback/privadas son rechazadas.
WEBHOOK_SIGNING_SECRET	-	Si habilitado	Secreto HMAC para firmar payloads de webhook. Mínimo 32 caracteres.
WEBHOOK_BROKER_EVENT_SIGNING_SECRET	-	No	Secreto HMAC separado para verificar eventos del broker. Usa WEBHOOK_SIGNING_SECRET como fallback.
WEBHOOK_ALLOW_UNSIGNED_BROKER_EVENTS	false	No	Acepta temporalmente eventos no firmados del broker durante migración.
WEBHOOK_UNSIGNED_BROKER_EVENTS_GRACE_SEC	0	No	Período de gracia (en segundos) para eventos no firmados. Debe ser > 0 cuando eventos no firmados están permitidos.
WEBHOOK_QUEUE_NAME	transfer.webhook.delivery	No	Nombre de la cola RabbitMQ para eventos de webhook.
WEBHOOK_DLQ_NAME	transfer.webhook.dlq	No	Cola de dead-letter para entregas de webhook fallidas.
WEBHOOK_CONSUMER_TAG	plugin-br-bank-transfer-webhook	No	Tag de consumidor RabbitMQ.
WEBHOOK_PREFETCH_COUNT	20	No	Conteo de prefetch RabbitMQ.
WEBHOOK_DELIVERY_CONCURRENCY	8	No	Máximo de entregas de webhook concurrentes por worker.
WEBHOOK_TIMEOUT_MS	5000	No	Timeout de entrega HTTP en milisegundos.
WEBHOOK_MAX_RETRIES	3	No	Máximo de intentos de reentrega.
WEBHOOK_RETRY_BACKOFF_MS	5000	No	Backoff entre reentregas en milisegundos. Los valores positivos por debajo de 5000 ms se ajustan al piso de 5s.

​

Límites de uso

Variable	Por defecto	Requerido	Descripción
USAGE_LIMITS_ENABLED	false	No	Habilita imposición de límites de uso por cuenta.
USAGE_LIMIT_DAILY_CENTS	0	No	Límite diario predeterminado de transferencia en centavos. Al menos un límite debe ser > 0 cuando está habilitado.
USAGE_LIMIT_MONTHLY_CENTS	0	No	Límite mensual predeterminado de transferencia en centavos.

​

Horarios operativos

Variable	Por defecto	Requerido	Descripción
TRANSFER_OPERATING_OPEN	06:30	No	Hora de apertura de la ventana de aceptación de transferencias (HH:MM).
TRANSFER_OPERATING_CLOSE	17:00	No	Hora de cierre de la ventana de aceptación de transferencias (HH:MM).
TRANSFER_OPERATING_TIMEZONE	America/Sao_Paulo	No	Zona horaria para evaluación de horarios operativos.

​

Telemetría (OpenTelemetry)

Variable	Por defecto	Requerido	Descripción
ENABLE_TELEMETRY	false	No	Habilita tracing y métricas OpenTelemetry.
OTEL_RESOURCE_SERVICE_NAME	plugin-br-bank-transfer	No	Nombre del servicio OTel.
OTEL_LIBRARY_NAME	github.com/LerianStudio/plugin-br-bank-transfer	No	Nombre de la biblioteca de instrumentación OTel.
OTEL_RESOURCE_SERVICE_VERSION	1.0.0	No	Versión del servicio OTel.
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT	development	No	Entorno de despliegue OTel.
OTEL_EXPORTER_OTLP_ENDPOINT	localhost:4317	No	Endpoint gRPC del colector OTel.
DB_METRICS_INTERVAL_SEC	15	No	Intervalo de recolección de métricas de base de datos en segundos.
RECONCILIATION_PENDING_ALERT_THRESHOLD	5	No	Umbral de alerta para ítems de reconciliación pendientes.
OTEL_TRACES_SAMPLER_ARG	-	No	Ratio de muestreo de traces (0.0–1.0). Sin definir usa el sampler por defecto resuelto en la inicialización de telemetría: 0.1 en producción, 1.0 en otros entornos. Valores fuera de (0,1] se clampean a 1.0 para que un error de configuración no deshabilite silenciosamente el tracing en producción.
BTF_METRICS_PROMETHEUS_ENABLED	false	No	Expone un endpoint dedicado de scrape de Prometheus para las métricas btf.*. Cuando es true, se inicia el listener en BTF_METRICS_PROMETHEUS_ADDRESS.
BTF_METRICS_PROMETHEUS_ADDRESS	127.0.0.1:9090	No	Dirección de escucha del endpoint Prometheus /metrics. El valor por defecto se enlaza a loopback para que un pod mal configurado no exponga métricas no autenticadas a la red del cluster. Sobrescriba (p. ej. 0.0.0.0:9090) solo detrás de una NetworkPolicy o sidecar.

​

Licencia

Variable	Por defecto	Requerido	Descripción
LICENSE_KEY	-	En producción	Clave de licencia. Requerido en entornos de producción.
LICENSE_SERVICE_ADDRESS	-	No	URL del servicio de validación de licencia.
TENANT_IDS	-	No	Lista de UUIDs de tenant licenciados separados por coma.

​

Encriptación

Encriptación a nivel de campo para datos sensibles en reposo. Cada clave debe ser una clave AES-256 de 32 bytes codificada en base64. Deje en blanco para deshabilitar la encriptación del campo.

Variable	Por defecto	Requerido	Descripción
JD_INCOMING_RAW_XML_ENCRYPTION_KEY	-	No	Clave AES-256 para encriptar payloads XML JD entrantes.
RECIPIENT_DETAILS_ENCRYPTION_KEY	-	No	Clave AES-256 para encriptar detalles del destinatario en reposo.

​

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)

Consulte la referencia de Admin API para la lista completa de campos configurables y el formato de solicitud.