Skip to main content
Use o Cursor para acelerar sua integração com a API Owem. Este guia mostra como configurar o Cursor para escrever código que consome a API de pagamentos PIX.

​
Pré-requisitos

  • Cursor instalado
  • Credenciais da API Owem (API Key + Secret)
  • Projeto configurado (Node.js, Python, ou outra linguagem)

​
Configuração de Regras

Crie regras de projeto para que o Cursor entenda a API Owem. Na raiz do seu projeto: 
mkdir -p .cursor
Crie o arquivo .cursor/rules.md: 
# Regras para API Owem

Você é um assistente especializado em integrar aplicações com a API Owem de pagamentos PIX.

## Contexto da API Owem

- **Base URL**: `https://api.owem.com.br`
- **Autenticação**: Basic Auth com `API_KEY:API_SECRET` em Base64
- **Documentação**: https://docs.owem.com.br

## Endpoints Principais

### PIX IN (Recebimentos)

- `POST /v4/i/pix/in/dynamic-qrcode` - Gerar QR Code dinâmico
- `GET /v4/i/pix/in/dynamic-qrcode/{txId}` - Consultar QR Code
- `POST /v4/i/pix/in/refund/{endToEndId}` - Estornar PIX
- `GET /v4/i/pix/in/refund/{endToEndId}` - Consultar estorno

### PIX OUT (Pagamentos)

- `POST /v4/i/bank-accounts/{accountId}/transfer/external` - Transferência PIX
- `GET /v4/i/bank-accounts/{accountId}/transfer/external/{endToEnd}` - Consultar transferência

### Ledger (Extrato)

- `GET /v4/i/ledger` - Listar movimentações
- `GET /v4/i/ledger/external-id/{externalId}` - Buscar por ID externo
- `GET /v4/i/ledger/end-to-end/{endToEndId}` - Buscar por E2E
- `GET /v4/i/ledger/entry-id/{entryId}` - Buscar por Entry ID

### Webhooks

- `POST /v4/i/webhooks/config` - Criar webhook
- `GET /v4/i/webhooks/config` - Listar webhooks
- `PUT /v4/i/webhooks/config/{configId}` - Atualizar webhook
- `DELETE /v4/i/webhooks/config/{configId}` - Excluir webhook

## Padrões de Código

### Autenticação

Sempre use Basic Auth com o token em Base64:

```javascript
const token = Buffer.from(`${API_KEY}:${API_SECRET}`).toString("base64")
const headers = {
  Authorization: `Basic ${token}`,
  "Content-Type": "application/json",
}
```

### Tratamento de Erros

A API retorna erros no formato:

```json
{
  "requestId": "uuid",
  "success": false,
  "status": 400,
  "message": "Mensagem de erro",
  "code": "ERROR_CODE"
}
```

### Idempotência

Use `externalId` para garantir idempotência em transações:

```javascript
{
  "amount": 100.00,
  "pixKey": "[email protected]",
  "externalId": "pedido-12345" // Seu ID único
}
```

## Regras Importantes

1. **NUNCA** exponha API_KEY ou API_SECRET no código cliente
2. **SEMPRE** valide webhooks pelo IP de origem (34.134.50.53, 35.238.101.57)
3. **SEMPRE** use HTTPS
4. **SEMPRE** trate o campo `test: true` para ambiente de testes
5. Use `endToEndId` para rastrear transações PIX
6. Use `externalId` para correlacionar com seu sistema

## Eventos de Webhook

| Evento               | Descrição               |
| -------------------- | ----------------------- |
| `pix_in:qrcode_paid` | QR Code pago            |
| `pix_out:succeeded`  | Transferência concluída |
| `pix_out:failed`     | Transferência falhou    |
| `med:created`        | Nova disputa (MED)      |

​
Exemplo de Uso

Com as regras configuradas, você pode pedir ao Cursor:

Gerar QR Code

“Crie uma função para gerar QR Code PIX dinâmico com a API Owem”

Processar Webhook

“Crie um endpoint Express para receber webhooks da Owem”

Consultar Saldo

“Faça uma função para consultar o saldo da conta bancária”

Transferência PIX

“Implemente uma função para fazer transferência PIX OUT”

​
Dicas

Use o arquivo llms.txt da Owem em https://docs.owem.com.br/llms.txt para dar contexto extra ao Cursor sobre a API.
Nunca inclua credenciais reais em exemplos de código. Use variáveis de ambiente.