Template .cursorrules

# Regras de Integração Pagou

Este projeto integra com a API de pagamentos Pagou.ai.

## Configuração da API

- Sandbox: https://api-sandbox.pagou.ai
- Produção: https://api.pagou.ai
- Documentação: https://developer.pagou.ai
- OpenAPI: https://developer.pagou.ai/api-reference/openapi-v2.json

## Autenticação

Use um destes métodos:
- Bearer token: `Authorization: Bearer <PAGOU_API_KEY>`
- Header API key: `apiKey: <PAGOU_API_KEY>`
- Basic auth: username=token, password=x

## Referência de Endpoints

### Pagamentos
- POST /v2/transactions - Criar pagamento (Pix ou cartão)
- GET /v2/transactions/{id} - Buscar transação
- PUT /v2/transactions/{id}/refund - Reembolsar transação

### Transferências
- POST /v2/transfers - Criar transferência Pix Out
- GET /v2/transfers/{id} - Buscar transferência
- POST /v2/transfers/{id}/cancel - Cancelar transferência

### Clientes
- POST /v2/customers - Criar cliente
- GET /v2/customers/{id} - Buscar cliente

## Criação de Pagamento

Request de pagamento Pix:
```json
{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "buyer": {
    "name": "Nome do Cliente",
    "email": "cliente@example.com",
    "document": { "type": "CPF", "number": "12345678901" }
  }
}
```

Request de pagamento com cartão (com token do Payment Element):
```json
{
  "external_ref": "order_1001",
  "amount": 2490,
  "currency": "BRL",
  "method": "credit_card",
  "token": "<token_do_payment_element>",
  "installments": 1
}
```

## Criação de Transferência

```json
{
  "pix_key_type": "EMAIL",
  "pix_key_value": "destinatario@example.com",
  "amount": 1200,
  "description": "Pagamento",
  "external_ref": "payout_1001"
}
```

Valores de pix_key_type: CPF, CNPJ, EMAIL, PHONE, EVP

## Enums de Status

Transação: pending, paid, expired, failed, refunded, partially_refunded, chargedback
Transferência: pending, in_analysis, processing, paid, error, cancelled

## Eventos de Webhook

Eventos de pagamento (em data.event_type):
- transaction.created, transaction.pending, transaction.paid
- transaction.cancelled, transaction.refunded, transaction.chargedback
- transaction.three_ds_required

Eventos de transferência (em type no topo):
- payout.created, payout.in_analysis, payout.processing
- payout.transferred, payout.failed, payout.canceled

## SDK TypeScript

```ts
import { Client } from "@pagouai/api-sdk";

const client = new Client({
  apiKey: process.env.PAGOU_API_KEY!,
  environment: "sandbox",
});
```

## Regras de Código

Ao escrever código de integração Pagou:

1. Sempre incluir external_ref em requests de pagamento/transferência
2. Usar header requestId para rastreamento de requisições
3. Deduplicar webhooks pelo id do evento no topo
4. Tratar 3DS verificando next_action em respostas de pagamento com cartão
5. Reconciliar estado com endpoints GET, não fazer retry de POSTs falhos
6. Nunca manipular números de cartão brutos - usar tokens do Payment Element
7. Confirmar webhooks com { "received": true }
8. Armazenar id da transação/transferência junto com seu external_ref

## Tratamento de Erros

- 400: Erro de validação - verificar corpo da requisição
- 401: API key inválida
- 404: Recurso não encontrado
- 409: external_ref duplicado (usar GET para buscar existente)
- 429: Rate limited - implementar backoff
- 500+: Erro do servidor - seguro fazer retry com chave de idempotência

## Payment Element (Cartões)

Script frontend: https://js.pagou.ai/payments/v3.js

```js
const elements = Pagou.elements({
  publicKey: "pk_sandbox_...",
  locale: "pt-BR",
  origin: window.location.origin,
});

const card = elements.create("card", { theme: "default" });
card.mount("#card-element");

const result = await elements.submit({
  createTransaction: async (tokenData) => {
    // Chamar seu backend com tokenData.token
  },
});
```