# Visao Geral da API

O STA Connector fornece duas APIs REST:

- **API de Saida** (Porta 8080) - Operacoes de upload de arquivos
- **API Admin** (Porta 8081) - Administracao e monitoramento

## URLs Base

| Ambiente | API de Saida | API Admin |
|----------|--------------|-----------|
| Desenvolvimento | `http://localhost:8080/api/v1` | `http://localhost:8081/admin` |
| Producao | `https://seu-dominio:8080/api/v1` | `https://seu-dominio:8081/admin` |

## Autenticacao

### API de Saida

Usa autenticacao por chave API:

```bash
curl -H "Authorization: Bearer sua-chave-api" \
  http://localhost:8080/api/v1/health
```

Ou com header X-API-Key:

```bash
curl -H "X-API-Key: sua-chave-api" \
  http://localhost:8080/api/v1/health
```

### API Admin

Usa autenticacao HTTP Basic:

```bash
curl -u admin:senha \
  http://localhost:8081/admin/health
```

## Estrutura da API

### Endpoints da API de Saida

| Metodo | Endpoint | Descricao | Documentacao |
|--------|----------|-----------|--------------|
| GET | `/api/v1/health` | Verificacao de saude | [API de Saida](/pt/api/outbound) |
| POST | `/api/v1/files` | Enviar arquivo para upload | [API de Saida](/pt/api/outbound) |
| GET | `/api/v1/files/{id}/status` | Verificar status do upload | [API de Saida](/pt/api/outbound) |

### Endpoints da API Admin

| Metodo | Endpoint | Descricao | Documentacao |
|--------|----------|-----------|--------------|
| GET | `/admin/health` | Health check com detalhes | [API Admin](/pt/api/admin) |
| GET | `/admin/config` | Obter configuracao | [API Admin](/pt/api/admin) |
| PATCH | `/admin/config` | Atualizar configuracao | [API Admin](/pt/api/admin) |
| GET | `/admin/metrics` | Obter metricas | [API Admin](/pt/api/admin) |
| GET | `/admin/files` | Listar arquivos processados | [API Admin](/pt/api/admin) |
| POST | `/admin/retry/{id}` | Retentar arquivo com falha | [API Admin](/pt/api/admin) |
| POST | `/admin/poller/trigger` | Disparar ciclo de poll | [API Admin](/pt/api/admin) |

## Endpoints Comuns

### Health Check (API de Saida)

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

Resposta:

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

### Health Check (API Admin)

```http
GET /admin/health
```

Resposta:

```json
{
  "status": "healthy",
  "version": "1.0.0",
  "checks": {
    "store": "healthy",
    "metrics": "healthy",
    "poller": "idle"
  },
  "timestamp": "2026-01-31T10:30:00Z"
}
```

## Formato de Requisicao/Resposta

### Headers de Requisicao

| Header | Obrigatorio | Descricao |
|--------|-------------|-----------|
| `Authorization` | Sim | Bearer token (Saida) ou Basic auth (Admin) |
| `Content-Type` | Para POST/PATCH | `application/json` |

### Resposta de Sucesso

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "protocol": "2026013100001234",
  "status": "uploaded",
  "created_at": "2026-01-31T10:30:00Z"
}
```

### Resposta de Erro

```json
{
  "error": "validation_error",
  "message": "system e obrigatorio"
}
```

## Codigos de Status HTTP

| Codigo | Descricao |
|--------|-----------|
| 200 | Sucesso |
| 201 | Criado |
| 202 | Aceito (operacao assincrona) |
| 400 | Requisicao Invalida |
| 401 | Nao Autorizado |
| 404 | Nao Encontrado |
| 409 | Conflito |
| 429 | Muitas Requisicoes |
| 500 | Erro Interno do Servidor |
| 502 | Bad Gateway (erro STA) |
| 503 | Servico Indisponivel |

## Codigos de Erro

| Codigo | Descricao |
|--------|-----------|
| `invalid_request` | Corpo da requisicao malformado |
| `validation_error` | Validacao da requisicao falhou |
| `invalid_content` | Conteudo base64 invalido |
| `not_found` | Recurso nao encontrado |
| `sta_error` | Erro do WebService STA |
| `sta_auth_error` | Autenticacao STA falhou |
| `sta_rate_limit` | Limite de taxa STA excedido |
| `sta_connection_error` | Falha ao conectar ao STA |
| `internal_error` | Erro interno do servidor |

## Limites de Taxa

O connector aplica os limites de taxa do BCB:

- **Maximo 10** uploads simultaneos por instituicao
- **Maximo 120** consultas por minuto por instituicao

Quando rate limited:

```http
HTTP/1.1 429 Too Many Requests

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

## Paginacao

Endpoints de listagem suportam paginacao:

```http
GET /admin/files?limit=50&offset=100
```

| Parametro | Padrao | Max | Descricao |
|-----------|--------|-----|-----------|
| `limit` | 100 | 1000 | Itens por pagina |
| `offset` | 0 | - | Pular itens |

A resposta inclui metadados de paginacao:

```json
{
  "files": [...],
  "total": 500,
  "limit": 50,
  "offset": 100,
  "has_more": true
}
```

## Filtragem

Endpoints de listagem suportam filtragem:

```http
GET /admin/files?status=failed&system=SPI&start_date=2026-01-01
```

| Filtro | Tipo | Descricao |
|--------|------|-----------|
| `status` | string | Filtrar por status |
| `system` | string | Filtrar por sistema BCB |
| `start_date` | ISO 8601 | Data inicial |
| `end_date` | ISO 8601 | Data final |

## Exemplos Rapidos

### Enviar um Arquivo

```bash
curl -X POST http://localhost:8080/api/v1/files \
  -H "Authorization: Bearer sua-chave-api" \
  -H "Content-Type: application/json" \
  -d '{
    "system": "CCS",
    "file_type": "ARQC001",
    "data": {
      "content": "'$(base64 -w0 arquivo.txt)'"
    },
    "destination": {
      "ispb": "00000000"
    }
  }'
```

### Verificar Status

```bash
curl -H "Authorization: Bearer sua-chave-api" \
  http://localhost:8080/api/v1/files/550e8400-.../status
```

### Obter Metricas

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

### Retentar Arquivo com Falha

```bash
curl -u admin:senha -X POST \
  http://localhost:8081/admin/retry/550e8400-...
```

## Proximos Passos

- [API de Saida](/pt/api/outbound) - Endpoints de upload de arquivos
- [API Admin](/pt/api/admin) - Administracao e monitoramento
- [Monitoramento em Tempo Real](/pt/api/channels) - Monitoramento baseado em polling