---
name: clickpay-sdk
description: Guia para integração com a plataforma de pagamentos ClickPay usando o SDK oficial @clickpay/sdk para JavaScript/TypeScript. Este skill deve ser usado quando o usuário quiser integrar pagamentos PIX, links de pagamento, gestão de clientes, webhooks ou operações de conta via API ClickPay em qualquer ambiente JavaScript (Node.js, NestJS, Next.js, browser, etc.).
---

# Integração ClickPay SDK

Fornecer código de integração para a plataforma de pagamentos ClickPay usando o pacote oficial `@clickpay/sdk`. ClickPay é uma plataforma brasileira de pagamentos focada em PIX, QR codes e links de pagamento.

## Quando Usar

Aplicar este skill quando:

- Integrar pagamentos ClickPay em um projeto JavaScript/TypeScript
- Criar cobranças PIX (QR Code ou PIX estático)
- Construir fluxos de link de pagamento
- Gerenciar clientes ou produtos via ClickPay
- Configurar webhooks para notificações de pagamento
- Realizar operações de conta (saldo, saques)
- Resolver erros do SDK ClickPay

## Visão Geral do SDK

Pacote: `@clickpay/sdk`
URL base da API: `https://api.clickpay.app.br`
Autenticação: chave de API passada no construtor do SDK
Chaves sandbox: prefixo `cpk_sandbox_`
Chaves de produção: prefixo `cpk_prod_` (requer validação de documentos)

Todos os valores monetários são em **centavos** (inteiros). R$50,00 = `5000`. Valor mínimo de cobrança: `500` (R$5,00).

### Instalação

```bash
npm install @clickpay/sdk
```

### Inicialização

```typescript
import { ClickPay } from '@clickpay/sdk';

const clickpay = new ClickPay({
  apiKey: process.env.CLICKPAY_API_KEY, // cpk_sandbox_... ou cpk_prod_...
});
```

## Fluxos Principais

### 1. Cobrança PIX (QR Code)

Para criar uma cobrança PIX direta que retorna um QR code e código copia-e-cola:

```typescript
const pix = await clickpay.charges.createPixCharge({
  amount: 1500, // R$15,00
  customer: {
    taxId: '12345678900',
    name: 'Maria Santos',
    email: 'maria@email.com',
    phone: '11988888888',
  },
  expiresIn: 900, // segundos (15 min)
});

// pix.data?.brCode       → string PIX copia-e-cola
// pix.data?.brCodeBase64 → imagem QR Code em base64
```

### 2. Link de Pagamento

Para criar um link de pagamento (página de checkout hospedada):

```typescript
const charge = await clickpay.charges.createPaymentLink({
  total: 5000, // R$50,00
  customer: {
    taxId: '12345678900',
    name: 'João Silva',
    email: 'joao@email.com',
    phone: '11999999999',
  },
  successUrl: 'https://meusite.com/sucesso',
  failedUrl: 'https://meusite.com/falha',
  items: [
    { productId: 'prod_abc123', quantity: 2 },
  ],
});

// charge.data?.url → URL da página de pagamento
```

### 3. Consultar Status da Cobrança

```typescript
const charge = await clickpay.charges.getById('charge_id');

// charge.data?.status        → OPEN | COMPLETED | EXPIRED
// charge.data?.paymentStatus → PENDING | PROCESSING | PAID | EXPIRED
```

### 4. Gerar PIX para Link de Pagamento Existente

Para gerar uma opção de pagamento PIX para uma cobrança já criada via link de pagamento:

```typescript
const pixPayment = await clickpay.charges.generatePixForCharge('charge_id', {
  customer: {
    taxId: '12345678900',
    name: 'João Silva',
    email: 'joao@email.com',
    phone: '11999999999',
  },
});
```

### 5. Simular Pagamento (Apenas Sandbox)

Para testar o fluxo completo de pagamento sem transações reais. Funciona apenas para cobranças criadas com `devMode: true`:

```typescript
await clickpay.charges.simulatePayment('charge_id');
```

### 6. Idempotência

A criação de cobranças suporta chaves de idempotência (UUID v4, TTL 24h) para evitar cobranças duplicadas:

```typescript
const charge = await clickpay.charges.createPixCharge(
  { amount: 5000, customer: { /* ... */ } },
  { idempotencyKey: 'f47ac10b-58cc-4372-a567-0e02b2c3d479' },
);
```

### 7. Gestão de Clientes

```typescript
import { DefaultStatus } from '@clickpay/sdk';

// Listar todos
const customers = await clickpay.customers.list();

// Buscar por ID
const customer = await clickpay.customers.getById('cust_abc123');

// Criar
const newCustomer = await clickpay.customers.create({
  name: 'João Silva',
  taxId: '12345678900',
  email: 'joao@email.com',
  phone: '11999999999',
  status: DefaultStatus.ACTIVE,
  postalCode: '01001000',
  address: 'Praça da Sé',
  number: '1',
  district: 'Sé',
});

// Atualizar
await clickpay.customers.update({
  id: 'cust_abc123',
  phone: '11977777777',
  status: DefaultStatus.INACTIVE,
});
```

### 8. Gestão de Produtos

```typescript
import { DefaultStatus } from '@clickpay/sdk';

const products = await clickpay.products.list({ status: DefaultStatus.ACTIVE });
const product = await clickpay.products.getById('prod_abc123');
const productBySku = await clickpay.products.getBySku('PLAN-MONTHLY');

const newProduct = await clickpay.products.create({
  name: 'Plano Mensal',
  description: 'Assinatura mensal do serviço',
  price: 4990, // R$49,90
  sku: 'PLAN-MONTHLY',
});

await clickpay.products.update({ id: 'prod_abc123', price: 5990 });
```

### 9. Webhooks

```typescript
import { WebhookEvent } from '@clickpay/sdk';

const webhooks = await clickpay.webhooks.list();

const webhook = await clickpay.webhooks.create({
  name: 'Notificações de Pagamento',
  url: 'https://meusite.com/webhooks/clickpay',
  events: [WebhookEvent.CHARGE_PAID, WebhookEvent.CHARGE_EXPIRED],
});

await clickpay.webhooks.update({
  id: 'wh_abc123',
  events: [WebhookEvent.CHARGE_PAID],
});

await clickpay.webhooks.delete('wh_abc123');

const events = await clickpay.webhooks.listEvents();
const stats = await clickpay.webhooks.getQueueStats();
```

### 10. Conta (Saldo e Saques)

```typescript
const balance = await clickpay.account.getBalance();

const withdraw = await clickpay.account.withdraw({ value: 10000 }); // R$100,00

const withdrawals = await clickpay.account.listWithdrawals();
```

## Tratamento de Erros

Sempre envolver chamadas do SDK em try/catch. O SDK fornece classes de erro específicas:

| Classe de Erro | Quando Ocorre |
|---|---|
| `ClickPayApiError` | Erro genérico da API (classe base) |
| `ClickPayRateLimitError` | HTTP 429 — inclui `retryAfter` (segundos) |
| `ClickPayIdempotencyError` | Conflito de chave de idempotência |
| `ClickPayTimeoutError` | Requisição excedeu o timeout |
| `ClickPayNetworkError` | Falha de conexão/rede |

```typescript
import {
  ClickPayApiError,
  ClickPayRateLimitError,
  ClickPayIdempotencyError,
  ClickPayTimeoutError,
  ClickPayNetworkError,
} from '@clickpay/sdk';

try {
  await clickpay.charges.createPixCharge({ /* ... */ });
} catch (error) {
  if (error instanceof ClickPayRateLimitError) {
    // Tentar novamente após error.retryAfter segundos
  } else if (error instanceof ClickPayIdempotencyError) {
    // Conflito de chave — mesma chave usada com parâmetros diferentes
  } else if (error instanceof ClickPayTimeoutError) {
    // Aumentar timeout na configuração do cliente ou tentar novamente
  } else if (error instanceof ClickPayNetworkError) {
    // Verificar conectividade
  } else if (error instanceof ClickPayApiError) {
    // error.statusCode, error.message, error.body
  }
}
```

## Configuração Avançada

```typescript
const clickpay = new ClickPay({
  apiKey: 'cpk_sandbox_...',
  baseUrl: 'https://api.clickpay.app.br', // padrão
  sandbox: true,          // habilitar modo sandbox
  timeout: 15000,         // ms, padrão 30000
  maxRetries: 3,          // retentativa automática em 429/5xx, padrão 2
  headers: {},            // headers HTTP adicionais
  fetch: customFetch,     // fetch customizado para Node.js < 18
});
```

| Opção | Tipo | Padrão | Descrição |
|---|---|---|---|
| `apiKey` | `string` | — | Chave de API para autenticação **(obrigatório)** |
| `baseUrl` | `string` | `https://api.clickpay.app.br` | URL base da API |
| `sandbox` | `boolean` | `false` | Habilita ambiente sandbox |
| `timeout` | `number` | `30000` | Timeout das requisições em milissegundos |
| `maxRetries` | `number` | `2` | Número máximo de retentativas em erros 429/5xx |
| `headers` | `object` | `{}` | Headers HTTP adicionais |
| `fetch` | `function` | `globalThis.fetch` | Implementação customizada de fetch |

## Tipos e Enums

Todos os tipos TypeScript são exportados de `@clickpay/sdk`:

**Tipos:** `Customer`, `CreateCustomerInput`, `ChargeDetail`, `CreatePixChargeInput`, `Product`, `Webhook`, `ClickPayResponse`

**Enums:**
- `DefaultStatus` → `ACTIVE | INACTIVE`
- `ChargeStatus` → `OPEN | COMPLETED | EXPIRED`
- `PaymentStatus` → `PENDING | PROCESSING | PAID | EXPIRED`
- `WebhookEvent` → `CHARGE_PAID | CHARGE_EXPIRED | ...`
- `WithdrawStatus` → valores de status de saque

## Compatibilidade

Node.js >= 18, Bun, Deno, Browser (ESM), NestJS, Next.js, React Native. Para Node.js < 18, fornecer uma implementação customizada de `fetch` (ex: `node-fetch` ou `undici`).

## Integração com NestJS

Consultar `references/nestjs-example.md` para um padrão completo de módulo/serviço NestJS usando injeção de dependência com o SDK ClickPay.

## Recursos Adicionais

- Dashboard ClickPay: https://admin.clickpay.app.br/
- Documentação da API: https://docs.clickpay.app.br/pages/introduction
- Documentação do SDK: https://docs.clickpay.app.br/pages/resources