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

> Variáveis de deploy específicas do Consignado para conectividade com o Dataprev, workers, leilões, credenciais, artefatos, ritmo e janelas operacionais.

Defina essas variáveis no momento do deploy. Salvo indicação contrária, alterar uma delas exige uma reinicialização. A [referência de configuração do BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md) cobre o runtime compartilhado da Lerian: servidor, datastores, telemetria, autenticação, streaming e outbox. Esta página lista as configurações específicas do Consignado e as poucas configurações compartilhadas que mudam materialmente o comportamento do trilho.

`—` significa nenhum padrão. Variáveis que carregam certificados, chaves privadas, segredos OAuth ou chaves HMAC são sensíveis e devem vir de um gerenciador de segredos.

Um deploy é gerenciado quando `DEPLOYMENT_MODE` é `byoc` ou `saas`, quando `ENV_NAME` é `production` ou quando `MULTI_TENANT_ENABLED` é `true`.

## Serviço e modo de tenant

| Variável | Padrão | Finalidade |
| - | - | - |
| `SERVER_ADDRESS` | `:8080` | Listener HTTP principal para a API e os probes. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc` ou `saas`. A inicialização recusa qualquer outro valor. `byoc` e `saas` tornam o deploy gerenciado. |
| `ENV_NAME` | `development` | Rótulo do ambiente. `production` torna o deploy gerenciado. |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita a configuração em tempo de execução em `/system`. Com `MULTI_TENANT_ENABLED=true`, apenas um operador da plataforma Lerian cujo token não carrega tenant pode chamá-la; qualquer outro chamador recebe `403`. |
| `LICENSE_KEY` | — | Chave de licença Lerian. Obrigatória em todo modo de deploy: uma chave vazia, ou que o serviço de licenças recuse, interrompe a inicialização antes de o gateway abrir qualquer datastore. O gateway valida a chave como licença global na inicialização e a cada 6 horas depois, e para pelo desligamento gracioso se ela falhar mais tarde. Ele não lê `ORGANIZATION_IDS`. Veja [License Manager](https://docs.lerian.studio/pt/platform/licensing/license-manager.md). Sensível. |
| `MULTI_TENANT_ENABLED` | `false` | Executa o gateway para vários tenants. `true` torna o deploy gerenciado. |
| `OUTBOX_ENABLED` | `true` | Deve ser `true`; a inicialização recusa um deploy que não consiga registrar fatos do trilho de forma durável. |
| `OUTBOX_RETENTION_PUBLISHED_HOURS` | `1` | Horas que um fato publicado permanece no outbox do gateway após a publicação, de `0` a `87600`. `0` mantém os fatos publicados para sempre. Um fato não publicado nunca é excluído. |
| `STREAMING_ENABLED` | `true` | Deve ser `true`; o relay de streaming é o único a publicar os fatos do outbox. |
| `STREAMING_BROKERS` | — | Lista de brokers obrigatória. A inicialização recusa um relay sem destino. |
| `STREAMING_CLOUDEVENTS_SOURCE` | — | Deve ser exatamente `consignado-gw`. A inicialização recusa qualquer outro valor; uma origem errada significa que nenhum fato chega a um consumidor. |
| `STREAMING_KAFKA_TLS_ENABLED` | `false` | Conecta aos brokers por TLS. A inicialização exige `true`, a menos que `STREAMING_KAFKA_ALLOW_PLAINTEXT` seja `true`. |
| `STREAMING_KAFKA_ALLOW_PLAINTEXT` | `false` | Permite uma conexão sem criptografia com os brokers quando `ENV_NAME` é `development`, `local` ou `test`. Um deploy gerenciado a recusa. |
| `STREAMING_KAFKA_SASL_MECHANISM` | — | `plain`, `scram-sha-256` ou `scram-sha-512`. Um deploy gerenciado exige um dos dois valores SCRAM. |
| `STREAMING_KAFKA_SASL_USERNAME_FILE` | — | Caminho do arquivo que contém o nome de usuário do broker. Obrigatório com um mecanismo SASL e em um deploy gerenciado. |
| `STREAMING_KAFKA_SASL_PASSWORD_FILE` | — | Caminho do arquivo que contém a senha do broker. Obrigatório com um mecanismo SASL e em um deploy gerenciado. Sensível. |
| `SUBSCRIPTIONS_HUB_ENABLED` | `false` | Um deploy gerenciado exige `true` e recusa a inicialização sem ele. |
| `SUBSCRIPTIONS_HUB_BASE_URL` | — | URL base do Streaming Hub. Um deploy gerenciado recusa a inicialização sem ela. |

O desligamento segue o ciclo de vida compartilhado do servidor (`SHUTDOWN_DRAIN_DELAY`, `SHUTDOWN_TIMEOUT`). Veja a [configuração do BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md#server). Um gateway que termina o TLS por conta própria ignora as duas variáveis e usa 30 segundos fixos, sem drenagem.

## Declaração ao Access Manager

A autorização das requisições usa `PLUGIN_AUTH_ENABLED` (padrão `true`) e `PLUGIN_AUTH_HOST`, conforme descrito em [Autenticação de plugin](https://docs.lerian.studio/pt/reference/byoc-configuration.md#plugin-authentication). Com a autorização ligada, o gateway publica seu manifesto de permissões no Access Manager na inicialização, e uma publicação com falha ou uma configuração malformada do cliente do Access Manager interrompe a inicialização. O erro nomeia a variável. `AUTH_REQUIRED`, `AUTH_BREAKER_ENABLED`, `AUTH_M2M_PRODUCT_FORWARD_ENABLED` e `AUTH_PRINCIPAL_REQUIRED_WHEN_DISABLED` aceitam apenas `true` ou `false`. `AUTH_TIMEOUT` e `AUTH_CACHE_TTL` precisam de uma duração com unidade, como `30s`. `AUTH_RETRY_MAX` deve ser um inteiro. `AUTH_JWT_VERIFY_CERT` e o arquivo em `AUTH_JWT_VERIFY_CERT_PATH` devem conter chaves públicas RSA ou certificados em PEM.

| Variável | Padrão | Finalidade |
| - | - | - |
| `IDP_DECLARATION_ENABLED` | `true` | Publica o manifesto de permissões na inicialização. A publicação exige o Access Manager 3.13.0 ou posterior. Defina como `false` quando o serviço de identidade for multi-tenant: ele recusa a publicação com `501`. `false` pula apenas a publicação; a autorização das requisições continua ligada. Com `false`, entre em contato com o suporte da Lerian antes que o gateway atenda tenants. |
| `PLUGIN_IDENTITY_ADDRESS` | — | Serviço de identidade que recebe o manifesto. Obrigatório quando `IDP_DECLARATION_ENABLED` é `true`. Um deploy gerenciado exige `https://`. |
| `PLUGIN_AUTH_CLIENT_ID` | — | Client ID com o qual o gateway publica o manifesto. Obrigatório quando `IDP_DECLARATION_ENABLED` é `true`. |
| `PLUGIN_AUTH_CLIENT_SECRET` | — | Client secret desse client ID. Obrigatório quando `IDP_DECLARATION_ENABLED` é `true`. Sensível. |

## Cliente e autenticação do Dataprev

| Variável | Padrão | Finalidade |
| - | - | - |
| `DATAPREV_ENABLED` | `false` | Chave mestra para o runtime do trilho Dataprev. |
| `DATAPREV_BASE_URL` | — | URL base da API principal do Dataprev. HTTPS é obrigatório em deploys gerenciados; um deploy não gerenciado permite HTTP apenas para hosts loopback. |
| `DATAPREV_TOMBAMENTO_BASE_URL` | — | Endpoint separado para operações de tombamento. Vazio mantém essas operações indisponíveis. Segue a mesma política de HTTPS/loopback. |
| `DATAPREV_OAUTH_TOKEN_URL` | — | Endpoint de token OAuth2. HTTPS é obrigatório em deploys gerenciados; um deploy não gerenciado permite HTTP apenas para hosts loopback. |
| `DATAPREV_OAUTH_CLIENT_ID` | — | Client ID OAuth. Sensível. |
| `DATAPREV_OAUTH_CLIENT_SECRET` | — | Client secret OAuth. Sensível. |
| `DATAPREV_OAUTH_SCOPES` | — | Escopos OAuth separados por vírgula solicitados ao Dataprev. |
| `DATAPREV_CERT_FILE` | — | Caminho local do certificado ICP-Brasil para desenvolvimento não gerenciado. Sensível. |
| `DATAPREV_KEY_FILE` | — | Caminho local da chave privada pareada com `DATAPREV_CERT_FILE`. Sensível. |
| `DATAPREV_CODIGO_SOLICITANTE` | — | Código de solicitante de três dígitos. |
| `DATAPREV_REQUEST_TIMEOUT_SEC` | `30` | Timeout para uma requisição ao Dataprev. |
| `DATAPREV_REQUESTS_PER_SECOND` | `25` | Taxa do trilho, de 0 a 25, para requisições que não carregam identidade de tenant. Com o Systemplane habilitado, o valor armazenado se aplica no lugar dela. |
| `DATAPREV_CONSENT_CACHE_HMAC_KEY` | — | Chave HMAC para os registros e as entradas de cache de consentimento do trabalhador. As leituras de margem e de FGTS do trabalhador recusam sem ela, e a inicialização recusa um deploy com Redis sem ela. Sensível. |

Deploys gerenciados devem usar custódia de credenciais por tenant. Eles falham de forma fechada em vez de recorrer a um cliente sem autenticação ou sem mTLS.

## Contrato e janelas de portabilidade

| Variável | Padrão | Finalidade |
| - | - | - |
| `DATAPREV_AVERBACAO_ENABLED` | `false` | Habilita a averbação, o anexo de CCB e a importação de contrato com os dados de contabilização. Também habilita o armazenamento de CCB e de artefatos do trilho e as correções de contrato. Também atende a averbação por portabilidade; com `false`, essa operação responde `501`. |
| `DATAPREV_PORTABILIDADE_SOLICITACAO_WINDOW_HOURS` | `72` | Janela de lookback para propostas de portabilidade. |
| `DATAPREV_PORTABILIDADE_INCLUSAO_GARANTIAS_PATH` | — | Override para o caminho de envio de garantia de portabilidade do Dataprev. |
| `DATAPREV_PORTABILIDADE_AVERBACAO_WINDOW_DAYS` | `20` | Dias corridos, a partir da data de exclusão de origem informada na requisição, para registrar uma portabilidade de entrada. |
| `DATAPREV_REFINANCIAMENTO_REVERSAO_WINDOW_BUSINESS_DAYS` | `7` | Janela em dias úteis para reversão de refinanciamento. |
| `DATAPREV_SALDO_DEVEDOR_CLOCK_INTERVAL_SEC` | `3600` | Cadência para obrigações de saldo devedor e fallback de fim de mês. |
| `DATAPREV_SALDO_DEVEDOR_REENVIO_INTERVAL_SEC` | `60` | Cadência do reenvio dos informes de saldo devedor que uma virada de competência reteve. |
| `CONSIGNADO_DOCUMENTATION_DEADLINE_ENABLED` | `false` | Publica `consignado.averbacao.documentation_deadline` para averbações que aguardam a documentação e para o novo contrato de uma renegociação aceita por meio do gateway, contado a partir da aceitação. |
| `CONSIGNADO_DOCUMENTATION_DEADLINE_INTERVAL_SEC` | `60` | Cadência da verificação do prazo da documentação. |
| `DATAPREV_DOCUMENTATION_FOLLOWUP_ENABLED` | `false` | Lê no Dataprev, uma vez por dia, cada averbação que aguarda a documentação, a partir de um dia após a averbação. Também lê o novo contrato de cada refinanciamento aceito por meio deste gateway durante 14 dias após o desfecho. Isso encontra uma reversão feita no portal do Dataprev. Uma vez por semana, também relê cada contrato encerrado por término de vínculo enquanto a dívida permanece. Exige `DATAPREV_AVERBACAO_ENABLED=true`. |
| `DATAPREV_DOCUMENTATION_FOLLOWUP_INTERVAL_SEC` | `300` | Cadência da passada de acompanhamento. |
| `DATAPREV_DOCUMENTATION_FOLLOWUP_CAP_DAYS` | `7` | Dias após o instante de vencimento da documentação durante os quais o acompanhamento continua lendo um contrato. |

## Conciliação e feeds de emprego

| Variável | Padrão | Finalidade |
| - | - | - |
| `DATAPREV_RECONCILIATION_ENABLED` | `false` | Habilita a conciliação de escrituração de folha de pagamento e de repasse. Cada execução lê todos os empregadores. Com `MULTI_TENANT_ENABLED=true`, ela roda para todo tenant ativo e pula um tenant sem credencial do Dataprev armazenada. |
| `DATAPREV_RECONCILIATION_INTERVAL_SEC` | `3600` | Cadência de conciliação. |
| `DATAPREV_RECONCILIATION_LOOKBACK_MONTHS` | `1` | Competências de folha anteriores incluídas em cada execução. |
| `DATAPREV_EMPLOYMENT_REPORT_ENABLED` | `false` | Habilita o feed de rescisão de emprego. |
| `DATAPREV_EMPLOYMENT_REPORT_ADAPTER` | `disabled` | `dataprev` para o adapter real; `fake` é apenas local. |
| `DATAPREV_EMPLOYMENT_REPORT_INTERVAL_SEC` | `3600` | Cadência do relatório de emprego. |
| `DATAPREV_EMPLOYMENT_REPORT_CONCURRENCY` | `4` | Workers concorrentes por tenant. |
| `DATAPREV_EMPLOYMENT_REPORT_TENANT_TIMEOUT_SEC` | `300` | Tempo máximo de processamento para um tenant em uma execução. |
| `DATAPREV_MIGRACAO_ENABLED` | `false` | Habilita a leitura dos contratos que o Dataprev moveu para o novo vínculo empregatício do trabalhador. Publica `consignado.migracao.efetivada`. Exige `DATAPREV_ENABLED=true`. |
| `DATAPREV_MIGRACAO_INTERVAL_SEC` | `86400` | Cadência da leitura de migração de contratos. Deve ser positiva. |

## Exclusão

| Variável | Padrão | Finalidade |
| - | - | - |
| `DATAPREV_EXCLUSION_ENABLED` | `false` | Habilita a admissão e a recuperação de exclusão. |
| `DATAPREV_EXCLUSION_PROVIDER_TIMEOUT_SEC` | `30` | Timeout para uma chamada ao provedor de exclusão. |
| `DATAPREV_EXCLUSION_CLAIM_DWELL_SEC` | `60` | Tempo de permanência mínimo antes que um trabalho reivindicado possa ser repetido. |
| `DATAPREV_EXCLUSION_STATUS_CHECK_LEASE_SEC` | `60` | Lease para verificações de status de exclusão. |
| `DATAPREV_EXCLUSION_RECOVERY_INTERVAL_SEC` | `30` | Cadência do loop de recuperação. |
| `DATAPREV_EXCLUSION_RECOVERY_BATCH` | `50` | Operações reivindicadas por execução. |
| `DATAPREV_EXCLUSION_RECOVERY_CONCURRENCY` | `4` | Workers de recuperação concorrentes. |
| `DATAPREV_EXCLUSION_RECOVERY_TENANT_TIMEOUT_SEC` | `60` | Tempo máximo de processamento para um tenant em uma execução. |

Deixe `DATAPREV_EXCLUSION_ADAPTER` e `DATAPREV_EXCLUSION_FAKE_BASE_URL` sem definir.

## Recuperação de desfecho

Um comando de trilho pode terminar com o desfecho não estabelecido: o processo morreu no meio da chamada, ou o Dataprev nunca respondeu. Dois loops de recuperação convergem esse estado com o registro próprio do trilho. Um terceiro loop reenvia um lance cuja resposta do trilho se perdeu. Os três loops ficam desligados por padrão. Habilite-os em qualquer deploy que envie averbações, comandos de trilho ou lances. Caso contrário, nada converge automaticamente um desfecho não estabelecido.

| Variável | Padrão | Finalidade |
| - | - | - |
| `DATAPREV_AVERBACAO_RECOVERY_ENABLED` | `false` | Habilita a convergência de desfecho de averbação. |
| `DATAPREV_AVERBACAO_RECOVERY_INTERVAL_SEC` | `60` | Cadência de convergência. |
| `DATAPREV_AVERBACAO_RECOVERY_BATCH` | `50` | Registros reivindicados por execução. |
| `DATAPREV_AVERBACAO_RECOVERY_CONCURRENCY` | `4` | Workers concorrentes por tenant. |
| `DATAPREV_AVERBACAO_RECOVERY_TENANT_TIMEOUT_SEC` | `60` | Tempo máximo de processamento para um tenant em uma execução. |
| `DATAPREV_AVERBACAO_RECOVERY_MINIMUM_DWELL_SEC` | `300` | Idade mínima antes que um desfecho não estabelecido seja conciliado. |
| `DATAPREV_AVERBACAO_RECOVERY_PROVIDER_TIMEOUT_SEC` | `30` | Timeout para uma leitura do registro. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_ENABLED` | `false` | Habilita a convergência de refinanciamento, reversão, renegociação, exclusão de portabilidade do lado de origem, antecipação e alteração de termos. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_INTERVAL_SEC` | `60` | Cadência de convergência. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_BATCH` | `50` | Registros reivindicados por execução. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_CONCURRENCY` | `4` | Workers concorrentes por tenant. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_TENANT_TIMEOUT_SEC` | `60` | Tempo máximo de processamento para um tenant em uma execução. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_MINIMUM_DWELL_SEC` | `300` | Idade mínima antes que um desfecho não estabelecido seja conciliado. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_PROVIDER_TIMEOUT_SEC` | `30` | Timeout para uma leitura do registro. |
| `CONSIGNADO_BID_RECONDUCTION_ENABLED` | `false` | Habilita o reenvio de lances cuja resposta do trilho se perdeu, com o número de proposta original. |
| `CONSIGNADO_BID_RECONDUCTION_INTERVAL_SEC` | `15` | Cadência do reenvio. |
| `CONSIGNADO_BID_RECONDUCTION_BATCH_SIZE` | `20` | Lances reenviados em uma execução. |

## Leilões e lances de clientes

| Variável | Padrão | Finalidade |
| - | - | - |
| `LEILAO_ENABLED` | `false` | Habilita a descoberta agendada de solicitações de empréstimo abertas. Com `MULTI_TENANT_ENABLED=true`, roda para todo tenant com credenciais do Dataprev em custódia. |
| `LEILAO_CLIENT_BID_ENABLED` | `false` | Habilita a superfície de comando de lance autenticado do cliente. |
| `LEILAO_INTERVAL_SEC` | `3600` | Cadência de descoberta de leilão. |
| `LEILAO_PORTAL_BASE_URL` | — | URL base opcional do portal do trabalhador. Deixar sem definir é um deploy válido: os lances então trafegam com os próprios contatos do cliente. Um valor definido é validado na inicialização, e um valor inseguro falha a inicialização de forma fechada. |
| `LEILAO_DISCOVERY_LOOKBACK_HOURS` | `48` | Largura de cada janela de descoberta. Ela deve ser maior que `LEILAO_INTERVAL_SEC` mais `LEILAO_DISCOVERY_CLOCK_SKEW_SEC`, ou a inicialização falha. |
| `LEILAO_DISCOVERY_CLOCK_SKEW_SEC` | `300` | Sobreposição de clock skew aplicada às janelas de descoberta. Cada janela de leitura da conciliação também termina essa quantidade de segundos antes do relógio do gateway. |
| `LEILAO_FAST_LANE_ENABLED` | `false` | Habilita uma segunda execução de descoberta sobre os últimos 60 segundos de solicitações abertas, uma vez por segundo por padrão. Ela só começa com `LEILAO_ENABLED=true` e `MULTI_TENANT_ENABLED=false`. Em um deploy multi-tenant, registra um aviso e não começa. |
| `LEILAO_PORTABILITY_ENABLED` | `false` | Habilita a descoberta de portabilidade. Isso é independente de `LEILAO_ENABLED`. |
| `LEILAO_PORTABILITY_INTERVAL_SEC` | `3600` | Cadência da execução de descoberta de portabilidade. |

A descoberta de portabilidade exige `LEILAO_PORTABILITY_ENABLED=true`, `DATAPREV_ENABLED=true`, `STREAMING_ENABLED=true`, um banco de dados primário e o outbox canônico. Ela não exige `LEILAO_ENABLED=true`. A janela de listagem de portabilidade é de 72 horas por padrão (`DATAPREV_PORTABILIDADE_SOLICITACAO_WINDOW_HOURS`). O serviço recusa a inicialização a menos que essa janela seja maior que `LEILAO_PORTABILITY_INTERVAL_SEC` mais a margem de 300 segundos de `LEILAO_DISCOVERY_CLOCK_SKEW_SEC`.

## Custódia de credenciais e artefatos

| Variável | Padrão | Finalidade |
| - | - | - |
| `CREDENTIALS_STORE_ENABLED` | `false` | Habilita a custódia de credenciais do Dataprev. Um deploy gerenciado a exige. |
| `CREDENTIALS_CLEANUP_INTERVAL_SEC` | `30` | Cadência de limpeza de credenciais. |
| `CREDENTIALS_CLEANUP_BATCH_SIZE` | `50` | Credenciais reivindicadas por execução de limpeza. |
| `CREDENTIALS_CLEANUP_CONCURRENCY` | `4` | Workers de limpeza concorrentes. |
| `CREDENTIALS_CLEANUP_LEASE_SEC` | `60` | Lease de limpeza. |
| `CREDENTIALS_CLEANUP_PERSISTENCE_TIMEOUT_SEC` | `5` | Timeout de persistência para uma operação de limpeza. |
| `CONSIGNADO_CERTIFICATE_EXPIRY_ENABLED` | `true` | Publica `consignado.certificate.expiring` aos 30 dias e aos 7 dias antes de o certificado do Dataprev em custódia vencer, e exporta o gauge `consignado_dataprev_certificate_not_after_seconds`. Lê apenas os dados de custódia do próprio gateway. |
| `CONSIGNADO_CERTIFICATE_EXPIRY_INTERVAL_SEC` | `3600` | Cadência da verificação de vencimento do certificado. |
| `AVERBACAO_ARTIFACTS_BUCKET` | — | Bucket privado de armazenamento de objetos para artefatos de CCB e do trilho. Obrigatório quando `DATAPREV_AVERBACAO_ENABLED=true`. |
| `AVERBACAO_ARTIFACTS_ENDPOINT_URL` | — | Override de endpoint compatível com S3 para armazenamentos de objetos locais ou privados. |
| `AVERBACAO_ARTIFACTS_USE_PATH_STYLE` | `false` | Usa endereçamento S3 no estilo path quando habilitado. |
| `AWS_REGION` | — | Região usada pela custódia de credenciais e pelo armazenamento de artefatos. Deliberadamente sem padrão: um valor não definido permite que o AWS SDK resolva a própria região da instituição, e um valor fixo a sobrescreveria. Defina-a explicitamente para a região em que seus dados devem permanecer. |
| `AWS_ENDPOINT_URL` | — | Override de endpoint compatível com AWS para desenvolvimento local. Não defina em produção AWS gerenciada. |

> [!NOTE]
>
> O Consignado não tem modo de inicialização não orientado a eventos: outbox, streaming e brokers são obrigatórios, mesmo que a plataforma compartilhe essas configurações. Mantenha a origem do CloudEvent fixa em `consignado-gw`.


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