# Configuracao

O STA Connector usa um arquivo de configuracao YAML com expansao de variaveis de ambiente para gerenciamento seguro de credenciais.

## Arquivo de Configuracao

O arquivo de configuracao principal e `configs/config.yaml`. Variaveis de ambiente sao referenciadas usando a sintaxe `${VAR_NAME}` e expandidas em tempo de execucao.

### Ordem de Carregamento

A configuracao e carregada na seguinte ordem:

1. **Valores padrao** - Valores padrao sensiveis integrados
2. **Arquivo de configuracao** - Arquivo de configuracao YAML
3. **Variaveis de ambiente** - Sobrescrevem valores especificos em tempo de execucao

## Referencia Completa de Configuracao

```yaml
# Identificacao do servico e logging
service:
  name: "sta-connector"
  log_level: "info"  # debug, info, warn, error, fatal

# Conexao STA WebService
sta:
  environment: "homologation"  # homologation, production, sandbox
  base_url: ""                 # Opcional: sobrescreve URL auto-detectada
  username: "${STA_USERNAME}"
  password: "${STA_PASSWORD}"
  institution_code: "12345"
  timeout_seconds: 30
  max_retries: 3

# Poller de entrada (BCB -> Monetarie STA)
poller:
  enabled: true
  interval_seconds: 30
  systems:
    - "CCS"
    - "CIR"
    - "CMP"
    - "STR"
    - "SPI"
    - "CAM"
    - "LDL"
    - "DICT"
  batch_size: 10

# API de Saida (Monetarie STA -> BCB)
outbound_api:
  enabled: true
  host: "0.0.0.0"
  port: 8080
  auth:
    type: "api_key"        # api_key, jwt, ou none
    api_key: "${OUTBOUND_API_KEY}"

# API Admin (gerenciamento e monitoramento)
admin_api:
  enabled: true
  host: "0.0.0.0"
  port: 8081
  auth:
    username: "admin"
    password: "${ADMIN_PASSWORD}"

# Roteamento de arquivos (codigo do sistema -> endpoint Monetarie STA)
routes:
  CCS:
    url: "https://staapi-planner.monetarie.com.br/api/v1/ccs"
    method: "POST"
    headers:
      Authorization: "Bearer ${MONETARIE_STA_TOKEN}"
      Content-Type: "application/json"
    timeout_seconds: 30
    retry_attempts: 3
    enabled: true

# Persistencia de estado
state_store:
  type: "sqlite"           # sqlite ou postgres
  sqlite:
    path: "./data/state.db"
  postgres:
    host: "${DB_HOST}"
    port: 5432
    database: "sta_connector"
    username: "${DB_USER}"
    password: "${DB_PASSWORD}"
    ssl_mode: "disable"    # disable, require, verify-full
```

## Detalhes das Secoes

### Configuracoes de Servico

Configuracao geral do servico:

```yaml
service:
  name: "sta-connector"
  log_level: "info"
```

| Configuracao | Padrao | Descricao |
|--------------|--------|-----------|
| `name` | `sta-connector` | Nome do servico para logging e identificacao |
| `log_level` | `info` | Verbosidade do logging: `debug`, `info`, `warn`, `error`, `fatal` |

### Configuracoes STA

Configuracao de conexao do STA WebService BCB:

```yaml
sta:
  environment: "homologation"
  username: "${STA_USERNAME}"
  password: "${STA_PASSWORD}"
  institution_code: "12345"
  timeout_seconds: 30
  max_retries: 3
```

| Configuracao | Padrao | Descricao |
|--------------|--------|-----------|
| `environment` | `sandbox` | Ambiente BCB: `homologation`, `production`, `sandbox` |
| `base_url` | auto | Sobrescreve a URL auto-detectada |
| `username` | obrigatorio | Usuario Sisbacen |
| `password` | obrigatorio | Senha Sisbacen |
| `institution_code` | obrigatorio | Codigo da instituicao no Sisbacen |
| `timeout_seconds` | `30` | Timeout da requisicao HTTP |
| `max_retries` | `3` | Tentativas de retry em falhas transitorias |

#### URLs dos Ambientes

| Ambiente | URL |
|----------|-----|
| `homologation` | `https://sta-h.bcb.gov.br/staws` |
| `production` | `https://sta.bcb.gov.br/staws` |
| `sandbox` | `https://sta-h.bcb.gov.br/staws` |

### Configuracoes do Poller

Configure o polling de entrada do BCB:

```yaml
poller:
  enabled: true
  interval_seconds: 30
  systems:
    - "CCS"
    - "SPI"
    - "DICT"
  batch_size: 10
```

| Configuracao | Padrao | Descricao |
|--------------|--------|-----------|
| `enabled` | `false` | Habilita/desabilita polling de entrada |
| `interval_seconds` | `60` | Segundos entre ciclos de polling |
| `systems` | todos | Sistemas BCB para polling |
| `batch_size` | `100` | Maximo de arquivos por ciclo de polling |

#### Sistemas Suportados

| Sistema | Nome | Descricao |
|---------|------|-----------|
| `CCS` | Sistema de Consulta de Clientes | Arquivos de dados de clientes |
| `CIR` | Central de Informacoes de Credito | Informacoes de credito |
| `CMP` | Controle de Meios de Pagamento | Dados de controle de pagamento |
| `STR` | Sistema de Transferencia de Reservas | Transferencias de reservas |
| `SPI` | Sistema de Pagamentos Instantaneos | Transacoes PIX |
| `CAM` | Sistema de Cambio | Cambio estrangeiro |
| `LDL` | Liquidacao Diferida | Arquivos de liquidacao |
| `DICT` | Diretorio de Identificadores de Contas Transacionais | Diretorio de chaves PIX |

### Configuracoes da API de Saida

API para envio de arquivos ao BCB:

```yaml
outbound_api:
  enabled: true
  host: "0.0.0.0"
  port: 8080
  auth:
    type: "api_key"
    api_key: "${OUTBOUND_API_KEY}"
```

| Configuracao | Padrao | Descricao |
|--------------|--------|-----------|
| `enabled` | `false` | Habilita/desabilita a API de saida |
| `host` | `0.0.0.0` | Endereco de bind |
| `port` | `8080` | Porta de escuta |
| `auth.type` | `none` | Tipo de autenticacao: `api_key`, `jwt`, `none` |
| `auth.api_key` | | Chave API quando tipo e `api_key` |

### Configuracoes da API Admin

API de gerenciamento e monitoramento:

```yaml
admin_api:
  enabled: true
  host: "0.0.0.0"
  port: 8081
  auth:
    username: "admin"
    password: "${ADMIN_PASSWORD}"
```

| Configuracao | Padrao | Descricao |
|--------------|--------|-----------|
| `enabled` | `false` | Habilita/desabilita a API admin |
| `host` | `127.0.0.1` | Endereco de bind |
| `port` | `8081` | Porta de escuta |
| `auth.username` | obrigatorio | Usuario HTTP Basic auth |
| `auth.password` | obrigatorio | Senha HTTP Basic auth |

### Configuracao de Rotas

Defina como arquivos de entrada sao entregues ao Monetarie STA:

```yaml
routes:
  SPI:
    url: "https://staapi-planner.monetarie.com.br/api/v1/spi"
    method: "POST"
    headers:
      Authorization: "Bearer ${MONETARIE_STA_TOKEN}"
      Content-Type: "application/json"
    timeout_seconds: 30
    retry_attempts: 3
    enabled: true
```

| Configuracao | Padrao | Descricao |
|--------------|--------|-----------|
| `url` | obrigatorio | URL de destino para arquivos |
| `method` | `POST` | Metodo HTTP |
| `headers` | `{}` | Headers customizados a incluir |
| `timeout_seconds` | `30` | Timeout da requisicao |
| `retry_attempts` | `3` | Contagem de retries em falha |
| `enabled` | `true` | Habilita/desabilita esta rota |

### Configuracoes do State Store

Configure armazenamento persistente:

#### SQLite (Padrao)

```yaml
state_store:
  type: "sqlite"
  sqlite:
    path: "./data/state.db"
```

#### PostgreSQL

```yaml
state_store:
  type: "postgres"
  postgres:
    host: "localhost"
    port: 5432
    database: "sta_connector"
    username: "connector"
    password: "secret"
    ssl_mode: "require"
```

| Configuracao | Padrao | Descricao |
|--------------|--------|-----------|
| `type` | `sqlite` | Tipo de armazenamento: `sqlite` ou `postgres` |
| `sqlite.path` | `./data/state.db` | Caminho do arquivo de banco de dados SQLite |
| `postgres.host` | obrigatorio | Host PostgreSQL |
| `postgres.port` | `5432` | Porta PostgreSQL |
| `postgres.database` | obrigatorio | Nome do banco de dados |
| `postgres.username` | obrigatorio | Usuario do banco de dados |
| `postgres.password` | obrigatorio | Senha do banco de dados |
| `postgres.ssl_mode` | `disable` | Modo SSL: `disable`, `require`, `verify-full` |

## Variaveis de Ambiente

Todos os valores de configuracao podem ser sobrescritos com variaveis de ambiente:

```bash
# Servico
export SERVICE_NAME="my-connector"
export SERVICE_LOG_LEVEL="debug"

# STA
export STA_ENVIRONMENT="production"
export STA_USERNAME="user123"
export STA_PASSWORD="secret"
export STA_TIMEOUT_SECONDS=60

# Poller
export POLLER_ENABLED="true"
export POLLER_INTERVAL_SECONDS=30

# APIs
export OUTBOUND_API_PORT=8080
export ADMIN_API_PORT=8081

# Banco de Dados
export DB_HOST="postgres.example.com"
export DB_USER="connector"
export DB_PASSWORD="secret"
```

### Expansao de Variaveis

O arquivo de configuracao suporta sintaxe `${VAR_NAME}` para incorporar variaveis de ambiente:

```yaml
sta:
  username: "${STA_USERNAME}"
  password: "${STA_PASSWORD}"
```

### Valores Padrao

Use sintaxe `${VAR_NAME:-default}` para valores padrao:

```yaml
service:
  log_level: "${LOG_LEVEL:-info}"
```

## Hot Reload

Alteracoes de configuracao podem ser aplicadas em tempo de execucao via API Admin sem reiniciar o servico.

### Via API Admin

```bash
# Obter configuracao atual
curl -u admin:password http://localhost:8081/admin/config

# Atualizar uma configuracao
curl -u admin:password -X PATCH http://localhost:8081/admin/config \
  -H "Content-Type: application/json" \
  -d '{
    "poller": {
      "interval_seconds": 60
    }
  }'
```

### Configuracoes Suportadas para Hot-Reload

| Configuracao | Hot-Reloadable |
|--------------|----------------|
| `service.log_level` | Sim |
| `poller.enabled` | Sim |
| `poller.interval_seconds` | Sim |
| `poller.batch_size` | Sim |
| `routes.*.enabled` | Sim |
| `routes.*.url` | Sim |
| `routes.*.timeout_seconds` | Sim |
| `sta.timeout_seconds` | Sim |
| `sta.max_retries` | Sim |

Configuracoes como portas, hosts e conexoes de banco de dados requerem reinicio.

### Via Portal Admin

1. Navegue para a pagina de Configuracao
2. Edite as configuracoes no formulario
3. Clique em "Aplicar Alteracoes"
4. As alteracoes entram em vigor imediatamente

## Validacao de Configuracao

O connector valida a configuracao na inicializacao:

```bash
# Valide o arquivo de configuracao
./sta-connector --config config.yaml --validate
```

### Regras de Validacao

- `sta.username` e `sta.password` nao podem estar vazios
- `sta.environment` deve ser `homologation`, `production` ou `sandbox`
- `poller.interval_seconds` deve ser positivo quando habilitado
- `poller.batch_size` deve ser positivo quando habilitado
- `outbound_api.port` deve ser 1-65535 quando habilitado
- `admin_api.port` deve ser 1-65535 quando habilitado
- `routes.*.url` deve ser uma URL valida

## Limites de Taxa BCB

O BCB impoe limites de taxa rigorosos no STA WebService:

| Limite | Valor | Descricao |
|--------|-------|-----------|
| Max Conexoes Simultaneas | 10 | Por instituicao |
| Max Consultas por Minuto | 120 | Por instituicao |

O connector aplica automaticamente esses limites. Configure de forma conservadora para evitar atingir os limites:

```yaml
poller:
  batch_size: 10           # Nao exceda 10 downloads simultaneos
  interval_seconds: 30     # Evite polling rapido
```

## Proximos Passos

- [Pipeline de Entrada](/pt/guide/inbound) - Configure polling de arquivos
- [Pipeline de Saida](/pt/guide/outbound) - Configure uploads de arquivos
- [API Admin](/pt/api/admin) - Referencia da API de configuracao