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

# Variáveis de ambiente da Lerian SISBAJUD Mensageria

> Variáveis de ambiente da Lerian SISBAJUD Mensageria: runtime, autenticação, licença, gestão de chaves, API de execução, streaming de eventos, arquivos de resposta, armazenamento de objetos e Lerian STA.

Esta página lista as variáveis de ambiente da **Mensageria**. [Variáveis de ambiente do Lerian SISBAJUD executor](https://docs.lerian.studio/pt/rails/sisbajud/sisbajud-executor-environment-variables.md) lista as variáveis do executor. [Fundamentos de configuração do BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md) documenta as variáveis que todo serviço Go da Lerian compartilha: servidor, armazenamento de dados, telemetria e autenticação de plugin.

Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor padrão. Um qualificador em negrito (por exemplo, **Obrigatório**) marca as variáveis que você deve definir. `—` significa que não há padrão. Uma variável marcada como **Sensível** guarda uma credencial ou material de chave. Injete-a a partir do seu gerenciador de segredos no momento do deploy. Não faça commit do seu valor.

## Serviço e runtime

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SERVER_ADDRESS` | `:4031` | Endereço de escuta da API principal. `/health`, `/readyz` e `/version` usam esta porta. |
| `ENVIRONMENT_NAME` | — | Ambiente de execução. `ENV_NAME` é um nome alternativo. `local`, `development`, `staging`, `e2e` e `test` são valores de não produção. Qualquer outro valor, e nenhum valor, executa as verificações de produção. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc` ou `saas`. Qualquer outro valor recusa o boot. Com `saas`, o boot recusa uma conexão PostgreSQL ou Redis sem TLS. |
| `SYSTEMPLANE_ENABLED` | `false` | Serve a API de administração do [Systemplane](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md) em `/system` na porta principal. |

> [!NOTE]
>
> As verificações de produção exigem `POSTGRES_PASSWORD` e recusam `POSTGRES_SSLMODE=disable`. Com `STREAMING_ENABLED=true`, elas também exigem `STREAMING_TLS_ENABLED=true`.

## Autenticação

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | **Obrigatório** | `true` ou `false`. Um valor em branco ou qualquer outro valor recusa o boot. A Mensageria aceita `false` somente quando `ENV_NAME` é `development`, `develop`, `dev`, `local` ou `test`, e `DEPLOYMENT_MODE` não é `saas`. Com `false`, as operações protegidas ainda exigem um bearer token. |
| `PLUGIN_AUTH_HOST` | **Obrigatório se `PLUGIN_AUTH_ENABLED` ou `STA_TRANSFERS_ENABLED` for `true`** | Endereço do Access Manager. O envio ao Lerian STA obtém o seu token M2M deste endereço. |
| `AUTH_JWT_VERIFY_CERT` | **Obrigatório, ou `AUTH_JWT_VERIFY_CERT_PATH`** | Chaves públicas ou certificados PEM que verificam a assinatura dos bearer tokens. Este valor tem precedência sobre `AUTH_JWT_VERIFY_CERT_PATH`. |
| `AUTH_JWT_VERIFY_CERT_PATH` | **Obrigatório, ou `AUTH_JWT_VERIFY_CERT`** | Caminho de um arquivo com o mesmo conteúdo PEM. |
| `AUTH_JWT_ISSUER` | **Obrigatório** | O valor `iss` que os bearer tokens devem carregar. |

O boot aceita a ausência de chave de verificação e de emissor somente quando as três condições são verdadeiras: `PLUGIN_AUTH_ENABLED` é `true`, `DEPLOYMENT_MODE` é `local` ou não está definido, e `ENV_NAME` é `local`.

## Licença

[License Manager](https://docs.lerian.studio/pt/platform/licensing/license-manager.md) descreve como o produto verifica a licença.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `LICENSE_KEY` | **Obrigatório** | A chave de licença que a Lerian emitiu para o Lerian SISBAJUD. O boot recusa um valor vazio em qualquer ambiente. |
| `ORGANIZATION_IDS` | **Obrigatório** | Escopo da licença. Defina como `global`. Qualquer outro valor recusa o boot. |

## Gestão de chaves

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `KMS_PROVIDER` | **Obrigatório quando `ENVIRONMENT_NAME` é `production`** | Gerenciador de chaves da criptografia por envelope: `vault` (HashiCorp Vault Transit) ou `aws` (AWS KMS). Qualquer outro valor recusa o boot. Com qualquer outro ambiente, um valor não definido significa `vault`. |
| `AWS_REGION` | **Obrigatório com `aws`** | Região do AWS KMS. |
| `SISBAJUD_DEK_CACHE_TTL` | `5m` | Tempo que uma chave de dados desembrulhada fica no cache em memória. Duração Go. |
| `KEK_REWRAP_BACKFILL_ENABLED` | `false` | Executa o job em segundo plano que reembrulha as chaves de dados sob a nova versão da KEK depois de uma rotação. |
| `KEK_REWRAP_BACKFILL_SCAN_INTERVAL` | `300` | Intervalo do job de reembrulho, em segundos. |
| `KEK_REWRAP_BACKFILL_BATCH_SIZE` | `100` | Número máximo de chaves de dados, por tabela, que uma passada do job de reembrulho processa. |

### Vault (quando `KMS_PROVIDER=vault`)

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `VAULT_ADDR` | **Obrigatório** | Endereço do seu Vault. |
| `VAULT_AUTH_METHOD` | `token` | `token` ou `approle`. Qualquer outro valor recusa o boot. |
| `VAULT_TOKEN` | **Obrigatório para `token` quando `ENVIRONMENT_NAME` é `production`** | Token do Vault. Sensível. |
| `VAULT_APPROLE_ROLE_ID` | **Obrigatório para `approle`** | Role ID do AppRole. Sensível. |
| `VAULT_APPROLE_SECRET_ID` | **Obrigatório para `approle`** | Secret ID do AppRole. Sensível. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Caminho de montagem do engine Transit. |
| `VAULT_TIMEOUT_SEC` | `15` | Timeout de cada requisição ao Vault, em segundos. De `1` a `600`. |
| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Renova o token do Vault em segundo plano. |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Tempo mínimo entre duas renovações, em segundos. |

### AWS KMS (quando `KMS_PROVIDER=aws`)

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `KMS_AWS_KEY_MODE` | **Obrigatório** | `managed` ou `provided`. Não tem padrão. Qualquer outro valor recusa o boot. |
| `KMS_AWS_KEY_ARN` | **Obrigatório com `provided`** | ARN da sua chave do AWS KMS, na região de `AWS_REGION`. Um ARN de alias recusa o boot. Com `managed`, deixe-o vazio. |
| `KMS_AWS_ROTATION_CHECK_INTERVAL_SEC` | `3600` | Com `provided`, o intervalo, em segundos, em que a Mensageria procura uma rotação da sua chave. De `1` a `86400`. |
| `KMS_AWS_TIMEOUT_SEC` | `20` | Timeout de cada chamada ao AWS KMS, em segundos. De `1` a `600`. |

Os dois modos de chave:

* **`managed`.** A Mensageria cria uma chave para cada instituição, e `kek:rotate` a rotaciona.
* **`provided`.** Uma chave que você cria protege todas as instituições. A Mensageria nunca a cria nem a rotaciona, e `kek:rotate` retorna `422`. Quando o custodiante da sua chave a rotaciona, a Mensageria registra a nova versão.

Prepare a AWS antes do primeiro boot:

* No modo `provided`, a chave deve ser simétrica (`SYMMETRIC_DEFAULT`), com o uso `ENCRYPT_DECRYPT`, a origem `AWS_KMS` e o estado `Enabled`. A Mensageria recusa uma chave com material de chave importado.
* A Mensageria obtém as suas credenciais da AWS pela cadeia de credenciais padrão do AWS SDK.
* Nos dois modos, a sua identidade precisa de `kms:DescribeKey`, `kms:GenerateDataKey`, `kms:Decrypt`, `kms:ReEncryptFrom`, `kms:ReEncryptTo` e `kms:ListKeyRotations` nas suas chaves. No modo `managed`, ela também precisa de `kms:CreateKey`, `kms:TagResource`, `kms:CreateAlias`, `kms:RotateKeyOnDemand`, `kms:GetKeyRotationStatus`, `kms:ListAliases` e `tag:GetResources`.
* Cada chamada de chave de dados leva o contexto de criptografia `institution_id` e `key_purpose`. A política da sua chave pode usá-los em condições.

Escolha o provedor de chaves uma vez. Quando o banco de dados contém dados que outro provedor de chaves protege, o boot recusa.

## API de execução e sweeper

O executor lê as ordens e informa os resultados pela API de execução. [Integrando com o Lerian SISBAJUD](https://docs.lerian.studio/pt/rails/sisbajud/sisbajud-integration.md#execution-api) a descreve.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SISBAJUD_EXECUTION_ADDRESS` | `:4032` | Endereço de escuta da API de execução. Este listener aceita somente TLS. |
| `SISBAJUD_EXECUTION_TLS_CERT_FILE` | **Obrigatório** | Caminho do certificado de servidor da API de execução. |
| `SISBAJUD_EXECUTION_TLS_KEY_FILE` | **Obrigatório** | Caminho da chave privada desse certificado. Sensível. |
| `SISBAJUD_EXECUTION_MTLS_ENABLED` | `false` | `true` faz o listener exigir um certificado de cliente. Qualquer valor diferente de `true`, `false` ou em branco recusa o boot. |
| `SISBAJUD_EXECUTION_CLIENT_CA_FILE` | **Obrigatório se `SISBAJUD_EXECUTION_MTLS_ENABLED=true`** | Caminho do bundle de CA que verifica os certificados de cliente. |
| `RESPONSE_DEADLINE_MARGIN` | **Obrigatório** | Duração Go maior que 0, por exemplo `2h`. Para uma ordem que espera atrás de uma revisão anterior com resultado incerto, o sweeper mantém esta margem antes do prazo de resposta. |
| `EXECUTION_DRAINED_HEAD_ALARM_AFTER` | **Obrigatório** | Duração Go maior que 0, por exemplo `30m`. Quanto tempo uma ordem estacionada pode bloquear o seu sujeito antes de o sweeper disparar um alarme. |
| `EXECUTION_SWEEP_INTERVAL_SEC` | `60` | Intervalo do sweeper de execução, em segundos. |
| `EXECUTION_DEADLINE_MARGIN_SEC` | `RETURN_FILE_GENERATION_SCAN_INTERVAL` | Tempo, em segundos, entre o `deadlineAt` de uma ordem e o seu prazo de resposta. Deve ser maior que 0 e menor que `21600`. |
| `EXECUTION_CANARY_INTERVAL_SEC` | `300` | Intervalo do probe canário, em segundos. Cada execução envia um probe para cada instituição habilitada. |

## Streaming de eventos

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `STREAMING_ENABLED` | **Obrigatório: `true`** | Publica eventos. O padrão é `false`, e `false` recusa o boot: os avisos de execução precisam de um publicador real. |
| `STREAMING_BROKERS` | **Obrigatório** | Lista, separada por vírgulas, dos brokers Kafka dos eventos que a Mensageria publica. |
| `STREAMING_CLOUDEVENTS_SOURCE` | **Obrigatório** | Defina como `br-sisbajud`. Qualquer outro valor recusa o boot. |
| `STREAMING_TLS_ENABLED` | `false` · **`true` em produção** | Conecta aos brokers por TLS. |
| `STREAMING_SASL_MECHANISM` | — | Mecanismo SASL dos brokers. Com um mecanismo e sem TLS, o boot recusa, a menos que `STREAMING_SASL_ALLOW_PLAINTEXT` seja `true`. |
| `OUTBOX_ENABLED` | `true` | Caminho de entrega durável dos eventos. `STREAMING_ENABLED=true` o exige. |
| `OUTBOX_RETRY_WINDOW_SEC` | `300` | Tempo, em segundos, antes que a Mensageria tente de novo um evento que falhou. Com `STA_TRANSFERS_ENABLED=true`, um valor abaixo de `300` recusa o boot. |

## Arquivos de resposta e workers

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `RETURN_FILE_GENERATION_ENABLED` | `false` | Gera os arquivos de resposta de bloqueio para as ordens finalizadas que não têm arquivo de resposta. |
| `RETURN_FILE_GENERATION_SCAN_INTERVAL` | `3600` | Intervalo da geração de arquivos de resposta de bloqueio, em segundos. |
| `RETURN_FILE_GENERATION_LIMIT` | `500` | Número de ordens que uma passada de geração processa. |
| `INFORMATION_RETURN_FILE_GENERATION_ENABLED` | `false` | Gera os arquivos de resposta de informação (AJUD309). |
| `INFORMATION_RETURN_FILE_GENERATION_SCAN_INTERVAL` | `3600` | Intervalo da geração de arquivos de resposta de informação, em segundos. |
| `INFORMATION_RETURN_FILE_GENERATION_LIMIT` | `500` | Número de ordens que uma passada de geração de informação processa. |
| `RETURN_FILE_ENVIRONMENT` | `HOMOLOGATION` | `PRODUCTION` ou `HOMOLOGATION`. Um arquivo de resposta recebe o ambiente do arquivo de remessa por trás das suas ordens. Este valor se aplica somente quando nenhum arquivo de remessa as sustenta. Um valor inválido desliga a geração de arquivos de resposta. |
| `SISBAJUD_REMITTANCE_LAYOUTS` | `v111,v2026` | Layouts de remessa, separados por vírgulas, que a Mensageria aceita: `v111` e `v2026`. A recepção rejeita um arquivo em qualquer outro layout. Um valor inválido recusa o boot. |
| `SISBAJUD_RESPONSE_LAYOUT` | `auto` | Layout da resposta de bloqueio. `auto` responde cada remessa no layout em que ela chegou. `v111` ou `v2026` força um layout. Um valor inválido recusa o boot. |
| `SLA_ALERT_ENABLED` | `false` | Classifica as ordens ativas por faixa de risco de SLA e publica as faixas como métricas. |
| `SLA_ALERT_SCAN_INTERVAL` | `60` | Intervalo da classificação de SLA, em segundos. |
| `PROCESSING_LOCK_REAPER_ENABLED` | `true` | Apaga os locks de processamento expirados em segundo plano. |
| `PROCESSING_LOCK_REAPER_INTERVAL_SEC` | `300` | Intervalo da limpeza de locks, em segundos. |

## Armazenamento de objetos

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SEAWEEDFS_S3_ENDPOINT` | `http://localhost:8333` | Endpoint do armazenamento de objetos compatível com S3. |
| `SEAWEEDFS_BUCKET` | `sisbajud` | Bucket para os arquivos criptografados da Mensageria. |
| `SEAWEEDFS_REGION` | `us-east-1` | Região S3. |
| `SEAWEEDFS_CREDENTIALS_SOURCE` | `static` | `static` assina com as duas chaves abaixo, ou envia requisições sem assinatura quando as duas estão em branco. `default-chain` usa a cadeia de credenciais do AWS SDK, e então as duas chaves devem ficar em branco. |
| `SEAWEEDFS_ACCESS_KEY` | — | Chave de acesso do armazenamento de objetos. Sensível. |
| `SEAWEEDFS_SECRET_KEY` | — | Chave secreta do armazenamento de objetos. Sensível. |
| `STA_INBOUND_BUCKET` | **Obrigatório** | Bucket com os arquivos de remessa que o Lerian STA entrega. Usa o mesmo endpoint que `SEAWEEDFS_S3_ENDPOINT`. |
| `STA_FILE_LOCK_TTL` | `5` | Tempo de vida do lock de processamento de um arquivo, em minutos. |

## Consumidor do Lerian STA

A Mensageria recebe os arquivos de remessa somente pelos eventos que o [Lerian STA](https://docs.lerian.studio/pt/rails/sta/what-is-lerian-sta.md) publica. O consumidor usa as suas próprias configurações de broker, `STA_STREAM_*`. Ele não lê as variáveis `STREAMING_*`.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `STA_CONSUMER_ENABLED` | `false` | Recebe os arquivos de remessa pelos eventos do Lerian STA. |
| `STA_STREAM_BROKERS` | **Obrigatório se o consumidor estiver ligado** | Lista, separada por vírgulas, dos brokers Kafka do Lerian STA. |
| `STA_STREAM_SASL_MECHANISM` | **Obrigatório se o consumidor estiver ligado** | `PLAIN`, `SCRAM-SHA-256` ou `SCRAM-SHA-512`. |
| `STA_STREAM_SASL_USERNAME` | **Obrigatório se o consumidor estiver ligado** | Nome de usuário SASL. |
| `STA_STREAM_SASL_PASSWORD` | **Obrigatório se o consumidor estiver ligado** | Senha SASL. Sensível. |
| `STA_STREAM_TLS_ENABLED` | `false` | Conecta aos brokers por TLS. Com o consumidor ligado, `false` exige `STA_STREAM_SASL_ALLOW_PLAINTEXT=true`. |
| `STA_STREAM_TLS_CA_CERT` | **Obrigatório se o TLS estiver ligado** | Certificado de CA dos brokers, em PEM codificado em base64. |
| `STA_STREAM_SASL_ALLOW_PLAINTEXT` | `false` | Aceita SASL sem TLS. A produção recusa `true`. |
| `STA_CONSUMER_RETRY_BUDGET` | `3` | Número de retentativas de uma falha transitória dentro de uma entrega. |
| `STA_SOURCE_PRODUCT` | **Obrigatório se o consumidor ou o envio estiver ligado** | Nome do produto que o Lerian STA registra para este trilho. A Mensageria mantém somente os eventos com este nome. A configuração de exemplo usa `br-sisbajud`. |
| `STA_BACEN_SYSTEM_CODE` | **Obrigatório se o consumidor estiver ligado** | A configuração de exemplo usa `JUD`. |
| `STA_MAX_INBOUND_SIZE_BYTES` | **Obrigatório se o consumidor estiver ligado** | Maior arquivo de remessa, em bytes, que o consumidor baixa. Deve ser maior que 0. A configuração de exemplo usa `52428800`. |
| `STA_OBJECT_STORAGE_ENDPOINT` | **Obrigatório se o consumidor ou o envio estiver ligado** | Endpoint de armazenamento de objetos do Lerian STA. Deve indicar o mesmo armazenamento que `SEAWEEDFS_S3_ENDPOINT`. Um armazenamento diferente recusa o boot. |

## Envio ao Lerian STA

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `STA_TRANSFERS_ENABLED` | `false` | Envia os arquivos de resposta ao Lerian STA. Exige `PLUGIN_AUTH_HOST`. |
| `STA_TRANSFERS_BASE_URL` | **Obrigatório se o envio estiver ligado** | URL base da API do Lerian STA. |
| `STA_DOCUMENT_TYPE_AJUD302` | **Obrigatório se o envio estiver ligado** | Tipo de documento do Lerian STA para a resposta de bloqueio. A configuração de exemplo usa `AJUD302`. |
| `STA_DOCUMENT_TYPE_AJUD309` | **Obrigatório se o envio estiver ligado** | Tipo de documento do Lerian STA para a resposta de informação. A configuração de exemplo usa `AJUD309`. |
| `TRANSFER_OBJECT_STORAGE_BUCKET` | **Obrigatório se o envio estiver ligado** | Bucket compartilhado com o Lerian STA para os arquivos de resposta. Deve indicar o mesmo bucket que `STA_INBOUND_BUCKET`. Um bucket diferente recusa o boot. |
| `STA_CLIENT_ID` | **Obrigatório se o envio estiver ligado** | Client ID OAuth que obtém o token para o Lerian STA. |
| `STA_CLIENT_SECRET` | **Obrigatório se o envio estiver ligado** | Client secret OAuth para o Lerian STA. Sensível. |

## Valores que devem coincidir com o executor

* **`RESPONSE_DEADLINE_MARGIN`.** O executor lê a mesma variável. Defina o mesmo valor nos dois componentes.
* **TLS mútuo.** O executor tem a sua própria chave, `MENSAGERIA_MTLS_ENABLED`. Defina-a com o mesmo valor de `SISBAJUD_EXECUTION_MTLS_ENABLED`. Com TLS mútuo ligado na Mensageria e desligado no executor, o handshake TLS falha.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.