# Inbound Pipeline

The inbound pipeline automatically polls BCB STA for available files, downloads them, parses them, and delivers them to your configured Monetarie STA endpoints.

## Architecture Overview

```
                    ┌─────────────────┐
                    │   BCB STA       │
                    │   WebService    │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  STA Client     │
                    │ (SOAP/HTTPS)    │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
     ┌────────▼────────┐     │     ┌────────▼────────┐
     │   Poller        │     │     │  Rate Limiter   │
     │ (Scheduler)     │     │     │ (10 concurrent) │
     └────────┬────────┘     │     └─────────────────┘
              │              │
     ┌────────▼────────┐     │
     │   Processor     │◀────┘
     │ (Download/Parse)│
     └────────┬────────┘
              │
     ┌────────▼────────┐
     │   Router        │
     │ (Route to PIX)  │
     └────────┬────────┘
              │
     ┌────────▼────────┐
     │   Monetarie STA    │
     │   Endpoints     │
     └─────────────────┘
```

## How It Works

### 1. Polling for Files

The poller runs at configured intervals and queries BCB for available files:

```go
// Poller runs every interval_seconds
// Queries for files from configured systems
files, err := staClient.QueryAvailableFiles(ctx, &QueryParams{
    Sistemas:      []string{"CCS", "SPI", "DICT"},
    TamanhoPagina: batchSize,
})
```

### 2. Processing Files

For each discovered file, the processor:

1. Checks if already processed (prevents duplicates)
2. Downloads the file content from BCB
3. Parses using system-specific parser
4. Routes to the configured Monetarie STA endpoint
5. Confirms receipt with BCB (removes from queue)
6. Records in state store

### 3. Delivery to Monetarie STA

Files are delivered via HTTP to your configured routes:

```go
// Route delivers to Monetarie STA
resp, err := http.Post(route.URL, "application/json", fileContent)
```

### 4. Receipt Confirmation

After successful delivery, the connector confirms with BCB:

```go
// Confirm receipt removes file from BCB queue
err := staClient.ConfirmReceipt(ctx, protocolNumber)
```

## Configuration

### Basic Setup

Enable the inbound poller:

```yaml
poller:
  enabled: true
  interval_seconds: 30
  batch_size: 10
```

### System Selection

Specify which BCB systems to poll:

```yaml
poller:
  systems:
    - "CCS"
    - "SPI"
    - "DICT"
```

Leave empty or omit to poll all supported systems.

### Route Configuration

Define delivery routes for each system:

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

## File Processing States

Files move through the following states:

```
┌─────────┐    ┌────────────┐    ┌────────────┐    ┌───────────┐
│ pending │───▶│ downloading│───▶│ processing │───▶│ completed │
└─────────┘    └─────┬──────┘    └─────┬──────┘    └───────────┘
                     │                  │
                     │                  │
                     ▼                  ▼
               ┌──────────┐      ┌──────────┐
               │  failed  │◀─────│  failed  │
               └────┬─────┘      └──────────┘
                    │
                    ▼
               ┌──────────┐
               │ retrying │
               └──────────┘
```

| State | Description |
|-------|-------------|
| `pending` | File discovered, queued for processing |
| `downloading` | Downloading content from BCB |
| `processing` | Parsing and routing |
| `completed` | Successfully delivered and confirmed |
| `failed` | Processing failed |
| `retrying` | Scheduled for retry |

## Delivery Options

### HTTP Webhook

Deliver files via HTTP POST:

```yaml
routes:
  SPI:
    url: "https://your-api.com/webhooks/sta/spi"
    method: "POST"
    headers:
      Authorization: "Bearer ${TOKEN}"
      Content-Type: "application/json"
      X-Custom-Header: "value"
    timeout_seconds: 30
    retry_attempts: 3
    enabled: true
```

### Webhook Payload

The connector delivers files with the following JSON structure:

```json
{
  "protocol_number": "2026013100001234",
  "system_id": "SPI",
  "file_name": "SPI_20260131_001.xml",
  "file_type": "PACS.008",
  "content": "... base64 or parsed content ...",
  "metadata": {
    "received_at": "2026-01-31T10:30:00Z",
    "file_size": 12345,
    "checksum": "sha256:abc123..."
  }
}
```

## Retry Handling

Configure retry behavior per route:

```yaml
routes:
  SPI:
    retry_attempts: 5
    timeout_seconds: 30
```

| Setting | Default | Description |
|---------|---------|-------------|
| `retry_attempts` | `3` | Maximum retry attempts |
| `timeout_seconds` | `30` | Request timeout |

Retries use exponential backoff: 1s, 2s, 4s, 8s, 16s...

### Retry Queue

Failed files are added to a retry queue and processed asynchronously:

- Retries occur at increasing intervals
- Max retry count is configurable
- Files can be manually retried via Admin API

## Manual Operations

### Retry Failed Files

Retry a specific failed file via Admin API:

```bash
curl -u admin:password -X POST \
  http://localhost:8081/admin/retry/{file_id}
```

### Trigger Immediate Poll

Trigger a poll cycle immediately:

```bash
curl -u admin:password -X POST \
  http://localhost:8081/admin/poller/trigger
```

### List Pending Files

View files pending processing:

```bash
curl -u admin:password \
  "http://localhost:8081/admin/files?status=pending"
```

## Monitoring

### Health Check

Check poller status:

```bash
curl http://localhost:8080/api/v1/health
```

```json
{
  "status": "healthy",
  "sta_connection": "ok",
  "database": "ok",
  "details": {
    "pending_files": 5,
    "last_sta_check": "2026-01-31T10:30:00Z"
  }
}
```

### Admin Metrics

View inbound metrics:

```bash
curl -u admin:password http://localhost:8081/admin/metrics
```

```json
{
  "timestamp": "2026-01-31T10:30:00Z",
  "inbound": {
    "files_discovered": 1234,
    "files_processed": 1200,
    "files_failed": 12,
    "files_pending": 22
  },
  "poller": {
    "enabled": true,
    "last_poll": "2026-01-31T10:29:00Z",
    "poll_count": 500
  }
}
```

### Key Metrics

| Metric | Description |
|--------|-------------|
| `files_discovered` | Total files found in STA |
| `files_processed` | Successfully processed |
| `files_failed` | Failed to process |
| `files_pending` | Awaiting processing |

## Troubleshooting

### Files Not Being Discovered

1. **Check poller is enabled:**
   ```yaml
   poller:
     enabled: true
   ```

2. **Verify system IDs are correct:**
   ```yaml
   poller:
     systems: ["CCS", "SPI", "DICT"]
   ```

3. **Check STA connectivity:**
   ```bash
   curl http://localhost:8080/api/v1/health
   ```

4. **Review logs:**
   ```bash
   docker logs sta-connector 2>&1 | grep -i poller
   ```

### Download Failures

1. **Check network connectivity to BCB**
2. **Verify Sisbacen credentials:**
   ```yaml
   sta:
     username: "correct_user"
     password: "correct_pass"
   ```
3. **Check rate limit status** - BCB allows max 10 concurrent connections
4. **Review STA error responses in logs**

### Delivery Failures

1. **Verify destination URL is reachable:**
   ```bash
   curl -I https://staapi-planner.monetarie.com.br/api/v1/spi
   ```

2. **Check authentication credentials:**
   ```yaml
   routes:
     SPI:
       headers:
         Authorization: "Bearer ${VALID_TOKEN}"
   ```

3. **Review destination server logs**

4. **Check timeout settings:**
   ```yaml
   routes:
     SPI:
       timeout_seconds: 60  # Increase if needed
   ```

### High Memory Usage

1. **Reduce batch_size:**
   ```yaml
   poller:
     batch_size: 5  # Reduced from 10
   ```

2. **Increase polling interval:**
   ```yaml
   poller:
     interval_seconds: 60  # Increased from 30
   ```

3. **Check for stuck retries** via Admin API

## BCB Rate Limits

BCB enforces strict rate limits:

| Limit | Value |
|-------|-------|
| Max Concurrent Downloads | 10 |
| Max Queries per Minute | 120 |

The connector automatically enforces these limits. If you hit rate limits:

1. Reduce `batch_size`
2. Increase `interval_seconds`
3. Monitor rate limit warnings in logs

## Next Steps

- [Outbound Pipeline](/guide/outbound) - Sending files to BCB
- [Configuration](/guide/configuration) - Full configuration reference
- [Admin API](/api/admin) - Management endpoints