Template .cursorrules

# Regras de Integração Pagou

Este projeto integra com a API Pagou.ai para pagamentos, assinaturas, transferências e webhooks.

## Configuração da API

- Sandbox: https://api-sandbox.pagou.ai
- Produção: https://api.pagou.ai
- Docs rápidas: https://developer.pagou.ai/llms.txt
- Docs completas: https://developer.pagou.ai/llms-full.txt
- 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

Mantenha chaves secretas apenas no servidor. Use variáveis de ambiente. Nunca exponha uma chave secreta Pagou no navegador.

## Referência de Endpoints

### Pagamentos
- POST /v2/transactions - Criar pagamento (Pix, voucher 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

### Assinaturas
- POST /v2/subscriptions - Criar assinatura
- GET /v2/subscriptions - Listar assinaturas
- GET /v2/subscriptions/{id} - Buscar assinatura
- PATCH /v2/subscriptions/{id} - Atualizar assinatura
- POST /v2/subscriptions/{id}/cancel - Cancelar assinatura

## 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
}
```

Request de pagamento por voucher:
```json
{
  "external_ref": "order_3001",
  "amount": 125000,
  "currency": "MXN",
  "method": "voucher",
  "buyer": {
    "name": "Nome do Cliente",
    "email": "cliente@example.com",
    "address": {
      "street": "Av. Paseo de la Reforma",
      "city": "Cidade do Mexico",
      "zipCode": "06600",
      "country": "MX"
    }
  },
  "products": [{ "name": "Plano anual", "price": 125000, "quantity": 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

## Criação de Assinatura

Crie assinaturas pelo back-end depois que o navegador retornar um token do Payment Element:

```json
{
  "customer_id": "cus_1001",
  "token": "pgct_...",
  "amount": 4990,
  "currency": "BRL",
  "interval": "month",
  "interval_count": 1,
  "external_ref": "sub_1001"
}
```

## Enums de Status

Transação: pending, paid, expired, canceled, refused, refunded, partially_refunded, chargedback
Assinatura: trialing, active, past_due, cancel_scheduled, canceled
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

Eventos de assinatura (event=subscription, evento concreto em data.event_type):
- subscription.created, subscription.started, subscription.renewed
- subscription.updated, subscription.canceled, subscription.payment_failed
- subscription.past_due, subscription.trial_will_end, subscription.chargeback_received

## 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 inclua external_ref em requests de pagamento, assinatura e transferência
2. Use idempotência em criações, reembolsos, ações de assinatura, transferências e cancelamentos
3. Use requestId para rastreamento quando a API retornar
4. Deduplique webhooks pelo id do evento no topo
5. Roteie pagamentos por event=transaction + data.event_type
6. Roteie assinaturas por event=subscription + data.event_type
7. Roteie transferências pelo type no topo
8. Trate 3DS verificando next_action em respostas de pagamento com cartão
9. Reconcilie estado com endpoints GET apenas para suporte, recuperação ou estado incerto
10. Nunca use polling como fluxo principal
11. Nunca manipule números de cartão brutos - use tokens do Payment Element
12. Confirme webhooks rapidamente com { "received": true }
13. Armazene id da transação/assinatura/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 - faça retry com backoff apenas quando a escrita for idempotente

## Payment Element (Cartões)

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

```js
const elements = Pagou.elements({
  publicKey: "pk_test_...",
  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
  },
});
```