> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuração em tempo de execução (Systemplane)

> Visualize e altere a configuração operacional do Matcher em tempo de execução pelo Systemplane, sem precisar reiniciar o serviço em produção.

O Systemplane permite que você visualize e modifique a configuração do Matcher em tempo de execução — sem reiniciar o serviço. Em ambientes financeiros regulados, interrupções não planejadas para aplicar mudanças de configuração representam um risco de conformidade e uma disrupção operacional. O Systemplane elimina isso: parâmetros operacionais podem ser ajustados enquanto o serviço permanece em execução, mantendo os processos de reconciliação ininterruptos.

## Por que usar o Systemplane

***

Em um deploy tradicional, alterar um valor de configuração significa atualizar variáveis de ambiente e reiniciar o serviço. O Systemplane elimina esse downtime para muitas configurações:

* **Ajustar rate limits** durante picos de tráfego sem redeploy — evitando interrupções do serviço em momentos de alto volume de transações
* **Ajustar intervalos de workers** com base na carga de trabalho observada — otimizando o throughput de reconciliação sem mexer na infraestrutura
* **Atualizar tamanhos de connection pool** conforme os padrões de tráfego mudam
* **Inspecionar valores atuais em tempo de execução** para diagnosticar problemas em produção sem mergulhar nos logs

## Como funciona

***

O Systemplane fornece uma API de gerenciamento de chave-valor flat. Todas as chaves de configuração estão em um único namespace sob `/system/matcher`.

### Endpoints

| Endpoint               | Método | O que faz                                    |
| ---------------------- | ------ | -------------------------------------------- |
| `/system/matcher`      | `GET`  | Listar todas as chaves e seus valores atuais |
| `/system/matcher/:key` | `GET`  | Obter o valor atual de uma chave específica  |
| `/system/matcher/:key` | `PUT`  | Atualizar o valor de uma chave específica    |

<Note>
  Esses endpoints são servidos diretamente pela instância do Matcher em execução. Eles não são versionados sob `/v1` — use os caminhos acima exatamente como mostrado.
</Note>

## Permissões

***

Os endpoints do Systemplane são protegidos pela mesma autenticação usada por todas as rotas da API do Matcher. Quando a autenticação está habilitada, todos os endpoints `/system` requerem a permissão RBAC `system-runtime-config:admin` (recurso `system-runtime-config`, ação `admin`).

Quando a autenticação está desabilitada, todos os endpoints são acessíveis sem restrição.

## Comportamentos de aplicação

***

Nem todo valor de configuração pode ser alterado em tempo de execução. Cada chave tem um **comportamento de aplicação** que indica quando as mudanças entram em vigor:

| Comportamento               | O que acontece                                                                                                 |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Somente bootstrap**       | O valor é lido uma vez na inicialização. Você deve reiniciar o serviço para que as alterações entrem em vigor. |
| **Leitura em tempo real**   | As alterações entram em vigor imediatamente na próxima requisição.                                             |
| **Reconstrução de bundle**  | As alterações disparam uma atualização de estado interno. Entra em vigor em segundos.                          |
| **Reconciliação de worker** | Workers em background captam o novo valor no próximo ciclo.                                                    |

Chaves que são somente bootstrap NÃO estão registradas na API do systemplane — elas são gerenciadas exclusivamente por variáveis de ambiente. Isso evita uma armadilha onde um PUT de admin pareceria ter sucesso mas o processo em execução continuaria silenciosamente usando o valor do momento de inicialização.

## Chaves de configuração comuns

***

Abaixo estão as chaves mais comumente ajustadas, organizadas por categoria. Para uma lista completa, chame `GET /system/matcher`.

### Chaves ajustáveis em tempo de execução

Essas chaves podem ser alteradas sem reiniciar o Matcher:

| Chave                             | Variável de ambiente              | Descrição                                                                 |
| --------------------------------- | --------------------------------- | ------------------------------------------------------------------------- |
| `server.body_limit_bytes`         | `HTTP_BODY_LIMIT_BYTES`           | Tamanho máximo do corpo da requisição HTTP                                |
| `cors.allowed_origins`            | `CORS_ALLOWED_ORIGINS`            | Origens CORS permitidas                                                   |
| `cors.allowed_methods`            | `CORS_ALLOWED_METHODS`            | Métodos CORS permitidos                                                   |
| `cors.allowed_headers`            | `CORS_ALLOWED_HEADERS`            | Headers CORS permitidos                                                   |
| `swagger.enabled`                 | `SWAGGER_ENABLED`                 | Habilitar ou desabilitar o Swagger UI                                     |
| `swagger.host`                    | `SWAGGER_HOST`                    | Override do host do Swagger                                               |
| `swagger.schemes`                 | `SWAGGER_SCHEMES`                 | Esquemas de URL do Swagger                                                |
| `rate_limit.enabled`              | `RATE_LIMIT_ENABLED`              | Habilitar ou desabilitar o rate limiting global                           |
| `rate_limit.max`                  | `RATE_LIMIT_MAX`                  | Máximo de requisições por janela de rate limit                            |
| `rate_limit.expiry_sec`           | `RATE_LIMIT_EXPIRY_SEC`           | Duração da janela de rate limit (segundos)                                |
| `rate_limit.export_max`           | `EXPORT_RATE_LIMIT_MAX`           | Rate limit do endpoint de exportação                                      |
| `rate_limit.dispatch_max`         | `DISPATCH_RATE_LIMIT_MAX`         | Rate limit do endpoint de dispatch                                        |
| `rate_limit.admin_max`            | `ADMIN_RATE_LIMIT_MAX`            | Rate limit do plano admin (`/system`)                                     |
| `idempotency.retry_window_sec`    | `IDEMPOTENCY_RETRY_WINDOW_SEC`    | Janela para tentar novamente requisições idempotentes com falha           |
| `idempotency.success_ttl_hours`   | `IDEMPOTENCY_SUCCESS_TTL_HOURS`   | Por quanto tempo as chaves de idempotência concluídas ficam em cache      |
| `fetcher.discovery_interval_sec`  | `FETCHER_DISCOVERY_INTERVAL_SEC`  | Com que frequência o Matcher consulta o Fetcher por novas fontes de dados |
| `export_worker.enabled`           | `EXPORT_WORKER_ENABLED`           | Habilitar ou desabilitar o worker de exportação                           |
| `export_worker.poll_interval_sec` | `EXPORT_WORKER_POLL_INTERVAL_SEC` | Com que frequência o worker de exportação verifica novos jobs             |
| `cleanup_worker.enabled`          | `CLEANUP_WORKER_ENABLED`          | Habilitar ou desabilitar o worker de limpeza                              |
| `cleanup_worker.interval_sec`     | `CLEANUP_WORKER_INTERVAL_SEC`     | Intervalo do worker de limpeza                                            |
| `scheduler.interval_sec`          | `SCHEDULER_INTERVAL_SEC`          | Intervalo de polling do scheduler                                         |
| `archival.enabled`                | `ARCHIVAL_WORKER_ENABLED`         | Habilitar ou desabilitar o worker de arquivamento                         |
| `webhook.timeout_sec`             | `WEBHOOK_TIMEOUT_SEC`             | Timeout para dispatch de webhooks/callbacks                               |
| `callback_rate_limit.per_minute`  | `CALLBACK_RATE_LIMIT_PER_MIN`     | Máximo de callbacks por sistema externo por minuto                        |
| `deduplication.ttl_sec`           | `DEDUPE_TTL_SEC`                  | TTL de deduplicação em segundos                                           |

### Chaves multi-tenant (ajustáveis em tempo de execução)

Essas chaves controlam o comportamento multi-tenant e podem ser ajustadas sem reinício. Consulte [Modo Multi-Tenant](/pt/matcher/configuration/matcher-multi-tenant) para mais detalhes.

<Note>
  Habilitar o modo multi-tenant em si (`tenancy.multi_tenant_enabled` / `MULTI_TENANT_ENABLED`) é **somente bootstrap** — é lido uma vez na inicialização e requer um reinício. Não está registrado na API do Systemplane e não pode ser alternado em tempo de execução. Consulte a tabela de somente bootstrap mais abaixo.
</Note>

| Chave                                   | Variável de ambiente            | Descrição                                             |
| --------------------------------------- | ------------------------------- | ----------------------------------------------------- |
| `tenancy.multi_tenant_url`              | `MULTI_TENANT_URL`              | URL do serviço de multi-tenancy                       |
| `tenancy.multi_tenant_max_tenant_pools` | `MULTI_TENANT_MAX_TENANT_POOLS` | Máximo de pools de tenant simultâneos                 |
| `tenancy.multi_tenant_idle_timeout_sec` | `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Timeout de ociosidade para eviction de pool de tenant |
| `tenancy.multi_tenant_cache_ttl_sec`    | `MULTI_TENANT_CACHE_TTL_SEC`    | TTL do cache de configuração de tenant                |

### Chaves somente bootstrap (requerem reinício)

Essas chaves não estão registradas na API do systemplane. Altere-as por variáveis de ambiente e reinicie:

| Chave                          | Variável de ambiente   | Descrição                                                                                              |
| ------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------ |
| `tenancy.multi_tenant_enabled` | `MULTI_TENANT_ENABLED` | Habilitar infraestrutura multi-tenant. Lido uma vez na inicialização; requer um reinício para alterar. |
| `app.env_name`                 | `ENV_NAME`             | Nome do ambiente da aplicação                                                                          |
| `telemetry.enabled`            | `ENABLE_TELEMETRY`     | Habilitar OpenTelemetry                                                                                |
| `app.log_level`                | `LOG_LEVEL`            | Nível de log da aplicação (debug, info, warn, error)                                                   |
| `server.address`               | `SERVER_ADDRESS`       | Endereço de escuta do servidor HTTP                                                                    |
| `postgres.primary_host`        | `POSTGRES_HOST`        | Host do banco de dados primário                                                                        |
| `postgres.primary_port`        | `POSTGRES_PORT`        | Porta do banco de dados primário                                                                       |
| `postgres.primary_db`          | `POSTGRES_DB`          | Nome do banco de dados primário                                                                        |
| `redis.host`                   | `REDIS_HOST`           | Host do Redis                                                                                          |
| `rabbitmq.host`                | `RABBITMQ_HOST`        | Host do RabbitMQ                                                                                       |
| `auth.enabled`                 | `PLUGIN_AUTH_ENABLED`  | Habilitar middleware de autenticação                                                                   |
| `auth.host`                    | `PLUGIN_AUTH_ADDRESS`  | Endereço do serviço de autenticação                                                                    |

## Boas práticas

***

<AccordionGroup>
  <Accordion title="Inspecione os valores atuais antes de alterar">
    Chame `GET /system/matcher` para ver todos os valores atuais em tempo de execução antes de fazer qualquer alteração. Isso confirma o que o processo está realmente usando, que pode diferir das variáveis de ambiente se chamadas PUT anteriores foram feitas.
  </Accordion>

  <Accordion title="Teste mudanças em staging primeiro">
    Mesmo que as alterações em tempo de execução não requeiram reinício, elas entram em vigor imediatamente. Teste em um ambiente de staging antes de aplicar em produção.
  </Accordion>

  <Accordion title="Reinicie para chaves somente bootstrap">
    Se uma chave não estiver visível em `GET /system/matcher`, ela é somente bootstrap. Atualize a variável de ambiente e reinicie o serviço — não há caminho em tempo de execução para esses valores.
  </Accordion>
</AccordionGroup>

## Próximos passos

***

<Card title="Modo multi-tenant" icon="building" href="/pt/matcher/configuration/matcher-multi-tenant" horizontal>
  Habilitar e configurar o isolamento de tenant.
</Card>

<Card title="Roteamento de exceções" icon="route" href="/pt/matcher/configuration/matcher-exception-routing" horizontal>
  Configurar como as exceções são despachadas para sistemas externos.
</Card>

<Card title="Regras de match" icon="code-compare" href="/pt/matcher/configuration/matcher-match-rules" horizontal>
  Configurar regras de correspondência de transações.
</Card>

<Card title="Segurança" icon="shield" href="/pt/matcher/reference/matcher-security" horizontal>
  Autenticação, autorização e proteção de dados.
</Card>