# Configuration

STA Connector uses a YAML configuration file with environment variable expansion for secure credential management.

## Configuration File

The main configuration file is `configs/config.yaml`. Environment variables are referenced using `${VAR_NAME}` syntax and expanded at runtime.

### Loading Order

Configuration is loaded in the following order:

1. **Default values** - Built-in sensible defaults
2. **Config file** - YAML configuration file
3. **Environment variables** - Override specific values at runtime

## Complete Configuration Reference

```yaml
# Service identification and logging
service:
  name: "sta-connector"
  log_level: "info"  # debug, info, warn, error, fatal

# STA WebService connection
sta:
  environment: "homologation"  # homologation, production, sandbox
  base_url: ""                 # Optional: override auto-detected URL
  username: "${STA_USERNAME}"
  password: "${STA_PASSWORD}"
  institution_code: "12345"
  timeout_seconds: 30
  max_retries: 3

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

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

# Admin API (management & monitoring)
admin_api:
  enabled: true
  host: "0.0.0.0"
  port: 8081
  auth:
    username: "admin"
    password: "${ADMIN_PASSWORD}"

# File routing (system code -> Monetarie STA endpoint)
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

# State persistence
state_store:
  type: "sqlite"           # sqlite or 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
```

## Section Details

### Service Settings

General service configuration:

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

| Setting | Default | Description |
|---------|---------|-------------|
| `name` | `sta-connector` | Service name for logging and identification |
| `log_level` | `info` | Logging verbosity: `debug`, `info`, `warn`, `error`, `fatal` |

### STA Settings

BCB STA WebService connection configuration:

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

| Setting | Default | Description |
|---------|---------|-------------|
| `environment` | `sandbox` | BCB environment: `homologation`, `production`, `sandbox` |
| `base_url` | auto | Override the auto-detected URL |
| `username` | required | Sisbacen username |
| `password` | required | Sisbacen password |
| `institution_code` | required | Institution code in Sisbacen |
| `timeout_seconds` | `30` | HTTP request timeout |
| `max_retries` | `3` | Retry attempts on transient failures |

#### Environment URLs

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

### Poller Settings

Configure inbound polling from BCB:

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

| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `false` | Enable/disable inbound polling |
| `interval_seconds` | `60` | Seconds between poll cycles |
| `systems` | all | BCB systems to poll |
| `batch_size` | `100` | Maximum files per poll cycle |

#### Supported Systems

| System | Name | Description |
|--------|------|-------------|
| `CCS` | Customer Consultation System | Customer data files |
| `CIR` | Credit Information Registry | Credit information |
| `CMP` | Means of Payment Control | Payment control data |
| `STR` | Reserve Transfer System | Reserve transfers |
| `SPI` | Instant Payment System | PIX transactions |
| `CAM` | Foreign Exchange System | Currency exchange |
| `LDL` | Deferred Settlement | Settlement files |
| `DICT` | PIX Directory | PIX keys directory |

### Outbound API Settings

API for sending files to BCB:

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

| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `false` | Enable/disable the outbound API |
| `host` | `0.0.0.0` | Bind address |
| `port` | `8080` | Listen port |
| `auth.type` | `none` | Authentication type: `api_key`, `jwt`, `none` |
| `auth.api_key` | | API key when type is `api_key` |

### Admin API Settings

Management and monitoring API:

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

| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `false` | Enable/disable the admin API |
| `host` | `127.0.0.1` | Bind address |
| `port` | `8081` | Listen port |
| `auth.username` | required | HTTP Basic auth username |
| `auth.password` | required | HTTP Basic auth password |

### Routes Configuration

Define how inbound files are delivered to 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
```

| Setting | Default | Description |
|---------|---------|-------------|
| `url` | required | Destination URL for files |
| `method` | `POST` | HTTP method |
| `headers` | `{}` | Custom headers to include |
| `timeout_seconds` | `30` | Request timeout |
| `retry_attempts` | `3` | Retry count on failure |
| `enabled` | `true` | Enable/disable this route |

### State Store Settings

Configure persistent storage:

#### SQLite (Default)

```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"
```

| Setting | Default | Description |
|---------|---------|-------------|
| `type` | `sqlite` | Storage type: `sqlite` or `postgres` |
| `sqlite.path` | `./data/state.db` | SQLite database file path |
| `postgres.host` | required | PostgreSQL host |
| `postgres.port` | `5432` | PostgreSQL port |
| `postgres.database` | required | Database name |
| `postgres.username` | required | Database user |
| `postgres.password` | required | Database password |
| `postgres.ssl_mode` | `disable` | SSL mode: `disable`, `require`, `verify-full` |

## Environment Variables

All configuration values can be overridden with environment variables:

```bash
# Service
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

# Database
export DB_HOST="postgres.example.com"
export DB_USER="connector"
export DB_PASSWORD="secret"
```

### Variable Expansion

The config file supports `${VAR_NAME}` syntax for embedding environment variables:

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

### Default Values

Use `${VAR_NAME:-default}` syntax for defaults:

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

## Hot Reload

Configuration changes can be applied at runtime via the Admin API without restarting the service.

### Via Admin API

```bash
# Get current configuration
curl -u admin:password http://localhost:8081/admin/config

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

### Supported Hot-Reload Settings

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

Settings like ports, hosts, and database connections require a restart.

### Via Admin Portal

1. Navigate to the Configuration page
2. Edit settings in the form
3. Click "Apply Changes"
4. Changes take effect immediately

## Configuration Validation

The connector validates configuration on startup:

```bash
# Validate configuration file
./sta-connector --config config.yaml --validate
```

### Validation Rules

- `sta.username` and `sta.password` must not be empty
- `sta.environment` must be `homologation`, `production`, or `sandbox`
- `poller.interval_seconds` must be positive when enabled
- `poller.batch_size` must be positive when enabled
- `outbound_api.port` must be 1-65535 when enabled
- `admin_api.port` must be 1-65535 when enabled
- `routes.*.url` must be a valid URL

## Example Configurations

### Development

```yaml
service:
  name: "sta-connector-dev"
  log_level: "debug"

sta:
  environment: "sandbox"
  username: "${STA_USERNAME}"
  password: "${STA_PASSWORD}"
  institution_code: "99999"
  timeout_seconds: 10

poller:
  enabled: true
  interval_seconds: 10
  systems: ["SPI"]
  batch_size: 5

outbound_api:
  enabled: true
  host: "127.0.0.1"
  port: 8080
  auth:
    type: "none"

admin_api:
  enabled: true
  host: "127.0.0.1"
  port: 8081
  auth:
    username: "admin"
    password: "admin"

state_store:
  type: "sqlite"
  sqlite:
    path: "./data/dev.db"
```

### Production

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

sta:
  environment: "production"
  username: "${STA_USERNAME}"
  password: "${STA_PASSWORD}"
  institution_code: "${STA_INSTITUTION_CODE}"
  timeout_seconds: 60
  max_retries: 5

poller:
  enabled: true
  interval_seconds: 30
  systems:
    - "CCS"
    - "CIR"
    - "CMP"
    - "STR"
    - "SPI"
    - "CAM"
    - "LDL"
    - "DICT"
  batch_size: 50

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

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

routes:
  SPI:
    url: "${MONETARIE_STA_BASE_URL}/api/v1/spi"
    method: "POST"
    headers:
      Authorization: "Bearer ${MONETARIE_STA_TOKEN}"
      Content-Type: "application/json"
    timeout_seconds: 30
    retry_attempts: 5
    enabled: true
  # ... configure all systems

state_store:
  type: "postgres"
  postgres:
    host: "${DB_HOST}"
    port: 5432
    database: "sta_connector"
    username: "${DB_USER}"
    password: "${DB_PASSWORD}"
    ssl_mode: "require"
```

## BCB Rate Limits

BCB enforces strict rate limits on the STA WebService:

| Limit | Value | Description |
|-------|-------|-------------|
| Max Concurrent Connections | 10 | Per institution |
| Max Queries per Minute | 120 | Per institution |

The connector automatically enforces these limits. Configure conservatively to avoid hitting limits:

```yaml
poller:
  batch_size: 10           # Don't exceed 10 concurrent downloads
  interval_seconds: 30     # Avoid rapid polling
```

## Next Steps

- [Inbound Pipeline](/guide/inbound) - Configure file polling
- [Outbound Pipeline](/guide/outbound) - Configure file uploads
- [Admin API](/api/admin) - Configuration API reference