# Referencia da API

Visao geral completa da API REST da plataforma Monetarie PIX, incluindo autenticacao, endpoints, formatos de requisicao/resposta e exemplos com curl.

## Pre-requisitos

- curl instalado para executar exemplos
- jq instalado para formatar respostas JSON
- Conhecimento do formato RFC 7807 para erros
- Credenciais de acesso (usuario/senha) para autenticacao

## URLs Base

| Servico | Porta | URL (Dev) | Descricao |
|---------|-------|-----------|-----------|
| Settlement (Gateway) | 4003 | `https://pixapi-dev.fluxiq.com.br` | API Gateway principal |
| Dict Service | 4001 | Interno (proxy via Settlement) | Diretorio de chaves PIX |
| SPI Service | 4002 | Interno (proxy via Settlement) | Pagamentos instantaneos |

::: tip API Gateway
O Settlement Service (porta 4003) e o ponto de entrada unico para todas as requisicoes externas. Ele faz proxy para os servicos DICT (4001) e SPI (4002) internamente. Nao e necessario acessar DICT ou SPI diretamente.
:::

## Autenticacao

### Login

```bash
# 1. Obter chave publica RSA para criptografia da senha
curl -s https://pixapi-dev.fluxiq.com.br/api/v1/auth/public-key | jq .
# Saida:
# {"public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBg..."}

# 2. Login (senha em texto plano para exemplo; em producao, criptografar com RSA-OAEP)
curl -s -c cookies.txt \
  -X POST https://pixapi-dev.fluxiq.com.br/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin@2026!"}' | jq .

# Saida esperada:
# {
#   "status": "ok",
#   "user": {
#     "id": "550e8400-e29b-41d4-a716-446655440000",
#     "username": "admin",
#     "role": "system_administrator"
#   }
# }

# O cookie pix_session e definido automaticamente (HttpOnly)
# O cookie __monetarie_csrf e retornado para double-submit CSRF
```

### Autenticacao em Requisicoes

Todas as requisicoes autenticadas devem incluir:

| Header/Cookie | Valor | Obrigatorio |
|--------------|-------|-------------|
| Cookie: `pix_session` | JWT token (definido pelo login) | Sim |
| X-CSRF-Token | Valor do cookie `__monetarie_csrf` | Sim (para POST/PUT/DELETE) |

```bash
# Exemplo de requisicao autenticada
CSRF=$(grep __monetarie_csrf cookies.txt | awk '{print $NF}')
curl -s -b cookies.txt \
  -H "X-CSRF-Token: ${CSRF}" \
  https://pixapi-dev.fluxiq.com.br/api/v1/transactions | jq .
```

### Logout

```bash
curl -s -b cookies.txt \
  -X POST https://pixapi-dev.fluxiq.com.br/api/v1/auth/logout \
  -H "X-CSRF-Token: ${CSRF}" | jq .
# Saida: {"status": "ok"}
# O token JWT e adicionado ao blacklist no Redis
```

### MFA (Autenticacao Multi-Fator)

```bash
# Verificar se MFA esta habilitado
curl -s -b cookies.txt \
  https://pixapi-dev.fluxiq.com.br/api/v1/auth/me | jq .mfa_enabled

# Configurar MFA (TOTP)
curl -s -b cookies.txt \
  -X POST https://pixapi-dev.fluxiq.com.br/api/v1/auth/mfa/setup \
  -H "X-CSRF-Token: ${CSRF}" | jq .
# Retorna: secret (base32) + qr_code_uri (otpauth://)

# Verificar codigo MFA durante login
curl -s -c cookies.txt \
  -X POST https://pixapi-dev.fluxiq.com.br/api/v1/auth/mfa/verify \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}' | jq .
```

## Formato de Requisicao

| Parametro | Valor |
|-----------|-------|
| Content-Type | `application/json` |
| Encoding | UTF-8 |
| Formato de chaves | `snake_case` |
| Valores monetarios | Inteiros em centavos (ex: R$ 150,00 = 15000) |
| UUIDs | Formato padrao (ex: `550e8400-e29b-41d4-a716-446655440000`) |
| Datas | ISO 8601 (ex: `2026-02-13T14:30:00Z`) |

## Formato de Resposta

### Sucesso

```json
{
  "data": [...],
  "total": 100,
  "page": 1,
  "per_page": 20
}
```

### Erro (RFC 7807)

```json
{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "O campo 'amount' deve ser maior que zero",
  "instance": "/api/v1/payments"
}
```

## Paginacao

Todas as listas suportam paginacao via query parameters:

| Parametro | Tipo | Padrao | Descricao |
|-----------|------|--------|-----------|
| `page` | integer | 1 | Numero da pagina |
| `per_page` | integer | 20 | Itens por pagina (max: 100) |

```bash
curl -s -b cookies.txt \
  "https://pixapi-dev.fluxiq.com.br/api/v1/transactions?page=2&per_page=50" | jq .total
```

## Rate Limiting

| Endpoint | Limite | Janela | Chave |
|----------|--------|--------|-------|
| POST /api/v1/auth/login | 10 requisicoes | 15 minutos | IP do cliente |
| POST /api/v1/auth/mfa/verify | 10 requisicoes | 15 minutos | IP do cliente |
| Demais endpoints | Sem limite fixo | - | - |

Resposta quando rate limit atingido:

```json
{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Try again in 543 seconds."
}
```

## Idempotencia

Endpoints POST que criam recursos suportam o header `Idempotency-Key`:

```bash
curl -s -b cookies.txt \
  -X POST https://pixapi-dev.fluxiq.com.br/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: ${CSRF}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount": 15000, "creditor_key": "12345678901"}' | jq .
```

| Situacao | Comportamento |
|----------|--------------|
| Primeira requisicao | Processa normalmente, cacheia resposta (24h TTL) |
| Replay com mesmo body | Retorna resposta cacheada (HTTP 200) |
| Replay com body diferente | HTTP 422 "Idempotency key conflict" |
| Apos 24h | Chave expirada, processa como nova requisicao |

## Grupos de Endpoints

### Auth (Autenticacao)

| Metodo | Path | Descricao |
|--------|------|-----------|
| POST | `/api/v1/auth/login` | Login com usuario/senha |
| POST | `/api/v1/auth/logout` | Logout (blacklist token) |
| GET | `/api/v1/auth/public-key` | Chave publica RSA para criptografia |
| GET | `/api/v1/auth/me` | Dados do usuario autenticado |
| POST | `/api/v1/auth/mfa/setup` | Configurar MFA (TOTP) |
| POST | `/api/v1/auth/mfa/verify` | Verificar codigo MFA |

### Transacoes

```bash
# Listar transacoes
curl -s -b cookies.txt \
  "https://pixapi-dev.fluxiq.com.br/api/v1/transactions?status=STLD&page=1&per_page=20" | jq .

# Saida:
# {
#   "data": [
#     {
#       "id": "uuid...",
#       "end_to_end_id": "E1234567820260213143000001",
#       "status": "STLD",
#       "amount": 15000,
#       "message_type": "pacs.008",
#       "direction": "OUTBOUND",
#       "operation_time": "2026-02-13T14:30:00Z",
#       "settlement_time": "2026-02-13T14:30:01.200Z"
#     }
#   ],
#   "total": 4521,
#   "page": 1,
#   "per_page": 20
# }
```

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v1/transactions` | Listar transacoes (filtros: status, e2e_id, date_from, date_to, instrument_type) |
| GET | `/api/v1/transactions/:id` | Detalhes de uma transacao |
| POST | `/api/v1/transactions` | Criar nova transacao |
| GET | `/api/v1/transactions/:id/history` | Historico de status (message_history) |
| GET | `/api/v1/transactions/summary` | Estatisticas agregadas |
| GET | `/api/v1/transactions/export` | Exportar CSV |

### Pagamentos (Alias)

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v1/payments` | Listar pagamentos |
| POST | `/api/v1/payments` | Criar pagamento PIX (suporta Idempotency-Key) |
| GET | `/api/v1/payments/:id` | Detalhes do pagamento |

```bash
# Criar pagamento PIX
curl -s -b cookies.txt \
  -X POST https://pixapi-dev.fluxiq.com.br/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: ${CSRF}" \
  -H "Idempotency-Key: pay-$(uuidgen)" \
  -d '{
    "amount": 15000,
    "creditor_key": "12345678901",
    "debtor_account": "12345678",
    "remittance_info": "Pagamento referente a NF 12345"
  }' | jq .

# Saida:
# {
#   "id": "uuid...",
#   "end_to_end_id": "E1234567820260213143000001",
#   "status": "PDNG",
#   "amount": 15000,
#   "created_at": "2026-02-13T14:30:00Z"
# }
```

### DICT (Chaves PIX)

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v1/keys` | Listar chaves PIX |
| POST | `/api/v1/keys` | Registrar nova chave |
| GET | `/api/v1/keys/:key` | Consultar chave |
| DELETE | `/api/v1/keys/:key` | Remover chave |

```bash
# Consultar chave PIX
curl -s -b cookies.txt \
  "https://pixapi-dev.fluxiq.com.br/api/v1/keys/12345678901" | jq .

# Saida:
# {
#   "key_type": "CPF",
#   "key_value": "12345678901",
#   "owner_name": "Joao da Silva",
#   "owner_ispb": "12345678",
#   "account": {
#     "branch": "0001",
#     "number": "12345-6",
#     "type": "CACC"
#   }
# }
```

### Claims (Reivindicacoes)

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v2/claims` | Listar reivindicacoes |
| POST | `/api/v2/claims` | Criar reivindicacao |
| GET | `/api/v2/claims/:id` | Detalhes da reivindicacao |
| PUT | `/api/v2/claims/:id/respond` | Responder reivindicacao |
| PUT | `/api/v2/claims/:id/cancel` | Cancelar reivindicacao |

### Infraction Reports (MED 2.0)

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v2/infraction-reports` | Listar relatorios de infracao |
| GET | `/api/v2/infraction-reports/:id` | Detalhes do relatorio |
| PUT | `/api/v2/infraction-reports/:id/acknowledge` | Confirmar recebimento |
| PUT | `/api/v2/infraction-reports/:id/analyse` | Analisar (AGREED/DISAGREED) |
| PUT | `/api/v2/infraction-reports/:id/close` | Fechar relatorio |

```bash
# Listar infraction reports
curl -s -b cookies.txt \
  "https://pixapi-dev.fluxiq.com.br/api/v2/infraction-reports?status=OPEN" | jq .

# Analisar um report
curl -s -b cookies.txt \
  -X PUT "https://pixapi-dev.fluxiq.com.br/api/v2/infraction-reports/uuid.../analyse" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: ${CSRF}" \
  -d '{"result": "AGREED", "details": "Fraude confirmada"}' | jq .
```

### Settlement (Liquidacao)

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v1/settlement/netting` | Resultados de netting |
| GET | `/api/v1/settlement/reconciliation` | Reconciliacao |
| GET | `/api/v1/settlement/fees` | Tarifas |

### Contabilidade

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v1/accounting/chart-of-accounts` | 44 contas COSIF (BCB 4010) |
| GET | `/api/v1/accounting/journal-entries` | Lancamentos contabeis |
| GET | `/api/v1/accounting/events` | Eventos contabeis |
| POST | `/api/v1/accounting/events` | Criar evento (auto-cria lancamento) |
| GET | `/api/v1/accounting/cost-centers` | Centros de custo |
| POST | `/api/v1/accounting/cost-centers` | Criar centro de custo |
| PUT | `/api/v1/accounting/cost-centers/:id` | Atualizar centro de custo |
| POST | `/api/v1/accounting/cost-centers/:id/toggle-status` | Ativar/desativar |

```bash
# Listar plano de contas COSIF
curl -s -b cookies.txt \
  "https://pixapi-dev.fluxiq.com.br/api/v1/accounting/chart-of-accounts" | jq '.data | length'
# Saida: 44
```

### Monitoramento

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/health` | Health check geral |
| GET | `/api/v1/monitoring/health` | Health detalhado (servicos + infra) |
| GET | `/api/v1/monitoring/metrics` | Metricas BEAM VM |
| GET | `/api/v1/monitoring/alerts` | Alertas de infraestrutura |
| GET | `/metrics` | Metricas Prometheus |

### Configuracao do Sistema

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v1/system/config` | Listar parametros (filtro: category, search) |
| PUT | `/api/v1/system/config/:key` | Atualizar parametro |
| GET | `/api/v1/config/parameters` | Parametros de configuracao |
| GET | `/api/v1/config/schedules` | Agendamentos |
| GET | `/api/v1/config/categories` | Categorias de configuracao |

### Seguranca

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v1/security/policies` | Politicas de seguranca |
| PUT | `/api/v1/security/policies/:key` | Atualizar politica |
| GET | `/api/v1/security/settings` | Configuracoes de seguranca |

### Auditoria

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v1/audit/logs` | Logs de auditoria |
| GET | `/api/v1/audit/logs/export` | Exportar CSV |
| GET | `/api/v1/audit/event-types` | Tipos de evento |

### Simulador BACEN

| Metodo | Path | Descricao |
|--------|------|-----------|
| GET | `/api/v1/simulator/status` | Status do simulador |
| POST | `/api/v1/simulator/config` | Configurar simulador |
| POST | `/api/v1/simulator/process` | Processar mensagem |
| POST | `/api/v1/simulator/inbound` | Simular recebimento |
| GET | `/api/v1/simulator/scenarios` | Cenarios disponiveis |
| GET | `/api/v1/simulator/test-runs` | Historico de execucoes |
| GET | `/api/v1/simulator/exchanges` | Troca de mensagens |

```bash
# Verificar status do simulador
curl -s -b cookies.txt \
  "https://pixapi-dev.fluxiq.com.br/api/v1/simulator/status" | jq .

# Saida:
# {
#   "enabled": true,
#   "scenarios": 8,
#   "test_runs": 15,
#   "last_run": "2026-02-13T14:00:00Z"
# }
```

## Codigos de Status HTTP

| Codigo | Significado | Quando |
|--------|------------|--------|
| 200 | OK | Requisicao bem-sucedida |
| 201 | Created | Recurso criado com sucesso |
| 400 | Bad Request | Formato de requisicao invalido |
| 401 | Unauthorized | Nao autenticado ou token expirado |
| 403 | Forbidden | Sem permissao (RBAC) |
| 404 | Not Found | Recurso nao encontrado |
| 409 | Conflict | Conflito (ex: chave PIX ja existe) |
| 422 | Unprocessable Entity | Validacao falhou |
| 429 | Too Many Requests | Rate limit excedido |
| 500 | Internal Server Error | Erro interno do servidor |
| 502 | Bad Gateway | Servico downstream indisponivel |
| 503 | Service Unavailable | Circuit breaker aberto |

## Resultado Esperado

Ao utilizar esta referencia, voce sera capaz de:

- Autenticar-se na API via HttpOnly cookies com CSRF protection
- Navegar por todos os grupos de endpoints (auth, transacoes, DICT, settlement, contabilidade, monitoramento)
- Construir requisicoes com o formato correto (JSON, snake_case, centavos)
- Tratar erros seguindo o padrao RFC 7807
- Implementar idempotencia para operacoes de criacao
- Respeitar limites de rate limiting nos endpoints de autenticacao