Configuración de Bank Transfer

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.

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 tenant — aplica a todas las transferencias de la organización
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

El valor predeterminado es fail-closed. Cambie esto por organización a través de la Admin API.

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 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.
`DEFAULT_TENANT_ID`	`11111111-1111-1111-1111-111111111111`	No	UUID de tenant de fallback cuando auth está deshabilitado. Debe ser un UUID válido.
`DEFAULT_TENANT_SLUG`	`default`	No	Identificador slug del tenant por defecto.
`DEFAULT_ORGANIZATION_ID`	-	No	ID de organización usado en modo single-tenant (cuando `MULTI_TENANT_ENABLED=false`). Complementa `DEFAULT_TENANT_ID`.
`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:

DEFAULT_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. Antes de habilitarlo, asegúrese de que DEFAULT_TENANT_ID (o Pool Manager) esté configurado con un UUID válido. El polling JD no es compatible cuando MULTI_TENANT_ENABLED=true.

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 fetcher 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`	`500`	No	Backoff entre reentregas en milisegundos.

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 tenant 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.

Documentation Index

​Niveles de configuración

​Decisiones de negocio que puede configurar

​Límites de transferencia

​Política de tarifas

​Fail-open vs. fail-closed

​Recepción de TED IN

​Anulaciones de horario operativo

​Configuración de infraestructura

​Aplicación

​TLS

​Headers de proxy

​CORS

​Autenticación

​Test admin (solo no-producción)

​Rate limiting

​Idempotencia

​Multi-tenancy

​PostgreSQL

​Réplica PostgreSQL

​MongoDB

​Redis

​Conexión JD SPB

​Polling JD

​Servicios externos (Midaz)

​Servicios externos (CRM)

​Servicios externos (Fees)

​Resiliencia de Fees

​Reconciliación

​Calendario de feriados (BACEN/ANBIMA)

​RabbitMQ

​Entrega de webhooks

​Límites de uso

​Horarios operativos

​Telemetría (OpenTelemetry)

​Licencia

​Encriptación

​Configuración en tiempo de ejecución (Admin API)

Niveles de configuración

Decisiones de negocio que puede configurar

Límites de transferencia

Política de tarifas

Fail-open vs. fail-closed

Recepción de TED IN

Anulaciones de horario operativo

Configuración de infraestructura

Aplicación

TLS

Headers de proxy

CORS

Autenticación

Test admin (solo no-producción)

Rate limiting

Idempotencia

Multi-tenancy

PostgreSQL

Réplica PostgreSQL

MongoDB

Redis

Conexión JD SPB

Polling JD

Servicios externos (Midaz)

Servicios externos (CRM)

Servicios externos (Fees)

Resiliencia de Fees

Reconciliación

Calendario de feriados (BACEN/ANBIMA)

RabbitMQ

Entrega de webhooks

Límites de uso

Horarios operativos

Telemetría (OpenTelemetry)

Licencia

Encriptación

Configuración en tiempo de ejecución (Admin API)