tenantId. Ele é responsável pelo isolamento em nível de infraestrutura, incluindo a resolução de banco de dados da plataforma de multi-tenancy e o acesso a secretos com escopo de tenant.
O header X-Organization-Id define o escopo da organização Midaz dentro desse tenant. Ele é obrigatório em todas as rotas de transferência com escopo de organização, independentemente do modo de deployment. Requisições que omitem esse header ou fornecem um valor que não seja um UUID válido retornam uma resposta 400.
Processos em segundo plano, como o poller de TED IN e os workers de reconciliação, não recebem headers de requisição. Em deployments single-tenant, esses processos usam a variável de ambiente ORGANIZATION_ID como contexto de organização.
Níveis de configuração
A configuração do plugin Bank Transfer é dividida em três níveis:
- Configuração de infraestrutura (gerenciada pelo DevOps) controla URLs, credenciais, configurações de autenticação e timeouts. As alterações requerem reinicialização do serviço.
- Configurações do tenant (gerenciadas pelo time de produto via Admin API) controlam limites de transferência, políticas de tarifas e sobrescritas de horário de funcionamento. As alterações entram em vigor sem reiniciar o serviço.
- Configurações de conta (gerenciadas pelo time de produto via Admin API) controlam limites e restrições para contas individuais. As alterações entram em vigor sem reiniciar o serviço.
Decisões de negócio que você pode configurar
Estas são as configurações que GPMs e times de produto se importam. Todas são gerenciadas via Admin API em tempo de execução — sem necessidade de deploy.
Limites de transferência
Defina tetos de volume diário e mensal em dois níveis:- Por organização — aplica-se às transferências de uma organização Midaz dentro do tenant resolvido
- Por conta — aplica-se a uma conta específica do usuário final (sobrescreve os padrões da organização)
Política de tarifas
Controle se o plugin cobra tarifa em transferências TED OUT, TED IN e P2P. As regras de tarifa são definidas no Fees Engine e aplicadas por organização. Consulte Fees Engine para detalhes de configuração.Fail-open vs. fail-closed
Se o serviço de cálculo de tarifas estiver indisponível no momento de uma transferência, você tem duas opções:- Fail-open — permite que a transferência prossiga sem cobrar tarifa
- Fail-closed — bloqueia a transferência até que o serviço de tarifas esteja disponível novamente
FEES_FAIL_CLOSED_DEFAULT=false). Altere isso por organização via Admin API quando precisar que indisponibilidades do serviço de tarifas bloqueiem as transferências. O TED IN tem seu próprio interruptor de segurança, BTF_FEES_TED_IN_FAIL_OPEN, que é true por padrão para que os fundos recebidos sejam creditados com tarifa=0 se o plugin-fees estiver indisponível.
Recebimento de TED IN
Transferências recebidas estão desabilitadas por padrão. Habilite o TED IN por organização assim que suas credenciais JD SPB estiverem configuradas e o worker de polling estiver ativo.Sobrescritas de horários de funcionamento
O plugin aplica a janela de funcionamento do TED do BACEN por padrão. Você pode configurar janelas personalizadas por política de tenant — por exemplo, restringindo transferências apenas ao horário comercial — dentro dos limites do BACEN.Configuração de infraestrutura
As variáveis de ambiente definidas no deploy (URLs, credenciais, TLS, persistência, integrações, chaves de segurança) são definidas pelo DevOps e requerem reinicialização do serviço. Consulte a referência completa em Variáveis de ambiente.
Configuração em tempo de execução (Admin API)
As configurações de nível de tenant e de conta são gerenciadas via Admin API — sem necessidade de reinicialização. As alterações entram em vigor imediatamente (sujeito ao TTL do cache para configurações de tenant). As configurações disponíveis incluem:
- Limites de transferência (diário e mensal, por organização e por conta)
- Comportamento de tarifas (fail-open ou fail-closed quando o serviço de tarifas está indisponível)
- Recebimento de TED IN (habilitado ou desabilitado por organização)
- Sobrescritas de horários de funcionamento (janelas personalizadas dentro dos limites do BACEN)
Configurações gerenciadas pelo systemplane
As configurações abaixo são gerenciadas em tempo de execução através do systemplane (Admin API), não no momento do deploy. Cada uma tem um nome de variável de ambiente correspondente que ainda existe na base de código, mas o carregador de configuração ignora essas variáveis de ambiente e emite um WARN de depreciação se elas forem definidas — atribuí-las via ambiente não tem efeito. Use o systemplane para alterá-las.| Área | Configurações |
|---|---|
| Rate limiting | RATE_LIMIT_ENABLED, RATE_LIMIT_MAX, RATE_LIMIT_EXPIRY_SEC |
| CORS | CORS_ALLOWED_ORIGINS, CORS_ALLOWED_METHODS, CORS_ALLOWED_HEADERS (a origem padrão é o wildcard * quando não configurada; não validada na inicialização) |
| Política de tarifas | FEES_FAIL_CLOSED_DEFAULT, FEES_MAX_FEE_AMOUNT_CENTS, FEES_REFUND_ON_DEVOLUCAO, BTF_FEES_TED_IN_FAIL_OPEN |
| Limites de uso | USAGE_LIMITS_ENABLED, USAGE_LIMIT_DAILY_CENTS, USAGE_LIMIT_MONTHLY_CENTS |
| Horários de funcionamento | TRANSFER_OPERATING_OPEN, TRANSFER_OPERATING_CLOSE, TRANSFER_OPERATING_TIMEZONE |
| Idempotência / duplicate guard | IDEMPOTENCY_REQUIRE_REDIS, DUPLICATE_GUARD_TTL_SEC |
| Roteamento | ROUTING_* (todas as configurações de regra de roteamento) |
| Tuning de timeout & retry do JD | JD_TIMEOUT_MS, JD_MAX_RETRIES, JD_VALIDATE_EXTERNAL_SIGNATURE |
| Tuning de polling do JD | JD_POLL_MAX_MESSAGES_PER_CYCLE, JD_POLL_RECOVERY_BATCH_SIZE, JD_POLL_DISABLE_OPERATING_HOURS_WINDOW |
| Tuning de reconciliação | BTF_RECONCILIATION_BATCH_SIZE, BTF_RECONCILIATION_MAX_ATTEMPTS, BTF_RECONCILIATION_STALE_AFTER_SEC, BTF_RECONCILIATION_TICK_DEADLINE_SECONDS, RECONCILIATION_PENDING_ALERT_THRESHOLD |
| Tuning de publicação 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 qualquer um dos nomes acima via ambiente não tem efeito e é registrado em WARN como depreciado. Eles existem apenas como gêmeos de ambiente depreciados de configurações gerenciadas em runtime/systemplane.