> ## 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 fazer o deploy e operar o Pix Lerian: identidade, persistência, integrações, conectividade e eventos.

Os componentes do Pix Lerian incluem o SPI, o DICT Hub, o COB Hub, a API do Pix Automático, os workers deles e o adaptador de conectividade. Esta página lista as entradas de deploy que o Pix Lerian lê. Use as tabelas para ver quais valores os componentes compartilham e quais pertencem a um único componente.

Para instalar ou atualizar o Pix Lerian, consulte o [README do chart do Pix Lerian](https://github.com/LerianStudio/helm/tree/main/charts/plugin-br-pix-lerian).

> [!NOTE]
>
> Os valores mostrados aqui são marcadores de posição. Injete credenciais e material de licença a partir do seu cofre de segredos. Nunca faça commit de segredos reais.

## Modelo de configuração

Cada componente carrega valores de bootstrap do ambiente. O SPI, o DICT Hub, o COB Hub, a API do Pix Automático e o worker DICT VSync também consomem a configuração de tempo de execução do armazenamento do Systemplane após a inicialização. O adaptador do provedor simulado lê a configuração apenas do ambiente e mantém o estado em memória.

Configure cada componente separadamente. Suas portas, seus armazenamentos e suas dependências obrigatórias são diferentes.

## Identidade e deploy compartilhados

| Variável | Componentes | Contrato |
| - | - | - |
| `APPLICATION_NAME` | Todos | Identidade do componente usada em logs, telemetria. Mantenha o valor fornecido pela configuração da release. |
| `SERVER_ADDRESS` | Todos os componentes HTTP | Endereço de escuta no formato `host:port`. A porta deve corresponder à configuração do serviço e das probes do componente. |
| `DEPLOYMENT_MODE` | Componentes de API e workers | `local`, `saas` ou `byoc`. O padrão é `local` quando o valor está ausente. |
| `REQUEST_TIMEOUT_SEC` | Componentes HTTP | Timeout por requisição, em segundos. O padrão é `30`. |
| `LICENSE_KEY` | Componentes licenciados | Obrigatório em todo modo de deploy, `local` inclusive. A chave vale para o deploy inteiro: veja o [License Manager](https://docs.lerian.studio/pt/platform/licensing/license-manager.md). Injete-a como segredo. |
| `ENV_NAME` | Todos | Nome do ambiente. Quando está em branco, o componente lê `ENV`, depois `GO_ENV`, e senão roda como `production`. |
| `SWAGGER_ENABLED` | Componentes de API | Booleano estrito. Quando não definido, a superfície OpenAPI e Scalar em tempo de execução fica ligada em `local` e `development` e desligada em todo outro ambiente. |

`PLUGIN_AUTH_ENABLED` controla a autenticação das rotas de entrada. `PLUGIN_AUTH_HOST` é o endereço base do Access Manager usado pela integração de autenticação compartilhada e pelos fluxos de credenciais de cliente OAuth. Ele deve conter somente um endereço base, sem caminho OAuth, query, fragmento ou credenciais incorporadas. Use `https://` fora do desenvolvimento local.

O adaptador do provedor simulado exige `SPI_BASE_URL`, `PROVIDER_CLIENT_ID` e `PROVIDER_CLIENT_SECRET` na inicialização. `MOCK_TEST_ENDPOINTS_ENABLED=true` ativa rotas de teste que podem forjar callbacks do provedor. O adaptador simulado não tem autorização de rota: mantenha o mock inacessível para chamadores não confiáveis, seja qual for o valor desse switch. Não configure o adaptador simulado como um trilho de produção.

## Persistência e Valkey

| Variável | Componentes | Contrato |
| - | - | - |
| `DATABASE_URL` | SPI, DICT Hub, COB Hub, API do Pix Automático e VSync | DSN do PostgreSQL para o armazenamento de negócio do componente. Ele é obrigatório quando o componente persiste dados de negócio. |
| `DATABASE_READ_REPLICA` | SPI, DICT Hub, COB Hub e API do Pix Automático | DSN opcional do PostgreSQL para uma réplica de leitura. Somente as rotas de listagem leem dela, então uma escrita recente pode faltar em uma lista por um momento. O componente abre a conexão no primeiro uso, então inicia mesmo quando a réplica está inacessível. O modo multi-tenant a ignora. |
| `SYSTEMPLANE_POSTGRES_DSN` | Consumidores do Systemplane | DSN do PostgreSQL para o armazenamento de configuração em tempo de execução. No SPI, no DICT Hub, no COB Hub e na API do Pix Automático, usa `DATABASE_URL` quando não definido. |
| `REDIS_HOST`, `REDIS_PORT`, `REDIS_USER`, `REDIS_PASSWORD`, `REDIS_DB` | Componentes de API e VSync | Configurações estruturadas da conexão com Valkey. Não as substitua pela variável aposentada `VALKEY_URL`. |
| `REDIS_TLS`, `REDIS_PROTOCOL`, `REDIS_CA_CERT` | Componentes de API e VSync | Segurança de transporte do Valkey. Um certificado privado ou autoassinado exige `REDIS_CA_CERT`; não há uma opção para ignorar a verificação. |
| `KEY_CACHE_TTL_SEC` | DICT Hub | TTL do cache de chaves Pix, em segundos. O padrão é `60`. |

O comportamento do Valkey varia por componente. SPI, DICT Hub e COB Hub podem degradar caminhos selecionados de idempotência ou cache quando você não configura o Valkey. Algumas mutações de SPI, DICT e COB falham de forma fechada com `PIX-0032` quando não existe um backstop de replay durável. O DICT VSync trata o Valkey como uma dependência obrigatória porque coordena o bloqueio de mutações entre pods. Um valor `REDIS_*` configurado, mas malformado, faz a inicialização falhar em vez de selecionar silenciosamente outro endpoint.

A implementação do Systemplane não usa `SYSTEMPLANE_SECRET_MASTER_KEY`. Proteja o acesso ao banco de dados do Systemplane, os backups e o armazenamento em disco por meio do ambiente de deploy.

## Integrações da instituição e de serviços

| Variável | Componentes | Contrato |
| - | - | - |
| `ORGANIZATION_ID` | SPI, DICT Hub, COB Hub | Organização do Midaz que os componentes usam. |
| `ISPB` | SPI, DICT Hub, COB Hub | Identificador do participante. A API valida o cabeçalho do participante ou resolve o valor da configuração do tenant. |
| `ADAPTER_BASE_URL` | SPI, DICT Hub, COB Hub, VSync | URL base do adaptador de conectividade, com o prefixo de rota. Aponte-a para o adaptador de conectividade Lerian ou, em testes de integração, para o adaptador do provedor simulado. |
| `ADAPTER_CLIENT_ID`, `ADAPTER_CLIENT_SECRET` | SPI, DICT Hub, COB Hub, VSync | Credenciais de cliente opcionais para as chamadas ao adaptador de conectividade. Quando as duas estão vazias, essas chamadas não levam o header `Authorization`. |
| `MIDAZ_BASE_URL` | SPI | URL base do Midaz para operações de onboarding e transação. O Midaz deve ter `overrides.allowFeeSkip` ligado no ledger, porque um Pix recebido nunca paga tarifa. |
| `MIDAZ_LEDGER_ID` | SPI | Identificador do ledger usado nas operações contábeis. |
| `MIDAZ_CLIENT_ID`, `MIDAZ_CLIENT_SECRET` | SPI | Credenciais do cliente OAuth para chamadas ao Midaz. |
| `CRM_BASE_URL`, `CRM_CLIENT_ID`, `CRM_CLIENT_SECRET` | SPI, DICT Hub, VSync | Integração com o CRM usada pelos fluxos que validam contas, titulares ou entradas órfãs. |
| `DICT_BASE_URL`, `DICT_CLIENT_ID`, `DICT_CLIENT_SECRET` | SPI e COB Hub | Endereço e credenciais do DICT Hub ou proxy. `DICT_ROUTING_MODE` seleciona `hub` ou `proxy`; mantenha a URL consistente com essa escolha. |
| `COB_BASE_URL`, `COB_CLIENT_ID`, `COB_CLIENT_SECRET` | SPI | Endereço e credenciais do COB Hub ou proxy. `COB_ROUTING_MODE` seleciona `hub` ou `proxy`; mantenha a URL consistente com essa escolha. |
| `SPI_BASE_URL`, `SPI_CLIENT_ID`, `SPI_CLIENT_SECRET` | DICT Hub | Endereço e credenciais do SPI usados para consultas de transferência e operações de bloqueio de saldo do MED 2.0. |
| `ANTIFRAUD_HOOK_ALLOW_PRIVATE_NETWORK` | SPI | `true` permite que a verificação de fraude chame um endereço `http` ou um endereço em uma rede privada. Use apenas em um ambiente de teste. O padrão é `false`. |

## Adaptador de conectividade Lerian

O adaptador de conectividade Lerian conecta o Pix Lerian ao [Lerian SPI](https://docs.lerian.studio/pt/rails/spi/what-is-lerian-spi.md). Ele roda em dois componentes: a API do adaptador e o seu gravador de configuração. A API do adaptador atende as suas rotas sob o prefixo `/lerian`.

O gravador de configuração copia as suas variáveis para o armazenamento de configuração de tempo de execução do adaptador na inicialização. Ele não sobrescreve um valor armazenado que difere do padrão. No modo single-tenant, a API do adaptador lê o roteamento e as credenciais desse armazenamento.

| Variável | Componente | Contrato |
| - | - | - |
| `SYSTEMPLANE_POSTGRES_DSN` | API do adaptador | DSN PostgreSQL do armazenamento de configuração de tempo de execução. A API do adaptador não inicia sem ele. |
| `DATABASE_URL` | Gravador de configuração | DSN PostgreSQL em que o gravador armazena os valores. `SYSTEMPLANE_POSTGRES_DSN` o substitui quando definido. O gravador não inicia sem um dos dois. |
| `BRSFN_SPI_BASE_URL`, `BRSFN_DICT_BASE_URL`, `BRSFN_BRCODE_BASE_URL` | Gravador de configuração | Endereços das superfícies `spi`, `dict` e `brcode` do Lerian SPI: apenas esquema, host e porta. Uma superfície sem endereço recusa as suas chamadas. Nenhuma superfície usa o endereço de outra. |
| `BRSFN_SPI_CLIENT_ID`, `BRSFN_SPI_CLIENT_SECRET` | Gravador de configuração | Credenciais de cliente OAuth da superfície `spi`. |
| `BRSFN_DICT_CLIENT_ID`, `BRSFN_DICT_CLIENT_SECRET` | Gravador de configuração | Credenciais de cliente OAuth da superfície `dict`. |
| `BRSFN_COB_CLIENT_ID`, `BRSFN_COB_CLIENT_SECRET` | Gravador de configuração | Credenciais de cliente OAuth da superfície `brcode`. |
| `PLUGIN_AUTH_HOST` | Gravador de configuração | Endereço do Access Manager. O adaptador obtém dele o token de cada par de credenciais de cliente. |
| `SPI_BASE_URL` | Gravador de configuração | Endereço completo do SPI, com o caminho `/spi`, para os callbacks de pagamento. Sem ele, o adaptador não roteia nenhuma requisição. |
| `DICT_BASE_URL`, `COB_BASE_URL`, `PIXAUTO_BASE_URL` | Gravador de configuração | Endereços completos do DICT Hub, do COB Hub e da API do Pix Automático para os seus callbacks. Inclua o caminho `/pixauto` em `PIXAUTO_BASE_URL`. Quando um deles não está definido, apenas os seus callbacks falham. |
| `SPI_CLIENT_ID`, `SPI_CLIENT_SECRET`, `DICT_CLIENT_ID`, `DICT_CLIENT_SECRET`, `COB_CLIENT_ID`, `COB_CLIENT_SECRET`, `PIXAUTO_CLIENT_ID`, `PIXAUTO_CLIENT_SECRET` | Gravador de configuração | Credenciais de cliente, um par para os callbacks de cada componente. Quando o par do SPI, do COB ou do Pix Automático está incompleto, o adaptador envia os callbacks para esse componente sem token. Sem o par completo do DICT, o adaptador recusa cada evento que deve encaminhar ao DICT Hub. |
| `DICT_CID_FILE_BASE_URL` | Gravador de configuração | Endereço da API do adaptador, com o prefixo `/lerian`, como o DICT Hub o alcança. Sem ele, o adaptador recusa cada evento de arquivo do DICT VSync. |
| `WEBHOOK_INGRESS_ENABLED` | API do adaptador | Ativa as rotas que recebem eventos do Lerian SPI, como resultados de cash-in e de liquidação. O padrão é `false`. Quando é `true`, a API do adaptador não inicia sem `REDIS_HOST`. |
| `MULTI_TENANT_URL`, `MULTI_TENANT_SERVICE_API_KEY` | Ambos | Obrigatórios quando `MULTI_TENANT_ENABLED=true`. |
| `AWS_REGION` | API do adaptador | Obrigatório quando `MULTI_TENANT_ENABLED=true`, junto com `ENV_NAME`. |

Quando uma superfície do Lerian SPI não tem um par de credenciais completo ou não há `PLUGIN_AUTH_HOST`, o adaptador não chama essa superfície. Cada rota de eventos verifica cada entrega com o segredo de assinatura da sua inscrição de eventos. O adaptador lê esses segredos da configuração de tempo de execução, não do ambiente. No modo single-tenant, quando uma inscrição tem um novo segredo de assinatura, grave esse segredo na configuração de tempo de execução pela API administrativa do gravador de configuração. Uma rota sem segredo recusa todas as entregas.

Cada variável booleana desta página aceita somente os valores exatos em minúsculas `true` e `false`. Qualquer outro valor, como `TRUE` ou `1`, interrompe o componente na inicialização.

## VSync do DICT

O worker DICT VSync concilia o estado do DICT e exige sua própria configuração de worker:

| Variável | Padrão | Contrato |
| - | - | - |
| `VSYNC_ENABLED` | `true` | Habilita o agendador do worker. |
| `VSYNC_FILE_RECON_ENABLED` | `true` | Habilita a conciliação baseada em arquivo. |
| `VSYNC_CHUNK_PROCESSING_DEADLINE_MIN` | `30` | Prazo de processamento do chunk, em minutos. |
| `VSYNC_MAX_JOB_ATTEMPTS` | `3` | Número máximo de tentativas de um job de conciliação. |
| `VSYNC_EVENTSYNC_MAX_PAGES` | `100` | Número máximo de páginas na sincronização de eventos. |
| `VSYNC_GATE_TTL_SEC` | `3600` | TTL do lease do bloqueio de mutação, em segundos. |
| `VSYNC_STUCK_JOB_SWEEP_TICK_SEC` | `120` | Intervalo entre verificações de jobs travados, em segundos. |
| `RABBITMQ_URI` | — | URI do RabbitMQ para a fila de conciliação de arquivos. Use `amqps://` fora do desenvolvimento local. |
| `RABBITMQ_ENABLED` | depende do componente | Habilita o publicador de jobs do DICT Hub. O próprio worker VSync exige sua configuração de fila. |

`VSYNC_ENABLED` e `VSYNC_FILE_RECON_ENABLED` podem ser recarregados a quente pela configuração de tempo de execução do worker. Os demais valores de ajuste são lidos na inicialização e exigem um restart.

## API do Pix Automático

A API do Pix Automático envia comandos de liquidação ao SPI e lê estas variáveis:

| Variável | Contrato |
| - | - |
| `ORGANIZATION_ID` | Organização em nome da qual o componente atua no modo single-tenant. O componente lê primeiro a configuração de tempo de execução e usa este valor apenas quando essa configuração não tem nenhum. Com `MULTI_TENANT_ENABLED=true`, o componente se recusa a iniciar se este valor estiver definido. |
| `SPI_BASE_URL` | Endereço do SPI para a liquidação do Pix Automático. Inclua o segmento de caminho `/spi` do SPI. Um valor malformado impede o componente de iniciar. |
| `SPI_CLIENT_ID`, `SPI_CLIENT_SECRET` | Credenciais de cliente para a chamada de liquidação. No modo multi-tenant, o componente resolve as credenciais por tenant e não usa estes valores. |
| `REGULATORY_DISPATCH_ENABLED` | Ativa o despachante que envia intenções regulatórias ao adaptador do provedor. O padrão é `false`. |
| `ADAPTER_BASE_URL` | Endereço do adaptador do provedor para o qual o despachante envia. O componente lê `REGULATORY_DISPATCH_BASE_URL` somente quando este valor está vazio. Quando o despacho está ativado e nenhum endereço está definido, o componente se recusa a iniciar. |
| `ADAPTER_CLIENT_ID`, `ADAPTER_CLIENT_SECRET` | Credenciais de cliente do despachante. Quando o despacho está ativado, o componente se recusa a iniciar se apenas uma delas estiver definida. Ele também se recusa a iniciar se as duas estiverem vazias e `ENV_NAME` não for `local` nem `development`. |
| `CRM_BASE_URL`, `CRM_CLIENT_ID`, `CRM_CLIENT_SECRET` | Endereço e credenciais do CRM usados para resolver a conta do pagador nas jornadas de QR code e nas solicitações da jornada 1 que não informam a conta. Quando `CRM_BASE_URL` não está definido, toda resolução responde `503` (`PIX-0814`). |

## Streaming e observabilidade

O relay do outbox de notificações é desabilitado por padrão. Para habilitá-lo, defina `STREAMING_ENABLED=true` e forneça `STREAMING_BROKERS`. A origem compartilhada de CloudEvents, quando configurada, deve identificar o serviço Pix Lerian. O componente também valida as configurações TLS/SASL do broker de streaming e a `STREAMING_DATASCHEMA_BASE_URL` opcional.

Defina `ENABLE_TELEMETRY=true` para ativar o OpenTelemetry. As variáveis `OTEL_*` configuram a telemetria. Consulte [Configuração BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md) para a telemetria compartilhada e os parâmetros de transporte do broker.

## Saúde e readiness

A API SPI expõe `/health` e `/readyz` no listener principal, sob seu prefixo de rota. A prontidão verifica o PostgreSQL e a configuração obrigatória. As verificações configuradas do adaptador e do Midaz são reportadas sem afetar a prontidão.


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