> ## 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 de deploy do Lerian CCS: postura de runtime, armazenamentos de dados, os upstreams STA e Reporter, chaves de criptografia e configurações regulatórias.

O Lerian CCS lê sua configuração a partir do ambiente do processo na inicialização. Você define essas variáveis no momento do deploy. Um reinício do serviço as torna efetivas. A [referência de configuração do BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md) documenta a base que todo serviço Go da Lerian compartilha.

Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor que o serviço aplica quando você deixa a variável sem definir. Um qualificador em negrito marca uma variável que você deve definir, como **Obrigatório** ou **Obrigatório em produção**. `—` significa que o serviço não aplica nenhum padrão. Uma variável marcada com `Sensitive.` carrega material de credencial ou de chave. Injete-a a partir do seu gerenciador de segredos no momento do deploy. Nunca faça commit de um valor.

Quando um valor no arquivo de exemplo publicado difere do valor que o código aplica, esta página publica o valor do código.

## Serviço e runtime

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `APPLICATION_NAME` | Nome do serviço | Nome do processo da aplicação que aparece nos logs e na telemetria. |
| `ENV_NAME` | `—` | Rótulo do ambiente de deploy, convertido para minúsculas. O valor `production` ativa todos os gates de produção desta página. |
| `LOG_LEVEL` | `info` | Nível do logger estruturado: `debug`, `info`, `warn` ou `error`. |
| `DEPLOYMENT_MODE` | `local` | Postura operacional: `local`, `byoc` ou `saas`. Outro valor interrompe o boot. |
| `CCS_RUN_MODE` | `all` | Seleciona os subsistemas que este processo executa: `manager` apenas para a API HTTP, `worker` apenas para os workers em segundo plano, ou `all` para ambos. Um valor inválido interrompe o boot. |
| `SERVER_ADDRESS` | `—` | Endereço HTTP principal de escuta. Um valor não definido faz o servidor se vincular a uma porta atribuída pelo sistema operacional, então os deploys o definem. |
| `HTTP_BODY_LIMIT_BYTES` | `104857600` | Tamanho máximo do corpo da requisição de entrada, em bytes. |
| `DEFAULT_TENANT_ID` | `—` | Identificador de tenant de fallback para caminhos sem contexto de tenant por requisição. |
| `MIGRATIONS_PATH` | `—` | Caminho no sistema de arquivos para os arquivos de migração SQL. Os binários de migração o leem diretamente. O serviço nunca aplica as migrações por conta própria. |
| `INFRA_CONNECT_TIMEOUT_SEC` | `30` | Orçamento geral de dial de infraestrutura, em segundos. O serviço limita um valor igual ou menor que zero a 30 segundos. |

## Licença

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `LICENSE_KEY` | **Obrigatório** | Credencial de licença emitida pela Lerian. `Sensitive.` |
| `ORGANIZATION_IDS` | **Obrigatório** | Escopo de organização que a licença cobre. O Lerian CCS executa a biblioteca de licenças em modo global, então o valor é o literal `global`. |

## CORS, TLS e proxies

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `CORS_ALLOWED_ORIGINS` | **Obrigatório em produção** | Lista separada por vírgulas das origens de navegador permitidas. Um boot em produção recusa uma lista vazia e recusa um curinga. |
| `CORS_ALLOWED_METHODS` | `—` | Lista separada por vírgulas dos métodos HTTP permitidos. |
| `CORS_ALLOWED_HEADERS` | `—` | Lista separada por vírgulas dos headers de requisição permitidos. |
| `CORS_EXPOSE_HEADERS` | `—` | Lista separada por vírgulas dos headers de resposta que o navegador pode ler. |
| `CORS_ALLOW_CREDENTIALS` | `false` | Permite requisições cross-origin com credenciais. |
| `ALLOW_CORS_WILDCARD` | `false` | Vale quando `CORS_ALLOWED_ORIGINS` está vazio ou é `*`: `true` permite qualquer origem sem credenciais, e `false` recusa toda requisição cross-origin. |
| `SERVER_TLS_CERT_FILE` | `—` | Caminho para o certificado TLS quando o serviço encerra o TLS por conta própria. Defina-o junto com o arquivo de chave. |
| `SERVER_TLS_KEY_FILE` | `—` | Caminho para a chave privada TLS. Defina-o junto com o arquivo de certificado. |
| `TLS_TERMINATED_UPSTREAM` | `false` | Marca o caminho da requisição como tendo o TLS encerrado por um proxy na frente do serviço. |
| `TRUSTED_PROXIES` | **Obrigatório em produção** | Faixas CIDR separadas por vírgulas dos proxies de camada 7 cujo header `X-Forwarded-For` o serviço respeita. Um boot em produção recusa uma lista vazia e recusa uma faixa curinga. |

## PostgreSQL

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `POSTGRES_HOST` | `—` | Host do banco de dados principal. A identidade de conexão não carrega padrões, então um bloco incompleto falha o dial no boot. |
| `POSTGRES_PORT` | `—` | Porta do banco de dados principal. |
| `POSTGRES_USER` | `—` | Usuário do banco de dados principal. |
| `POSTGRES_PASSWORD` | **Obrigatório em produção** | Senha do banco de dados principal. `Sensitive.` |
| `POSTGRES_NAME` | `—` | Nome do banco de dados principal. |
| `POSTGRES_SSLMODE` | **Obrigatório** | Modo TLS do banco de dados principal. Um boot em produção recusa o valor `disable`. |
| `POSTGRES_REPLICA_HOST` | `—` | Host da réplica de leitura para escalar consultas. Os outros campos da réplica usam o valor do principal quando não estão definidos. |
| `POSTGRES_REPLICA_PORT` | `—` | Porta da réplica de leitura. |
| `POSTGRES_REPLICA_USER` | `—` | Usuário da réplica de leitura. |
| `POSTGRES_REPLICA_PASSWORD` | `—` | Senha da réplica de leitura. `Sensitive.` |
| `POSTGRES_REPLICA_NAME` | `—` | Nome do banco de dados da réplica de leitura. |
| `POSTGRES_REPLICA_SSLMODE` | `—` | Modo TLS da réplica de leitura. Um boot em produção recusa o valor `disable`. |
| `POSTGRES_MAX_OPEN_CONNS` | `25` | Máximo de conexões abertas por pool. |
| `POSTGRES_MAX_IDLE_CONNS` | `—` | Máximo de conexões ociosas por pool. O serviço não aplica nenhum padrão aqui. |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | `30` | Tempo de vida máximo da conexão, em minutos. |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | `5` | Tempo máximo de ociosidade da conexão, em minutos. |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | `—` | Timeout de dial, em segundos. |
| `POSTGRES_POOL_FANOUT_ACK` | `—` | Consentimento do operador para exceder o fan-out seguro de conexões entre os pools de conexão. Aceita `true`, `1`, `yes` ou `on`. Sem ele, o boot recusa um fan-out excessivo. |

## Redis

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `REDIS_HOST` | `localhost:6379` | Endereço do Redis como `host:port`. Um valor não vazio também ativa o gate de postura TLS no modo `saas`. |
| `REDIS_MASTER_NAME` | `—` | Nome do master do Sentinel quando o deploy usa Redis Sentinel. |
| `REDIS_PASSWORD` | `—` | Senha do Redis. `Sensitive.` |
| `REDIS_DB` | `0` | Número do banco de dados lógico do Redis. |
| `REDIS_PROTOCOL` | `3` | Versão do protocolo de rede do Redis. |
| `REDIS_TLS` | `false` | Ativa o TLS para o cliente Redis. |
| `REDIS_CA_CERT` | `—` | Autoridade certificadora em PEM codificado em Base64 para o handshake do Redis. O cliente só a lê quando `REDIS_TLS=true`. |
| `REDIS_POOL_SIZE` | `10` | Tamanho máximo do pool do Redis. O cliente limita um valor acima de 1000. |
| `REDIS_MIN_IDLE_CONNS` | `—` | Mínimo de conexões ociosas do Redis mantidas aquecidas. O cliente não pré-aquece nenhuma por padrão. |
| `REDIS_READ_TIMEOUT` | `3` | Timeout de leitura do Redis, em segundos. |
| `REDIS_WRITE_TIMEOUT` | `3` | Timeout de escrita do Redis, em segundos. |
| `REDIS_DIAL_TIMEOUT` | `5` | Timeout de dial do Redis, em segundos. |
| `REDIS_POOL_TIMEOUT` | `2` | Timeout de checkout do pool do Redis, em segundos. |
| `REDIS_MAX_RETRIES` | `3` | Orçamento de novas tentativas de comando do Redis. |
| `REDIS_MIN_RETRY_BACKOFF` | `8` | Backoff mínimo de nova tentativa do Redis, em milissegundos. |
| `REDIS_MAX_RETRY_BACKOFF` | `1` | Backoff máximo de nova tentativa do Redis, em segundos. |

## Mensageria e circuit breaker

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `CIRCUIT_BREAKER_ENABLED` | `false` (**Obrigatório** como `true`) | Conecta o gerenciador de circuit breaker. A integração com o Reporter e os adaptadores de armazenamento de objetos precisam dele, então o boot recusa um valor `false`. |
| `RABBITMQ_ENABLED` | `false` | Ativa a conexão com o message broker. |
| `RABBITMQ_URL` | `—` | URL completa de conexão com o broker. `Sensitive.` Defina esta variável ou o host, porque o boot recusa ambos vazios quando o broker está ativado. |
| `RABBITMQ_HOST` | `—` | Host do broker. |
| `RABBITMQ_PORT_AMQP` | `—` | Porta de mensagens do broker. |
| `RABBITMQ_DEFAULT_USER` | `—` | Nome de usuário do broker. |
| `RABBITMQ_DEFAULT_PASS` | `—` | Senha do broker. `Sensitive.` |
| `RABBITMQ_VHOST` | `—` | Host virtual do broker. |
| `RABBITMQ_QUEUE` | `—` | Nome da fila padrão. |
| `RABBITMQ_EXCHANGE` | **Obrigatório** com o broker ativo | Exchange dos eventos de negócio. O serviço o declara no broker, que recusa um nome vazio. |
| `RABBITMQ_HEALTH_CHECK_URL` | `—` | Endpoint HTTP que a probe de readiness chama para verificar o broker. |
| `RABBITMQ_HEALTH_CHECK_ALLOWED_HOSTS` | `—` | Lista de permissão separada por vírgulas dos hosts que a probe de health pode ter como alvo. |
| `RABBITMQ_REQUIRE_HEALTH_ALLOWED_HOSTS` | `false` | Força a lista de permissão da probe de health a ser não vazia. |
| `RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK` | `false` | `true` permite que o health check do broker envie as credenciais do broker a um `RABBITMQ_HEALTH_CHECK_URL` `http://`, e limita o check apenas por `RABBITMQ_HEALTH_CHECK_ALLOWED_HOSTS`. Um boot em produção recusa `true`. |
| `RABBITMQ_PUBLISHER_CONFIRM_TIMEOUT_MS` | `5000` | Timeout de confirmação do publisher, em milissegundos. |
| `RABBITMQ_PUBLISHER_RECOVERY_INITIAL_MS` | `1000` | Primeiro backoff de recuperação do publisher, em milissegundos. |
| `RABBITMQ_PUBLISHER_RECOVERY_MAX_MS` | `30000` | Backoff máximo de recuperação do publisher, em milissegundos. |
| `RABBITMQ_PUBLISHER_MAX_RECOVERIES` | `10` | Máximo de tentativas de recuperação do publisher antes que ele desista. |
| `CCS_CONSUMER_MAX_REDELIVERIES` | `5` | Máximo de ciclos de nova tentativa que uma mensagem com falha transitória pode ter antes que o consumidor a mova para a dead-letter queue terminal. |

## Outbox

O Lerian CCS grava o trabalho de saída em um outbox transacional, na mesma transação de banco de dados da mudança de estado. A família `OUTBOX_` abaixo configura o dispatcher que a biblioteca de plataforma compartilhada executa.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `OUTBOX_ENABLED` | `false` (**Obrigatório** como `true`) | Ativa o worker do outbox. A integração com o Reporter o exige, então o boot recusa `false`. |
| `OUTBOX_TABLE_NAME` | `—` | Nome da tabela do outbox. O boot recusa um valor vazio quando o outbox está ativado. |
| `OUTBOX_DISPATCH_INTERVAL_SEC` | `2` | Intervalo em segundos entre os ciclos de dispatch. |
| `OUTBOX_BATCH_SIZE` | `50` | Máximo de eventos drenados por ciclo de dispatch. |
| `OUTBOX_PUBLISH_MAX_ATTEMPTS` | `3` | Máximo de tentativas de publicação por evento dentro de um ciclo. |
| `OUTBOX_PUBLISH_BACKOFF_MS` | `200` | Backoff de nova tentativa de publicação, em milissegundos. |
| `OUTBOX_RETRY_WINDOW_SEC` | `300` | Idade mínima em segundos antes que um evento com falha fique elegível para uma nova tentativa. |
| `OUTBOX_MAX_DISPATCH_ATTEMPTS` | `10` | Máximo de tentativas de dispatch por evento antes que o dispatcher pare de tentar novamente. |
| `OUTBOX_PROCESSING_TIMEOUT_SEC` | `600` | Timeout em segundos após o qual o dispatcher recupera um evento travado. |
| `OUTBOX_MAX_FAILED_PER_BATCH` | `25` | Máximo de eventos com falha que o dispatcher recupera para uma nova tentativa em um ciclo. |
| `OUTBOX_INCLUDE_TENANT_METRICS` | `false` | Adiciona labels por tenant às métricas do outbox. |
| `OUTBOX_PRIORITY_EVENT_TYPES` | `—` | Tipos de evento separados por vírgulas que o dispatcher envia primeiro. |
| `OUTBOX_ALLOW_EMPTY_TENANT` | `false` | Aceita um evento sem contexto de tenant. |

## Overrides de outbox do CCS

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `CCS_OUTBOX_OVERRIDES_ENABLED` | `false` | Aplica os três overrides abaixo. Enquanto for `false`, o serviço os ignora. |
| `CCS_OUTBOX_DISPATCH_INTERVAL_MS` | `1000` | Intervalo de dispatch em milissegundos. Ele tem precedência sobre o intervalo baseado em segundos, o que preserva a precisão de sub-segundo. |
| `CCS_OUTBOX_BATCH_SIZE` | `50` | Máximo de eventos que os handlers registrados processam por ciclo. |
| `CCS_OUTBOX_MAX_ATTEMPTS` | `10` | Máximo de tentativas de dispatch antes que o dispatcher marque um evento como permanentemente não entregável. |

## Streaming

A biblioteca de streaming da Lerian lê a família `STREAMING_`, não a configuração do serviço. O [Lerian Streaming Hub](https://docs.lerian.studio/pt/platform/streaming-hub/what-is-streaming-hub.md) entrega os eventos publicados.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `STREAMING_ENABLED` | `false` | Chave mestra para a emissão de eventos de negócio. Enquanto estiver desativada, o serviço conecta um emissor no-operation e não publica nada. Ela também exige `OUTBOX_ENABLED=true`. |
| `STREAMING_BROKERS` | **Obrigatório** quando o streaming está ativado | Lista de bootstrap de brokers separada por vírgulas. Uma configuração ativada com uma lista vazia recusa o boot. |
| `STREAMING_CLOUDEVENTS_SOURCE` | Fixo | A fonte CloudEvents deste serviço. Ela define o namespace do tópico e o prefixo do tipo de evento. Deixe-a sem definir. Qualquer valor diferente da fonte embutida recusa o boot, mesmo quando o streaming está desativado. |
| `STREAMING_CLIENT_ID` | O nome de destino do serviço | Identificador de cliente do broker usado para diagnósticos do lado do broker. |
| `STREAMING_CB_FAILURE_RATIO` | `0.5` | Proporção de falhas que abre o circuit breaker do produtor. |
| `STREAMING_CB_MIN_REQUESTS` | `10` | Mínimo de requisições antes que o circuit breaker do produtor avalie a proporção de falhas. |
| `STREAMING_CB_TIMEOUT_S` | `30` | Tempo de resfriamento no estado aberto, em segundos, para o circuit breaker do produtor. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Janela máxima de drenagem e flush, em segundos, quando o produtor encerra. |
| `STREAMING_TLS_ENABLED` | `false` (**Obrigatório** como `true` em `saas`) | Ativa o TLS para o dial do broker. A versão mínima é TLS 1.2. No modo `saas`, um dial de broker em texto claro recusa o boot. |
| `STREAMING_TLS_CA_CERT` | `—` | Autoridade certificadora PEM codificada em base64 para um broker privado ou on-premises. Um valor vazio usa o trust store do host. Um valor malformado recusa o boot. |
| `STREAMING_SASL_MECHANISM` | `—` | Mecanismo de autenticação do broker: `PLAIN`, `SCRAM-SHA-256` ou `SCRAM-SHA-512`. Um valor vazio desativa a autenticação do broker. Um mecanismo sem suas credenciais recusa o boot. |
| `STREAMING_SASL_USERNAME` | `—` | Nome de usuário de autenticação do broker. |
| `STREAMING_SASL_PASSWORD` | `—` | Senha de autenticação do broker. `Sensitive.` |
| `STREAMING_SASL_ALLOW_PLAINTEXT` | `false` | Permite a autenticação do broker por uma conexão em texto claro, o que envia as credenciais sem criptografia. O serviço recusa essa combinação a menos que você defina essa flag. |

## Integração com o STA

O Lerian CCS envia todo arquivo de saída ao BACEN por meio do [Lerian STA](https://docs.lerian.studio/pt/rails/sta/what-is-lerian-sta.md) e recebe as respostas de volta por ele.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `STA_ENABLED` | `false` | Conecta o cliente STA, o handler de submissão e a probe de readiness do STA. Também exige `STA_BASE_URL`, `CIRCUIT_BREAKER_ENABLED=true` e `OUTBOX_ENABLED=true`. |
| `STA_BASE_URL` | **Obrigatório** quando o STA está ativado | URL base do serviço STA. Um valor vazio recusa o boot. |
| `STA_HTTP_TIMEOUT_SEC` | `30` | Timeout por requisição, em segundos, no cliente STA. O serviço recorre a 30 segundos para um valor igual ou menor que zero. |
| `STA_FILE_HASH_VERIFY_ENABLED` | `false` | Verifica o digest SHA-256 de um arquivo de entrada baixado em relação ao digest no evento do arquivo. |
| `STA_EVENT_HMAC_VERIFY_ENABLED` | `false` | Autentica os eventos de negócio de entrada do STA em relação ao esquema de assinatura compartilhado. Um boot com a verificação ativada e um catálogo de chaves incompleto falha de forma explícita. |
| `STA_EVENT_HMAC_MASTER_KEYS` | `—` | Catálogo de chaves mestras `version:hex` compartilhadas com o serviço STA. `Sensitive.` |
| `STA_EVENT_HMAC_MASTER_KEY_VERSION` | `—` | Versão do catálogo que o verificador trata como ativa. |
| `STA_EVENT_HMAC_TOLERANCE_SECONDS` | `300` | Janela, em segundos, fora da qual um evento autêntico é registrado em log como atrasado ou adiantado. |

## Integração com o Reporter

O Lerian Reporter renderiza o arquivo ACCS001 diário, então é um upstream obrigatório. No CCS 1.0.0, a probe de readiness o trata como uma dependência rígida. Inicie o Lerian Reporter antes de esperar que o Lerian CCS fique pronto.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `REPORTER_URL` | **Obrigatório** | URL base do serviço Reporter. Um valor vazio recusa o boot. |
| `REPORTER_HTTP_TIMEOUT_SEC` | `30` | Timeout por requisição, em segundos, no cliente Reporter. O serviço recorre a 30 segundos para um valor igual ou menor que zero. |
| `REPORTER_TEMPLATE_ID_ACCS001` | `—` | Identificador do template do Reporter que a renderização do ACCS001 tem como alvo. O Reporter gera esse identificador por ambiente quando você registra o template. Um identificador vazio junto com um nome de template vazio recusa a aprovação do lote com o erro `MYS-0008` e HTTP 503. |
| `REPORTER_TEMPLATE_NAME_ACCS001` | `—` | Descrição do template ACCS001 no Reporter. O serviço resolve o template por essa descrição quando você deixa o identificador sem definir. |
| `DETAIL_RENDER_MODE` | `inline` | Caminho de renderização para uma resposta de detalhamento. Apenas `inline` inicia o serviço. Qualquer outro valor recusa o boot. |
| `CCS_REPORTER_POLL_INITIAL_DELAY_MS` | `2000` | Primeiro atraso de backoff, em milissegundos, no loop de poll de renderização. |
| `CCS_REPORTER_POLL_MAX_DELAY_MS` | `30000` | Atraso máximo de backoff, em milissegundos, no loop de poll de renderização. |
| `CCS_REPORTER_POLL_TOTAL_TIMEOUT_SEC` | `1800` | Orçamento total de poll, em segundos. Uma renderização mais antiga que esse orçamento termina como timeout. |
| `CCS_REPORTER_POLL_BACKOFF_MULTIPLIER` | `2.0` | Multiplicador aplicado ao atraso após cada poll. O boot recusa um valor abaixo de `1.0`. |

## Autenticação

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | **Obrigatório**: `true` ou `false`. Um valor vazio ou outro valor interrompe o boot. Um `ENV_NAME` de desenvolvimento é `development`, `develop`, `dev`, `local` ou `test` | `true` envia cada requisição `/v1` protegida por gate ao Lerian Access Manager para uma decisão. `false` pula essa chamada; um bearer token que nomeia um principal continua obrigatório. Só um `ENV_NAME` de desenvolvimento fora de `saas` aceita `false`. O valor também decide se o serviço emite tokens de saída. |
| `PLUGIN_AUTH_HOST` | **Obrigatório** quando a autenticação está ativada | URL base do [Lerian Access Manager](https://docs.lerian.studio/pt/platform/access-manager.md). |
| `AUTH_JWT_VERIFY_CERT` | `—` | Uma ou mais chaves públicas RSA ou certificados X.509 em PEM, separados por quebras de linha. Com um certificado carregado, o serviço verifica a assinatura RS256 e a expiração de cada bearer token antes de chamar o Access Manager, e responde 401 quando a verificação falha. Tem precedência sobre `AUTH_JWT_VERIFY_CERT_PATH`. Só tem efeito com `PLUGIN_AUTH_ENABLED=true`. |
| `AUTH_JWT_VERIFY_CERT_PATH` | `—` | Caminho de um arquivo com o mesmo conteúdo. O serviço o lê apenas quando `AUTH_JWT_VERIFY_CERT` está vazia. |
| `AUTH_JWT_ISSUER` | `—` | Com um certificado carregado, o serviço responde 401 a todo token cuja claim `iss` difere deste valor. |

## Credenciais machine-to-machine

O Lerian CCS emite um token de saída por upstream por meio do Lerian Access Manager. Cada upstream carrega seu próprio par de credenciais.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `REPORTER_CLIENT_ID` | **Obrigatório** quando a autenticação está ativada fora de `saas` | Identificador de cliente para o upstream do Reporter. |
| `REPORTER_CLIENT_SECRET` | **Obrigatório** quando a autenticação está ativada fora de `saas` | Segredo de cliente para o upstream do Reporter. `Sensitive.` |
| `STA_CLIENT_ID` | **Obrigatório** quando a autenticação está ativada fora de `saas` | Identificador de cliente para o upstream do STA. |
| `STA_CLIENT_SECRET` | **Obrigatório** quando a autenticação está ativada fora de `saas` | Segredo de cliente para o upstream do STA. `Sensitive.` |
| `REPORTER_M2M_TARGET_SERVICE` | `—` | Label de métricas para o upstream do Reporter. Um valor vazio recorre ao nome canônico do upstream. |
| `STA_M2M_TARGET_SERVICE` | `—` | Label de métricas para o upstream do STA. Um valor vazio recorre ao nome canônico do upstream. |

## Criptografia e idempotência

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `CCS_CRYPTO_MASTER_KEY` | **Obrigatório** | Chave mestra AES-256 de 32 bytes codificada em hexadecimal que criptografa os valores de documento que o serviço mantém criptografados. `Sensitive.` O boot falha quando o valor está ausente, é mais curto ou mais longo que 64 caracteres hexadecimais, ou não é hexadecimal. |
| `IDEMPOTENCY_KEY_PREFIX` | `idempotency:` | Prefixo base em cada chave de cache de idempotência. |
| `IDEMPOTENCY_KEY_TTL_HRS` | `168` | Janela de retenção, em horas, para uma resposta em cache. |

## Documentação da API

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SWAGGER_ENABLED` | `false` | Monta a rota interativa de documentação da API. A produção a mantém desligada. |
| `SWAGGER_TITLE` | Nome do serviço | Título renderizado na especificação da API. |
| `SWAGGER_DESCRIPTION` | `—` | Descrição renderizada na especificação da API. |
| `SWAGGER_VERSION` | `1.0.0` | Rótulo de versão da API renderizado na especificação. |
| `SWAGGER_HOST` | `—` | Substituição de host para a especificação da API. |
| `SWAGGER_SCHEMES` | `https` | Esquemas de URL separados por vírgulas que a especificação aceita. |

## Telemetria e métricas

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `ENABLE_TELEMETRY` | `false` | Conecta o exportador OpenTelemetry. Veja [Observabilidade](https://docs.lerian.studio/pt/platform/observability.md) para a visão de plataforma. |
| `OTEL_LIBRARY_NAME` | `—` | Nome da biblioteca de instrumentação. |
| `OTEL_RESOURCE_SERVICE_NAME` | Nome do serviço | Atributo de recurso de nome do serviço. |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | `—` | Atributo de recurso de ambiente de deploy. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `—` | Endereço do coletor para o exportador OpenTelemetry. |

## Rate limits

O Lerian CCS aplica três níveis de rate limit às rotas `/v1`: o nível padrão, o nível agressivo nas requisições de escrita e o nível de exportação nas leituras pesadas, como consultas de auditoria.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `RATE_LIMIT_ENABLED` | `false` | Ativa o subsistema de rate limit. A produção o força para `true`. |
| `RATE_LIMIT_MAX` | `500` | Teto de requisições do nível padrão por janela. |
| `RATE_LIMIT_WINDOW_SEC` | `60` | Janela do nível padrão, em segundos. |
| `AGGRESSIVE_RATE_LIMIT_MAX` | `100` | Teto de requisições do nível agressivo por janela. |
| `AGGRESSIVE_RATE_LIMIT_WINDOW_SEC` | `60` | Janela do nível agressivo, em segundos. |
| `EXPORT_RATE_LIMIT_MAX` | `60` | Teto de requisições do nível de exportação por janela. |
| `EXPORT_RATE_LIMIT_WINDOW_SEC` | `60` | Janela do nível de exportação, em segundos. |

## Endpoints de saúde

> [!NOTE]
>
> O Lerian CCS 1.0.0 expõe `GET /health` para liveness e `GET /readyz` para readiness na porta principal, além de `GET /version` e `GET /metrics`. Veja [Health e readiness](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o contrato da probe e [Operando o Lerian CCS](https://docs.lerian.studio/pt/rails/ccs/ccs-operations.md) para a lista de probes.

## Armazenamento de objetos

O Lerian CCS lê arquivos de entrada de um bucket e grava arquivos de saída em outro. Ambos aceitam qualquer armazenamento compatível com S3. No CCS 1.0.0, um nome de bucket vazio marca a verificação de readiness correspondente como ignorada.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `OBJECT_STORAGE_STA_ENDPOINT` | `—` | Endpoint do bucket de entrada. Um valor vazio seleciona o endpoint de nuvem padrão. |
| `OBJECT_STORAGE_STA_REGION` | `us-east-1` | Região do bucket de entrada. |
| `OBJECT_STORAGE_STA_BUCKET` | `—` | Nome do bucket de entrada somente leitura. |
| `OBJECT_STORAGE_STA_ACCESS_KEY` | `—` | Chave de acesso para o bucket de entrada. `Sensitive.` Deixe sem definir quando uma role de nuvem anexada fornece as credenciais. |
| `OBJECT_STORAGE_STA_SECRET_KEY` | `—` | Chave secreta para o bucket de entrada. `Sensitive.` |
| `OBJECT_STORAGE_STA_USE_PATH_STYLE` | `false` | Usa endereçamento path-style no bucket de entrada. |
| `OBJECT_STORAGE_STA_DISABLE_SSL` | `false` | Desativa o TLS na conexão com o bucket de entrada. |
| `OBJECT_STORAGE_STA_MAX_OBJECT_BYTES` | `536870912` | Tamanho máximo de um objeto de entrada, em bytes. |
| `OBJECT_STORAGE_STA_SSE_ALGORITHM` | **Obrigatório** quando o bucket de entrada está definido | Criptografia em repouso do bucket de entrada: `AES256`, `aws:kms` ou `none`. Um valor vazio ou outro valor interrompe o boot. `none` só inicia com um `ENV_NAME` de desenvolvimento fora de `saas`. |
| `OBJECT_STORAGE_STA_SSE_KMS_KEY_ID` | **Obrigatório** com `aws:kms` | Identificador da chave de `aws:kms` no bucket de entrada. |
| `OBJECT_STORAGE_CCS_ENDPOINT` | `—` | Endpoint do bucket de saída. Um valor vazio seleciona o endpoint de nuvem padrão. |
| `OBJECT_STORAGE_CCS_REGION` | `us-east-1` | Região do bucket de saída. |
| `OBJECT_STORAGE_CCS_BUCKET` | `—` | Nome do bucket de saída que guarda os arquivos regulatórios renderizados. |
| `OBJECT_STORAGE_CCS_ACCESS_KEY` | `—` | Chave de acesso para o bucket de saída. `Sensitive.` Deixe sem definir quando uma role de nuvem anexada fornece as credenciais. |
| `OBJECT_STORAGE_CCS_SECRET_KEY` | `—` | Chave secreta para o bucket de saída. `Sensitive.` |
| `OBJECT_STORAGE_CCS_USE_PATH_STYLE` | `false` | Usa endereçamento path-style no bucket de saída. |
| `OBJECT_STORAGE_CCS_DISABLE_SSL` | `false` | Desativa o TLS na conexão com o bucket de saída. |
| `OBJECT_STORAGE_CCS_SSE_ALGORITHM` | **Obrigatório** quando o bucket de saída está definido | Criptografia em repouso do bucket de saída: `AES256`, `aws:kms` ou `none`. Um valor vazio ou outro valor interrompe o boot. `none` só inicia com um `ENV_NAME` de desenvolvimento fora de `saas`. |
| `OBJECT_STORAGE_CCS_SSE_KMS_KEY_ID` | **Obrigatório** com `aws:kms` | Identificador da chave de `aws:kms` no bucket de saída. |

## Retenção e configurações regulatórias

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `CCS_OUTBOUND_RETENTION_DAYS` | `30` | Tempo de vida em dias de um arquivo de saída enviado ao bucket. O serviço aplica 30 dias para um valor igual ou menor que zero. |
| `CCS_ACCS009_RETENTION_DAYS` | `30` | Tempo de vida em dias de um relatório de penalidade ACCS009 armazenado. |
| `CCS_NON_SUBMISSION_SCAN_INTERVAL_SEC` | `3600` | Intervalo em segundos entre as varreduras de não envio. O boot recusa um valor igual ou menor que zero e um valor acima de 86400. |
| `CCS_BACEN_DESTINATARIO_CNPJ_BASE` | `00000000` | Destinatário BACEN de oito dígitos carimbado no envelope do arquivo. Defina o valor real antes de entrar em produção. |
| `CCS_ACCS010_DTFIM_MODE` | `transfer_date` | Regra que resolve a data de término obrigatória em uma transferência de relacionamento. |

[Integrando com o Lerian CCS](https://docs.lerian.studio/pt/rails/ccs/ccs-integration.md) cobre a superfície da API, os códigos de erro e os eventos publicados.


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