> ## 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 ambiente para implantar e operar o Pix Lerian: identidade, bancos de dados, integrações, conectividade e eventos.
O Pix Lerian é formado pelos domínios SPI, DICT e COB e pelo adaptador de conectividade. A equipe de DevOps define seu comportamento por variáveis de ambiente no momento do deploy. Esta página cobre as variáveis **distintivas desta interface**. Para os parâmetros compartilhados de servidor, telemetria, autenticação, streaming e service discovery, consulte a [referência de configuração BYOC](/pt/reference/byoc-configuration).
Nas tabelas abaixo, a coluna **Padrão / Obrigatória** mostra o valor padrão. Um qualificador em negrito marca uma variável que você deve definir no contexto descrito. `—` significa que não há padrão. `🔒` marca um **segredo** — injete-o no momento do deploy a partir do seu secret store e nunca faça commit dele.
## Como o `values.yaml` e o Systemplane se relacionam
Na implantação inicial, o cliente fornece a configuração pelo `values.yaml` do Helm chart entregue. Depois da inicialização, as chaves de runtime passam a ser administradas pelo Systemplane.
O chart transforma os values em variáveis de ambiente do pod:
| Tipo | Local no `values.yaml` | Comportamento |
| --------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Configuração de implantação | `.configmap.` | O Helm renderiza a configuração e o Deployment injeta as chaves como envs. |
| Segredo | Configuração de Secret do componente | Injete o valor durante o deploy a partir do secret store e nunca o versione. |
| Seed de runtime | `spiSystemplane`, `dictSystemplane` ou `cobSystemplane` | Configure a variável no bloco do Systemplane que pertence ao domínio. O componente usa esse valor para inicializar a configuração de runtime. |
Cada domínio possui um componente dedicado de Systemplane. O fluxo é:
O Helm cria o ConfigMap e referencia o Secret de cada componente. O Deployment carrega ambos com `envFrom` quando o pod inicia.
O componente do Systemplane lê as envs mapeadas e aplica um seed apenas quando o valor armazenado ainda corresponde ao padrão registrado. Um override administrativo existente não é sobrescrito.
APIs e workers do domínio leem o store do Systemplane. A definição de cada chave determina se ela aceita atualização em runtime ou se exige restart.
Para envs de bootstrap, altere o `values.yaml`, execute o upgrade e faça o rollout do componente. Depois da inicialização, altere as chaves de runtime pelo Systemplane; mudar somente o `values.yaml` não substitui um override já gravado.
* **Env direta de bootstrap:** `APPLICATION_NAME`, `SERVER_ADDRESS`, `DATABASE_URL`, `SYSTEMPLANE_POSTGRES_DSN`, `SYSTEMPLANE_SECRET_MASTER_KEY`, `VALKEY_URL`, `LICENSE_KEY`, `ORGANIZATION_IDS`, `SWAGGER_ENABLED`, `RABBITMQ_ENABLED`, `RABBITMQ_URI` e `STREAMING_*`.
* **Também usadas como seed do Systemplane:** `DEPLOYMENT_MODE`, `REQUEST_TIMEOUT_SEC`, `PLUGIN_AUTH_*`, `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `MIDAZ_*`, `CRM_*`, `DICT_*`, `COB_*`, `SPI_*`, `KEY_CACHE_TTL_SEC` e `VSYNC_*`.
Defina os seeds no bloco do Systemplane que pertence ao domínio, e não no bloco da API ou do worker. As chaves sensíveis continuam marcadas com `🔒` nas tabelas abaixo.
| Bloco do chart | Seeds específicos do domínio |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `spiSystemplane` | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `MIDAZ_*`, `CRM_*`, `DICT_*` e `COB_*`. |
| `dictSystemplane` | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `CRM_*`, `SPI_*`, `KEY_CACHE_TTL_SEC` e `VSYNC_*`. |
| `cobSystemplane` | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `DICT_BASE_URL`, `DICT_CLIENT_ID`, `DICT_CLIENT_SECRET` e `DICT_ROUTING_MODE`. |
Os três blocos também recebem os seeds compartilhados `DEPLOYMENT_MODE`, `REQUEST_TIMEOUT_SEC` e `PLUGIN_AUTH_*`.
O Pix Lerian não expõe descoberta de catálogo. Use esta página como referência das chaves suportadas e consulte [Systemplane](/pt/reference/systemplane/overview) para o modelo de autorização e atualização de runtime.
## Servidor e modo de implantação
Cada componente recebe `SERVER_ADDRESS` por `.configmap.SERVER_ADDRESS`; o valor deve coincidir com `.service.port` no mesmo `values.yaml`. As probes de liveness e readiness usam essa porta. Consulte [Servidor](/pt/reference/byoc-configuration#servidor) e [Saúde e prontidão](/pt/reference/health-and-readiness).
| Variável | Padrão / Obrigatória | Descrição |
| --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `APPLICATION_NAME` | Definida pelo chart | Identidade do componente usada em licenciamento, logs e telemetria. Não sobrescreva o valor fornecido pelo chart. |
| `SERVER_ADDRESS` | Definida pelo chart | Endereço HTTP de escuta no formato `host:port`; deve coincidir com o `targetPort` do componente. |
| `DEPLOYMENT_MODE` | `byoc` | Modo das implantações entregues ao cliente. Mantenha o valor definido pelo chart. |
| `REQUEST_TIMEOUT_SEC` | `30` | Timeout padrão das requisições HTTP, em segundos. |
| `PLUGIN_AUTH_ENABLED` | `false` | Exige autenticação do Access Manager nas rotas protegidas. Ative em produção. |
| `PLUGIN_AUTH_URL` | **Obrigatória com autenticação ou M2M** | URL base do Access Manager usada pela autenticação de entrada e pelos clientes OAuth entre componentes. |
| `LICENSE_KEY` | 🔒 **Obrigatória em BYOC** | Chave de licença do Pix Lerian. |
| `ORGANIZATION_IDS` | **Obrigatória quando `LICENSE_KEY` estiver definida** | Escopo da licença: `global` ou lista de organizações separadas por vírgula. Use exatamente este nome; `LICENSE_ORGANIZATION_IDS` não é lida pelos binários atuais. |
| `SWAGGER_ENABLED` | Ativado fora de produção | Controla a especificação OpenAPI e a interface de exploração servidas pelo componente. |
## Persistência e configuração de runtime
SPI, DICT, COB e o adaptador mantêm stores separados. Não reutilize o mesmo banco lógico entre domínios.
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DATABASE_URL` | 🔒 **Obrigatória para componentes com persistência** | DSN PostgreSQL do componente, usada pelos serviços que persistem dados de negócio e pelos componentes de configuração. |
| `SYSTEMPLANE_POSTGRES_DSN` | 🔒 `DATABASE_URL` em SPI, DICT e COB | DSN dedicado para ler a configuração de runtime. Use o valor renderizado pelo chart do componente. |
| `SYSTEMPLANE_SECRET_MASTER_KEY` | 🔒 **Obrigatória em BYOC** | Chave AES-256-GCM de 32 bytes usada para criptografar valores secretos no store de configuração. |
| `VALKEY_URL` | 🔒 — | URL do Valkey/Redis usada por idempotência, deduplicação e cache. Alguns fluxos degradam ou falham de forma segura quando ela não está definida. |
| `KEY_CACHE_TTL_SEC` | `60` | TTL, em segundos, do cache de consultas de chaves no DICT. |
Valores de identidade, URLs e credenciais declarados nos componentes de configuração são usados como **seed apenas na primeira inicialização**. Depois que uma chave existe no store de runtime, reiniciar o serviço não sobrescreve o valor. Alterações posteriores devem ser feitas pelo plano autenticado de configuração.
## Identidade da instituição
| Variável | Padrão / Obrigatória | Descrição |
| ------------------ | ----------------------------------------- | ----------------------------------------------------------------- |
| `ORGANIZATION_ID` | **Obrigatória em BYOC** | UUID da organização Midaz usada por SPI, DICT e COB. |
| `ISPB` | **Obrigatória em BYOC** | Identificador de oito dígitos da instituição participante. |
| `ADAPTER_BASE_URL` | **Obrigatória para os fluxos conectados** | URL base do adaptador de conectividade usada por SPI, DICT e COB. |
## Midaz e CRM
O SPI usa o Midaz para contabilização. SPI e DICT usam o CRM para validar contas e titulares nos fluxos que exigem essa informação.
| Variável | Padrão / Obrigatória | Descrição |
| --------------------- | --------------------------------------- | ---------------------------------------------------------------------- |
| `MIDAZ_BASE_URL` | **Obrigatória para contabilização** | URL base compartilhada pelas APIs de onboarding e transações do Midaz. |
| `MIDAZ_LEDGER_ID` | **Obrigatória para contabilização** | UUID do ledger que registra as operações Pix. |
| `MIDAZ_CLIENT_ID` | **Obrigatória com autenticação** | OAuth client ID usado pelo SPI para chamar o Midaz. |
| `MIDAZ_CLIENT_SECRET` | 🔒 **Obrigatória com autenticação** | OAuth client secret usado pelo SPI para chamar o Midaz. |
| `CRM_BASE_URL` | **Obrigatória nos fluxos de validação** | URL base do CRM. |
| `CRM_CLIENT_ID` | **Obrigatória com autenticação** | OAuth client ID usado por SPI e DICT para chamar o CRM. |
| `CRM_CLIENT_SECRET` | 🔒 **Obrigatória com autenticação** | OAuth client secret usado por SPI e DICT para chamar o CRM. |
## Integrações entre os domínios
As URLs abaixo apontam para os componentes implantados do próprio Pix Lerian. Elas definem a comunicação entre SPI, DICT, COB e o adaptador, sem alterar o contrato consumido pela aplicação cliente.
| Variável | Padrão / Obrigatória | Descrição |
| -------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `DICT_BASE_URL` | **Obrigatória nos componentes que consultam DICT** | URL base do domínio DICT. Usada por SPI, COB e pelo adaptador. |
| `DICT_CLIENT_ID` | **Obrigatória com autenticação** | OAuth client ID para chamadas ao DICT. |
| `DICT_CLIENT_SECRET` | 🔒 **Obrigatória com autenticação** | OAuth client secret para chamadas ao DICT. |
| `DICT_ROUTING_MODE` | `hub` | Tier de descoberta do DICT: `hub` ou `proxy`. A URL configurada deve apontar para o mesmo tier. |
| `COB_BASE_URL` | **Obrigatória nos componentes que consultam COB** | URL base do domínio COB. Usada pelo SPI e pelo adaptador. |
| `COB_CLIENT_ID` | **Obrigatória com autenticação** | OAuth client ID para chamadas ao COB. |
| `COB_CLIENT_SECRET` | 🔒 **Obrigatória com autenticação** | OAuth client secret para chamadas ao COB. |
| `COB_ROUTING_MODE` | `hub` | Tier de descoberta do COB: `hub` ou `proxy`. A URL configurada deve apontar para o mesmo tier. |
| `SPI_BASE_URL` | **Obrigatória nos componentes que consultam SPI** | URL base do domínio SPI. Usada pelo DICT e pelo adaptador. |
| `SPI_CLIENT_ID` | **Obrigatória com autenticação** | OAuth client ID para chamadas ao SPI. |
| `SPI_CLIENT_SECRET` | 🔒 **Obrigatória com autenticação** | OAuth client secret para chamadas ao SPI. |
## Reconciliação do DICT (VSync)
O worker VSync reconcilia a base persistida do DICT com a fonte regulatória. O transporte RabbitMQ é habilitado por padrão; quando ativo, exige uma URI válida.
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- |
| `VSYNC_ENABLED` | `true` | Ativa o worker de reconciliação. |
| `VSYNC_FILE_RECON_ENABLED` | `true` | Ativa a reconciliação baseada em arquivo. |
| `RABBITMQ_ENABLED` | `true` | Ativa o transporte RabbitMQ do VSync. |
| `RABBITMQ_URI` | 🔒 **Obrigatória quando `RABBITMQ_ENABLED=true`** | URI de conexão com o RabbitMQ. Use `amqps://` em produção. |
| `VSYNC_CHUNK_CONSUMER_WORKERS` | `3` | Número de consumidores paralelos de chunks. |
| `VSYNC_JOBS_CONSUMER_WORKERS` | `3` | Número de consumidores paralelos de jobs. |
| `VSYNC_STUCK_JOB_SWEEP_TICK_SEC` | `120` | Intervalo, em segundos, da varredura de jobs travados. |
| `VSYNC_CHUNK_PROCESSING_DEADLINE_MIN` | `30` | Prazo, em minutos, para considerar um chunk travado. |
| `VSYNC_MAX_JOB_ATTEMPTS` | `3` | Máximo de tentativas de um job de reconciliação. |
| `VSYNC_EVENTSYNC_MAX_PAGES` | `100` | Limite de páginas processadas por ciclo de sincronização de eventos. |
| `VSYNC_GATE_TTL_SEC` | `3600` | TTL, em segundos, do bloqueio que protege mutações durante a reconciliação. |
## Streaming e observabilidade
A publicação de CloudEvents do SPI, DICT e COB usa a família `STREAMING_*` e permanece desativada por padrão. Quando `STREAMING_ENABLED=true`, `STREAMING_BROKERS` é obrigatória. Se você definir `STREAMING_CLOUDEVENTS_SOURCE`, o único valor aceito é `plugin-br-pix-lerian`. Consulte [Streaming e outbox](/pt/reference/byoc-configuration#streaming-e-outbox) e [Observabilidade](/pt/reference/byoc-configuration#observabilidade) para os demais parâmetros de broker, TLS, SASL e OpenTelemetry.
## Fonte de configuração de bootstrap
O `values.yaml` do Helm chart entregue é a fonte de bootstrap da implantação. Mantenha o arquivo alinhado à versão do chart e preserve os nomes dos blocos e das variáveis. Injete segredos a partir do secret store e não armazene credenciais em texto aberto no repositório. Após o seed, use o Systemplane para alterar chaves de runtime.
## Saúde e readiness
Configure as probes pelos campos `.livenessProbe.path` e `.readinessProbe.path` do `values.yaml`. Os paths padrão variam por componente; não assuma `/health` e `/readyz` sem prefixo.
A liveness probe verifica se o processo está ativo. A readiness probe verifica se as dependências e as configurações obrigatórias permitem receber tráfego. Não direcione tráfego para um componente enquanto a readiness probe não retornar sucesso.