Windsurf

# Owem API Rules

## Context

Integration project with the Owem API for PIX payments.

- **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 in Base64)

## Endpoints

### PIX IN

- `POST /v4/i/pix/in/dynamic-qrcode` - Generate QR
- `GET /v4/i/pix/in/dynamic-qrcode/{txId}` - Query
- `POST /v4/i/pix/in/refund/{e2e}` - Refund

### PIX OUT

- `POST /v4/i/bank-accounts/{id}/transfer/external` - Transfer
- `GET /v4/i/bank-accounts/{id}/transfer/external/{e2e}` - Query

### Ledger

- `GET /v4/i/ledger` - List
- `GET /v4/i/ledger/external-id/{id}` - By external ID
- `GET /v4/i/ledger/end-to-end/{e2e}` - By E2E

### Account

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

## Patterns

### Authentication

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

### Error Response

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

## Webhooks

| Event                | Description     |
| -------------------- | --------------- |
| `pix_in:qrcode_paid` | QR paid         |
| `pix_out:succeeded`  | Transfer OK     |
| `med:created`        | Dispute created |

Allowed IPs: 34.134.50.53, 35.238.101.57

## Rules

1. Credentials in env vars
2. Always HTTPS
3. Validate webhooks by IP
4. Use externalId for idempotency
5. Handle all errors