# Pipeline de Entrada

O pipeline de entrada automaticamente faz polling no BCB STA para arquivos disponiveis, faz download, faz parse e entrega para seus endpoints Monetarie STA configurados.

## Visao Geral da Arquitetura

```
                    +-------------------+
                    |     BCB STA       |
                    |   WebService      |
                    +---------+---------+
                              |
                    +---------v---------+
                    |   Cliente STA     |
                    |  (SOAP/HTTPS)     |
                    +---------+---------+
                              |
              +---------------+---------------+
              |               |               |
     +--------v--------+      |      +--------v--------+
     |    Poller       |      |      |  Rate Limiter   |
     |  (Scheduler)    |      |      | (10 simultaneos)|
     +--------+--------+      |      +-----------------+
              |               |
     +--------v--------+      |
     |   Processor     |<-----+
     | (Download/Parse)|
     +--------+--------+
              |
     +--------v--------+
     |    Router       |
     | (Rota p/ PIX)   |
     +--------+--------+
              |
     +--------v--------+
     |   Monetarie STA    |
     |    Endpoints    |
     +-----------------+
```

## Como Funciona

### 1. Polling de Arquivos

O poller executa em intervalos configurados e consulta o BCB por arquivos disponiveis:

```go
// Poller executa a cada interval_seconds
// Consulta arquivos dos sistemas configurados
files, err := staClient.QueryAvailableFiles(ctx, &QueryParams{
    Sistemas:      []string{"CCS", "SPI", "DICT"},
    TamanhoPagina: batchSize,
})
```

### 2. Processamento de Arquivos

Para cada arquivo descoberto, o processor:

1. Verifica se ja foi processado (evita duplicatas)
2. Faz download do conteudo do arquivo do BCB
3. Faz parse usando parser especifico do sistema
4. Roteia para o endpoint Monetarie STA configurado
5. Confirma recebimento com BCB (remove da fila)
6. Registra no state store

### 3. Entrega ao Monetarie STA

Arquivos sao entregues via HTTP para suas rotas configuradas:

```go
// Rota entrega ao Monetarie STA
resp, err := http.Post(route.URL, "application/json", fileContent)
```

### 4. Confirmacao de Recebimento

Apos entrega bem-sucedida, o connector confirma com o BCB:

```go
// Confirmar recebimento remove arquivo da fila BCB
err := staClient.ConfirmReceipt(ctx, protocolNumber)
```

## Configuracao

### Configuracao Basica

Habilite o poller de entrada:

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

### Selecao de Sistemas

Especifique quais sistemas BCB fazer polling:

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

Deixe vazio ou omita para fazer polling de todos os sistemas suportados.

### Configuracao de Rotas

Defina rotas de entrega para cada sistema:

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

## Estados de Processamento de Arquivo

Arquivos passam pelos seguintes estados:

```
+---------+    +------------+    +------------+    +-----------+
| pending |----> downloading|---->| processing |----> completed |
+---------+    +-----+------+    +-----+------+    +-----------+
                     |                  |
                     |                  |
                     v                  v
               +----------+      +----------+
               |  failed  |<-----|  failed  |
               +----+-----+      +----------+
                    |
                    v
               +----------+
               | retrying |
               +----------+
```

| Estado | Descricao |
|--------|-----------|
| `pending` | Arquivo descoberto, enfileirado para processamento |
| `downloading` | Fazendo download do conteudo do BCB |
| `processing` | Fazendo parse e roteamento |
| `completed` | Entregue e confirmado com sucesso |
| `failed` | Processamento falhou |
| `retrying` | Agendado para retry |

## Opcoes de Entrega

### Webhook HTTP

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

### Payload do Webhook

O connector entrega arquivos com a seguinte estrutura JSON:

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

## Tratamento de Retry

Configure o comportamento de retry por rota:

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

| Configuracao | Padrao | Descricao |
|--------------|--------|-----------|
| `retry_attempts` | `3` | Maximo de tentativas de retry |
| `timeout_seconds` | `30` | Timeout da requisicao |

Retries usam backoff exponencial: 1s, 2s, 4s, 8s, 16s...

### Fila de Retry

Arquivos com falha sao adicionados a uma fila de retry e processados assincronamente:

- Retries ocorrem em intervalos crescentes
- Contagem maxima de retry e configuravel
- Arquivos podem ser retentados manualmente via API Admin

## Operacoes Manuais

### Retentar Arquivos com Falha

Retente um arquivo especifico com falha via API Admin:

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

### Disparar Poll Imediato

Dispare um ciclo de poll imediatamente:

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

### Listar Arquivos Pendentes

Visualize arquivos pendentes de processamento:

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

## Monitoramento

### Health Check

Verifique o status do poller:

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

### Metricas Admin

Visualize metricas de entrada:

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

### Metricas Principais

| Metrica | Descricao |
|---------|-----------|
| `files_discovered` | Total de arquivos encontrados no STA |
| `files_processed` | Processados com sucesso |
| `files_failed` | Falha ao processar |
| `files_pending` | Aguardando processamento |

## Solucao de Problemas

### Arquivos Nao Estao Sendo Descobertos

1. **Verifique se o poller esta habilitado:**
   ```yaml
   poller:
     enabled: true
   ```

2. **Verifique se os IDs de sistema estao corretos:**
   ```yaml
   poller:
     systems: ["CCS", "SPI", "DICT"]
   ```

3. **Verifique a conectividade STA:**
   ```bash
   curl http://localhost:8080/api/v1/health
   ```

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

### Falhas de Download

1. **Verifique a conectividade de rede com o BCB**
2. **Verifique as credenciais Sisbacen:**
   ```yaml
   sta:
     username: "usuario_correto"
     password: "senha_correta"
   ```
3. **Verifique o status do rate limit** - BCB permite max 10 conexoes simultaneas
4. **Revise as respostas de erro STA nos logs**

### Falhas de Entrega

1. **Verifique se a URL de destino esta acessivel:**
   ```bash
   curl -I https://staapi-planner.monetarie.com.br/api/v1/spi
   ```

2. **Verifique as credenciais de autenticacao:**
   ```yaml
   routes:
     SPI:
       headers:
         Authorization: "Bearer ${TOKEN_VALIDO}"
   ```

3. **Revise os logs do servidor de destino**

4. **Verifique as configuracoes de timeout:**
   ```yaml
   routes:
     SPI:
       timeout_seconds: 60  # Aumente se necessario
   ```

### Alto Uso de Memoria

1. **Reduza o batch_size:**
   ```yaml
   poller:
     batch_size: 5  # Reduzido de 10
   ```

2. **Aumente o intervalo de polling:**
   ```yaml
   poller:
     interval_seconds: 60  # Aumentado de 30
   ```

3. **Verifique retries travados** via API Admin

## Limites de Taxa BCB

O BCB aplica limites de taxa rigorosos:

| Limite | Valor |
|--------|-------|
| Max Downloads Simultaneos | 10 |
| Max Consultas por Minuto | 120 |

O connector automaticamente aplica esses limites. Se voce atingir os limites de taxa:

1. Reduza `batch_size`
2. Aumente `interval_seconds`
3. Monitore avisos de rate limit nos logs

## Proximos Passos

- [Pipeline de Saida](/pt/guide/outbound) - Envio de arquivos para o BCB
- [Configuracao](/pt/guide/configuration) - Referencia completa de configuracao
- [API Admin](/pt/api/admin) - Endpoints de gerenciamento