Windsurf

# Regras API Owem

## Contexto

Projeto de integração com a API Owem para pagamentos PIX.

- **Docs**: https://docs.owem.com.br
- **LLMs.txt**: https://docs.owem.com.br/llms.txt
- **API**: https://api.owem.com.br
- **Auth**: Basic Auth (API_KEY:API_SECRET em Base64)

## Endpoints

### PIX IN

- `POST /v4/i/pix/in/dynamic-qrcode` - Gerar QR
- `GET /v4/i/pix/in/dynamic-qrcode/{txId}` - Consultar
- `POST /v4/i/pix/in/refund/{e2e}` - Estornar

### PIX OUT

- `POST /v4/i/bank-accounts/{id}/transfer/external` - Transferir
- `GET /v4/i/bank-accounts/{id}/transfer/external/{e2e}` - Consultar

### Ledger

- `GET /v4/i/ledger` - Listar
- `GET /v4/i/ledger/external-id/{id}` - Por ID externo
- `GET /v4/i/ledger/end-to-end/{e2e}` - Por E2E

### Conta

- `GET /v4/i/bank-accounts/{id}/balance` - Saldo

## Padrões

### Autenticação

```javascript
const token = Buffer.from(`${API_KEY}:${API_SECRET}`).toString('base64');
headers: { 'Authorization': `Basic ${token}` }
```

### Resposta de Erro

```json
{ "success": false, "status": 400, "message": "erro" }
```

## Webhooks

| Evento               | Descrição        |
| -------------------- | ---------------- |
| `pix_in:qrcode_paid` | QR pago          |
| `pix_out:succeeded`  | Transferência OK |
| `med:created`        | Disputa criada   |

IPs permitidos: 34.134.50.53, 35.238.101.57

## Regras

1. Credenciais em env vars
2. Sempre HTTPS
3. Validar webhooks por IP
4. Usar externalId para idempotência
5. Tratar todos os erros