# BACEN Connectivity

Configuration for connecting FluxiQ PIX to Banco Central do Brasil's DICT and SPI services via the RSFN (National Financial System Network).

## Prerequisites

- Institution registered as SPI participant with BCB
- ICP-Brasil certificates (CPIC + CPIA) issued and valid
- Network access to RSFN endpoints (firewall rules configured)
- Familiarity with [Certificates](./certificates.md) configuration

## BACEN Environments

| Environment | DICT URL | ICOM/SPI Primary | ICOM/SPI Secondary |
|-------------|----------|------------------|--------------------|
| Homologation | `https://dict-h.pi.rsfn.net.br:16522/api/v2` | `https://icom-h.pi.rsfn.net.br:16522` | `https://icom-sec-h.pi.rsfn.net.br:17522` |
| Production | `https://dict.pi.rsfn.net.br:16522/api/v2` | `https://icom.pi.rsfn.net.br:16522` | `https://icom-sec.pi.rsfn.net.br:17522` |

## Channel Routing (CPM/CSM)

The `Shared.Bacen.ChannelRouter` GenServer routes messages to the appropriate BACEN channel:

```mermaid
graph LR
    MSG[Message] --> CR{ChannelRouter}
    CR -->|Financial| CPM[Primary Channel<br/>:16522]
    CR -->|Non-Financial| CSM[Secondary Channel<br/>:17522]
    CPM -.->|Failover| CSM
    CSM -.->|Failover| CPM
```

- **Financial messages** (pacs.008, pacs.004) -> Primary (CPM, port 16522)
- **Non-financial messages** (pacs.002, pacs.028) -> Secondary (CSM, port 17522)
- **Auto-failover**: healthy -> degraded (2 failures) -> down (3 failures)
- **Recovery check**: every 2 minutes for downed channels

### Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `BACEN_FAILOVER_ENABLED` | `true` | Enable automatic CPM/CSM failover |
| `BACEN_FAILURE_THRESHOLD` | `3` | Failures before marking channel inactive |
| `BACEN_HEALTH_CHECK_INTERVAL` | `30` | Health check interval (seconds) |

## Error Handling (RFC 7807)

BACEN returns errors in RFC 7807 `application/problem+json` format. FluxiQ PIX handles these through:

- **`Shared.Bacen.ProblemDetails`**: Builds RFC 7807 responses for all error types
- **`Shared.Bacen.ErrorLookup`**: ETS-cached GenServer with 10-minute refresh for BACEN error codes
- 40+ error reason -> HTTP status mappings
- Content-Type: `application/problem+json`

## Simulator Mode

For testing without BACEN connectivity:

```bash
SIMULATOR_ENABLED=true
BACEN_ENABLED=false
```

The simulator provides:
- 8 pre-configured scenarios (happy_path, rejected_payment, return_flow, etc.)
- 11 simulator API endpoints under `/api/v1/simulator`
- Simulated DICT lookups and SPI message processing
- Integration test support (200 transactions: 100 send + 100 receive)

::: danger NEVER IN PRODUCTION
The simulator overrides real BACEN communication. Never enable `SIMULATOR_ENABLED=true` in production.
:::

## Audit Requirements

BCB requires comprehensive audit trails:

| Requirement | Implementation |
|-------------|----------------|
| ICOM message retention | 10 years |
| DICT read retention | 2 years |
| XML archival | SHA-256 hash per archived XML |
| Validation logging | Stored in `monetarie_audit.bacen_api_validations` |
| Export format | Gzipped JSONL for cold storage |

## XSD Validation

FluxiQ PIX validates all BACEN messages using a dual strategy:

1. **Structural validation**: `:xmerl` + Elixir rules for quick checks
2. **XSD file validation**: `xmllint` for full schema compliance

27 message type schemas are supported with required fields and format rules. Validation runs asynchronously via `Task.start` on both inbound and outbound messages.

## Expected Outcome

After configuring BACEN connectivity:

- mTLS connection to DICT and SPI homologation endpoints established
- Channel routing active (CPM for financial, CSM for non-financial)
- Auto-failover operational between channels
- Error responses in RFC 7807 format
- Audit trail recording all BACEN interactions