# Pipeline de Saida

O pipeline de saida gerencia uploads de arquivos do seu sistema FluxiQ STA para o BCB STA.

## Visao Geral da Arquitetura

```
+-------------------+
|   FluxiQ STA      |
|   Aplicacao       |
+---------+---------+
          |
          | POST /api/v1/files
          v
+-------------------+
|   API de Saida    |
|   (Porta 8080)    |
+---------+---------+
          |
          | Validar & Armazenar
          v
+-------------------+
|   State Store     |
|   (SQLite/PG)     |
+---------+---------+
          |
          | Solicitar Protocolo
          v
+-------------------+
|   Cliente STA     |
|   (SOAP/HTTPS)    |
+---------+---------+
          |
          | Upload do Arquivo
          v
+-------------------+
|     BCB STA       |
|   WebService      |
+-------------------+
```

## Como Funciona

### 1. Submissao de Arquivo

Submeta arquivos via API REST:

```bash
curl -X POST http://localhost:8080/api/v1/files \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "system": "CCS",
    "file_type": "GCCS001",
    "data": {
      "content": "SGVsbG8gV29ybGQ=",
      "file_name": "CCS_20260131_001.txt"
    },
    "destination": {
      "ispbs": ["12345678"]
    }
  }'
```

Resposta:

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "protocol": "2026013100001234",
  "status": "uploaded",
  "created_at": "2026-01-31T10:30:00Z",
  "file_name": "CCS_20260131_001.txt",
  "file_size": 12345,
  "checksum": "sha256:abc123..."
}
```

### 2. Solicitacao de Protocolo

O connector solicita um protocolo de upload do BCB:

```go
// Solicita protocolo para upload
protocolResp, err := staClient.RequestProtocol(ctx, &ProtocolRequest{
    NomeArquivo:   fileName,
    TipoArquivo:   fileType,
    ISPBsDestino:  []string{"12345678"},
})
// Retorna: protocol_number para o upload
```

### 3. Upload do Arquivo

Com o numero de protocolo, o arquivo e enviado:

```go
// Envia conteudo do arquivo para o BCB
err := staClient.UploadFile(ctx, protocolNumber, content)
```

### 4. Rastreamento de Status

Seu sistema pode fazer polling para atualizacoes de status ou receber notificacoes via webhook.

## Referencia da API

### Submeter Arquivo

```http
POST /api/v1/files
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "system": "CCS",
  "file_type": "GCCS001",
  "data": {
    "content": "conteudo-codificado-base64",
    "file_name": "nome_opcional.txt"
  },
  "destination": {
    "ispbs": ["12345678", "87654321"]
  },
  "metadata": {
    "reference": "seu-id-interno"
  }
}
```

| Campo | Tipo | Obrigatorio | Descricao |
|-------|------|-------------|-----------|
| `system` | string | Sim | Codigo do sistema BCB (CCS, SPI, etc.) |
| `file_type` | string | Sim | Identificador do tipo de arquivo BCB |
| `data.content` | string | Sim | Conteudo do arquivo codificado em Base64 |
| `data.file_name` | string | Nao | Nome customizado do arquivo (gerado automaticamente se omitido) |
| `destination.ispbs` | array | Nao | Codigos ISPB de destino |
| `metadata` | object | Nao | Metadados customizados para rastreamento |

### Obter Status do Arquivo

```http
GET /api/v1/files/{id}/status
Authorization: Bearer {api_key}
```

Resposta:

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "system": "CCS",
  "file_name": "CCS_20260131_001.txt",
  "file_type": "GCCS001",
  "file_size": 12345,
  "checksum": "sha256:abc123...",
  "status": "completed",
  "protocol": "2026013100001234",
  "sta_status": "PROCESSADO",
  "sta_message": null,
  "created_at": "2026-01-31T10:30:00Z",
  "updated_at": "2026-01-31T10:30:15Z"
}
```

### Health Check

```http
GET /api/v1/health
```

Resposta:

```json
{
  "status": "healthy",
  "sta_connection": "ok",
  "database": "ok",
  "uptime_seconds": 86400,
  "version": "1.0.0"
}
```

## Estados de Arquivo

Arquivos passam pelos seguintes estados:

```
+---------+    +------------+    +-----------+
| pending |----> uploading  |----> uploaded  |
+---------+    +-----+------+    +-----+-----+
                     |                  |
                     v                  v
               +----------+      +-----------+
               |  failed  |      | completed |
               +----------+      +-----------+
```

| Status | Descricao |
|--------|-----------|
| `pending` | Enfileirado para processamento |
| `uploading` | Upload em progresso |
| `uploaded` | Enviado com sucesso ao BCB |
| `processing` | BCB esta processando o arquivo |
| `completed` | BCB aceitou o arquivo |
| `failed` | Upload ou processamento falhou |

## Configuracao

### Configuracao da API de Saida

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

### Tipos de Autenticacao

#### API Key

```yaml
outbound_api:
  auth:
    type: "api_key"
    api_key: "${OUTBOUND_API_KEY}"
```

Uso:

```bash
curl -H "Authorization: Bearer ${API_KEY}" ...
# ou
curl -H "X-API-Key: ${API_KEY}" ...
```

#### Sem Autenticacao (Apenas Desenvolvimento)

```yaml
outbound_api:
  auth:
    type: "none"
```

## Validacao de Arquivo

### Validacao Integrada

O connector valida arquivos antes da submissao:

| Verificacao | Descricao |
|-------------|-----------|
| Tamanho do conteudo | Maximo 50 MB |
| Codificacao Base64 | Deve ser base64 valido |
| ID do Sistema | Deve ser sistema BCB valido |
| Tipo de Arquivo | Deve ser valido para o sistema |

### Erro de Validacao

```json
{
  "error": "validation_error",
  "message": "data.content deve ser base64 valido"
}
```

## Tratamento de Erros

### Erros Comuns

| Codigo de Erro | Status HTTP | Descricao | Resolucao |
|----------------|-------------|-----------|-----------|
| `invalid_request` | 400 | Requisicao malformada | Verifique formato do body |
| `validation_error` | 400 | Validacao falhou | Corrija erros de validacao |
| `sta_auth_error` | 502 | Autenticacao STA falhou | Verifique credenciais |
| `sta_rate_limit` | 429 | Limite de taxa BCB excedido | Aguarde e retente |
| `sta_error` | 502 | Erro do servico STA | Verifique status do BCB |
| `sta_connection_error` | 502 | Nao foi possivel conectar ao STA | Verifique rede |
| `internal_error` | 500 | Erro inesperado | Verifique logs |

### Resposta de Erro

```json
{
  "error": "sta_rate_limit",
  "message": "Limite de taxa STA excedido"
}
```

## Tratamento de Retry

### Retries Automaticos

O connector automaticamente retenta em falhas transitorias:

- Timeouts de rede
- Erros temporarios STA (5xx)
- Rate limit com header Retry-After

Comportamento de retry:

| Configuracao | Valor |
|--------------|-------|
| Max retries | 3 (configuravel) |
| Backoff | Exponencial (1s, 2s, 4s) |

### Retry Manual

Retente um upload com falha via API Admin:

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

## Rastreamento de Status

### Polling

Faca polling para atualizacoes de status:

```bash
# Verificar status
curl -H "Authorization: Bearer ${API_KEY}" \
  http://localhost:8080/api/v1/files/{id}/status
```

### Atualizacao de Status

O connector atualiza o status do BCB quando voce consulta arquivos em status `uploaded` ou `processing`.

## Monitoramento

### Metricas

Visualize metricas de saida via API Admin:

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

```json
{
  "timestamp": "2026-01-31T10:30:00Z",
  "outbound": {
    "files_submitted": 5000,
    "files_uploaded": 4995,
    "files_failed": 3,
    "files_pending": 2
  }
}
```

### Metricas Principais

| Metrica | Descricao |
|---------|-----------|
| `files_submitted` | Total de arquivos submetidos |
| `files_uploaded` | Enviados com sucesso ao BCB |
| `files_failed` | Uploads com falha |
| `files_pending` | Aguardando upload |

## Boas Praticas

1. **Use nomes de arquivo unicos** - Inclua timestamp e numero sequencial
2. **Armazene o ID do arquivo** - Para rastreamento de status e troubleshooting
3. **Trate rate limits graciosamente** - Implemente backoff no seu cliente
4. **Monitore profundidade da fila** - Alerte se arquivos pendentes crescerem
5. **Implemente idempotencia** - Use metadata para deduplicacao
6. **Valide antes de enviar** - Verifique formato do arquivo localmente

## Limites de Taxa BCB

O BCB aplica limites de taxa rigorosos:

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

O connector automaticamente enfileira uploads quando os limites sao atingidos.

## Proximos Passos

- [Pipeline de Entrada](/pt/guide/inbound) - Recebendo arquivos do BCB
- [API Admin](/pt/api/admin) - Gerenciamento e monitoramento
- [Referencia da API de Saida](/pt/api/outbound) - Documentacao completa da API