Template CLAUDE.md

# Integração Pagou

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

## 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 v2: https://developer.pagou.ai/api-reference/openapi-v2.json

## Autenticação

Escolha um método:
- `Authorization: Bearer <PAGOU_API_KEY>`
- Header `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.

## Regras principais

- Valide endpoints, campos, status e formatos de webhook no OpenAPI antes de codar
- Não invente endpoints, campos, status ou fluxos não documentados
- Valores na API v2 são em centavos
- Sempre inclua `external_ref` e idempotência em escritas
- Use Payment Element / SDK v3 para cartões; envie ao back-end apenas tokens `pgct_`
- Implemente webhooks reais, deduplique pelo id do evento no topo e processe de forma assíncrona
- Use polling/GET apenas para reconciliação, suporte ou recuperação, nunca como fluxo principal

## Pagamentos

### Criar pagamento Pix
```
POST /v2/transactions
{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "buyer": {
    "name": "Nome do Cliente",
    "email": "cliente@example.com",
    "document": { "type": "CPF", "number": "12345678901" }
  }
}
```

Resposta inclui `pix_qr_code` (base64) e `pix_code` (string).

### Criar pagamento com cartão
```
POST /v2/transactions
{
  "external_ref": "order_1001",
  "amount": 2490,
  "currency": "BRL",
  "method": "credit_card",
  "token": "<token_do_payment_element>",
  "installments": 1
}
```

Pagamentos com cartão requerem Payment Element no navegador para tokenizar dados do cartão.

### Status de transações
pending → paid | expired | canceled | refused | refunded | partially_refunded | chargedback

## Assinaturas

Crie cobrança recorrente com cartão pelo back-end depois que o navegador retornar um token do Payment Element:

```
POST /v2/subscriptions
{
  "customer_id": "018f1f2e-7b46-7c9a-8d3e-1a2b3c4d5e73",
  "token": "pgct_...",
  "amount": 4990,
  "currency": "BRL",
  "interval": "month",
  "interval_count": 1,
  "external_ref": "sub_1001"
}
```

Use webhooks de assinatura para conceder, renovar, pausar ou remover acesso. Reconcilie estado incerto com `GET /v2/subscriptions/{id}`.

### Status de assinaturas
trialing → active | past_due | cancel_scheduled | canceled

## Transferências (Pix Out)

```
POST /v2/transfers
{
  "pix_key_type": "EMAIL",
  "pix_key_value": "destinatario@example.com",
  "amount": 1200,
  "description": "Descrição do pagamento",
  "external_ref": "payout_1001"
}
```

pix_key_type: CPF, CNPJ, EMAIL, PHONE, EVP

### Status de transferências
pending → in_analysis → processing → paid | error | cancelled

## Webhooks

### Estrutura de evento de pagamento
```json
{
  "id": "evt_pay_1001",
  "event": "transaction",
  "data": {
    "event_type": "transaction.paid",
    "id": "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
    "status": "paid",
    "correlation_id": "order_1001"
  }
}
```

### Estrutura de evento de transferência
```json
{
  "id": "evt_payout_1001",
  "type": "payout.transferred",
  "data": {
    "object": {
      "id": "018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72",
      "status": "paid"
    }
  }
}
```

### Estrutura de evento de assinatura
```json
{
  "id": "evt_sub_1001",
  "event": "subscription",
  "data": {
    "event_type": "subscription.created",
    "id": "018f1f2e-7b47-7c9a-8d3e-1a2b3c4d5e74",
    "status": "active",
    "customer_email": "customer@example.com"
  }
}
```

### Eventos de pagamento
- transaction.created
- transaction.pending
- transaction.paid
- transaction.cancelled
- transaction.refunded
- transaction.chargedback
- transaction.three_ds_required

### Eventos de assinatura
- subscription.created
- subscription.started
- subscription.renewed
- subscription.updated
- subscription.canceled
- subscription.payment_failed
- subscription.past_due
- subscription.trial_will_end
- subscription.chargeback_received

### Eventos de transferência
- payout.created
- payout.in_analysis
- payout.processing
- payout.transferred
- payout.failed
- payout.canceled

## SDK TypeScript

```bash
bun add @pagouai/api-sdk
```

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

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

// Pagamento Pix
const tx = await client.transactions.create({
  external_ref: "order_1001",
  amount: 1500,
  currency: "BRL",
  method: "pix",
});

// Transferência
const transfer = await client.transfers.create({
  pix_key_type: "EMAIL",
  pix_key_value: "destinatario@example.com",
  amount: 1200,
  external_ref: "payout_1001",
});
```

## Regras

- Sempre inclua `external_ref` para correlação e idempotência
- Use `requestId` para rastreamento quando a API retornar
- Deduplique webhooks pelo id do evento no topo, não pelo id da transação, assinatura ou transferência
- Roteie pagamentos por `event="transaction"` + `data.event_type`
- Roteie assinaturas por `event="subscription"` + `data.event_type`
- Roteie transferências pelo `type` no topo
- Reconcilie estados incertos com GET; não use polling como fluxo principal
- Cartões requerem Payment Element; nunca manipule dados brutos de cartão
- Confirme webhooks rapidamente com `{ "received": true }`

## Erros comuns a evitar

- Fazer retry de POST em falha (usar GET para reconciliar)
- Deduplicar webhooks por id do recurso (o mesmo recurso emite múltiplos eventos)
- Pular external_ref (impossibilita reconciliação)
- Manipular números de cartão brutos (usar tokens do Payment Element)
- Ignorar next_action em fluxos 3DS
- Atualizar pedido, acesso ou payout por sucesso no browser em vez de webhook confirmado ou estado reconciliado no servidor