# Vitrin Digital — Referência completa para LLMs

> Este arquivo concentra tudo o que um modelo de linguagem precisa para entender a API da Vitrin Digital. É descritivo, não prescritivo — as decisões de produto, arquitetura e UX ficam com quem está construindo.

## Como usar este arquivo

1. **Claude / ChatGPT / Gemini**: cole o conteúdo inteiro no início da conversa, depois descreva sua tarefa. O modelo terá contexto completo de auth, endpoints, webhooks e exemplos.
2. **Cursor / Windsurf**: salve este arquivo no projeto e referencie no prompt (`@llms-full.txt`) ou adicione ao seu `.cursorrules`.
3. **Claude Code**: salve como `docs/vitrin-llm.md` e mencione no `CLAUDE.md` do projeto.

## Visão geral

A Vitrin é um intermediador de pagamentos brasileiro. A API REST cobre:

- **Pix instantâneo** — cobrança via QR Code com confirmação por webhook
- **Pix Automático** — recorrência nativa do Banco Central com aceite único do pagador
- **Boleto bancário** — cobrança com PDF + linha digitável
- **Cartão de crédito** — à vista ou parcelado em até 12x, via tokenização

Mais: clientes, planos, assinaturas, produtos, pedidos, antecipação, transferências, relatórios e webhooks. 59 endpoints públicos no total.

## Escopo: o que é API e o que é dashboard

A API REST cobre operações de comerciante: cobrar, listar transações, gerenciar produtos/planos/assinaturas, configurar webhooks (programaticamente após receber o secret), antecipar recebíveis, sacar saldo, gerar relatórios.

**O que NÃO está na API REST** (e não deve ser):

- **Cadastro de org** — feito em `vitrin.digital` pelo dono. Inclui upload de documentos do CNPJ/sócios e definição do PIN. Tudo interação humana.
- **Login JWT** — usado pelo dashboard web internamente. Integração via API usa apenas a API key (Bearer).
- **Definição/troca/reset de PIN e password** — sempre pelo dashboard. PIN protege ações destrutivas (refund, transfer, regenerate api-key) e nunca deve ser hardcoded em integração.
- **Assinatura de contratos** — exige scroll humano + PIN, é assinatura eletrônica avançada (MP 2.200-2). Feita em `/dashboard/contract`.
- **Upload de documentos de onboarding** — anexo de arquivo manual em `/dashboard/onboarding`.

A API expõe **endpoints read-only de status** para que sua aplicação possa checar se a org está liberada (`GET /onboarding/status/`, `GET /contracts/status/`) antes de tentar cobrar. Tentar cobrar antes de tudo aprovado retorna HTTP 403 com mensagem orientando para o dashboard.

**URL base de produção**: `https://api.vitrin.digital/api/v1`
**Sandbox**: o admin libera uma subconta sandbox isolada (chave `vd_test_...`) para testes ponta-a-ponta sem mover dinheiro real.
**Auth**: `Authorization: Bearer vd_live_<sua-key>` em todas as chamadas.
**Content-Type**: `application/json` em POST/PATCH/PUT.

## Convenções da API

- **Valores monetários**: strings decimais (`"99.90"`) — não centavos, não float
- **Datas**: ISO 8601 (`"2026-04-15"`)
- **IDs**: UUIDs em string
- **Listas**: paginadas com `{ count, next, previous, results }`, 50 items/página
- **Erros**: JSON com chave `error` ou `detail` + status HTTP padrão (400/401/403/404/429/500/502)
- **Encoding**: UTF-8

## Requisitos técnicos da plataforma

Os pontos abaixo são impostos pela API — não são opiniões de design:

1. **Tokenização de cartão obrigatória.** Dados de cartão (número, ccv) devem ser enviados ao endpoint `POST /checkout/tokenize/` que retorna um `credit_card_token`. Cobranças posteriores usam o token. Esse fluxo é necessário pela conformidade PCI da plataforma.

2. **Validação de assinatura de webhook.** O dono da org configura a URL e gera o secret no dashboard (`/dashboard/webhooks`). A Vitrin envia eventos para essa URL com header `X-Vitrin-Signature: sha256=<hex>` calculado como HMAC-SHA256 do body cru com o `webhook_secret`. Validar essa assinatura é necessário para confiar na origem do evento.

3. **PIN em operações sensíveis.** Refund, cancel, transfer, anticipation request e rotação de api-key exigem o PIN do dono da org no body da requisição. O PIN é definido no cadastro. Como expor a entrada do PIN ao usuário é decisão do integrador.

4. **Janela do BC para Pix Automático.** Cobranças recorrentes via Pix Automático devem ter `due_date` entre 2 e 10 dias úteis no futuro. Fora dessa janela, a chamada retorna HTTP 400.

5. **Hard block de contratos.** Antes da primeira cobrança, a org precisa ter assinado os 4 contratos comerciais (Termos, Anexo Comercial, Política de Chargebacks, LGPD). A assinatura é feita pelo dono no dashboard (`https://vitrin.digital/dashboard/contract`) com PIN — **não há endpoint REST para essa ação**. Sua aplicação pode checar via `GET /contracts/status/` antes de tentar cobrar.

6. **Hard block de onboarding.** Antes do primeiro saque, o onboarding documental precisa estar aprovado. Sua aplicação pode checar via `GET /onboarding/status/` se `account_status.general == "APPROVED"`. Upload de documentos é humano (no dashboard).

7. **Webhooks têm retry.** A Vitrin reentregará eventos não confirmados. Retorne 2xx rapidamente e processe o evento de forma assíncrona se necessário.

## Estados úteis para conhecer

- **Pix Automático** — uma autorização passa por `CREATED` (aguardando aceite) → `ACTIVE` (aceita, pode gerar cobranças) → eventualmente `CANCELLED` ou `EXPIRED`. O evento de webhook `PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED` indica quando a autorização ficou ativa. Alternativamente, `POST /pix-automatic/authorizations/{id}/sync/` força sync com o processador.
- **Transactions** — `pending` → `confirmed` → `received` (Pix/Boleto liquidado) → opcional `refunded` ou `chargeback`.
- **Onboarding** — orgs novas têm `status='onboarding'` até completar verificação documental. `GET /onboarding/status/` retorna o estado em tempo real.

## O que a referência abaixo cobre

O guia completo a seguir tem exemplos cURL para todos os fluxos, payloads de request/response, lista exaustiva de eventos de webhook, códigos de erro, prazos de liquidação e rate limits. Use-o como fonte de verdade para qualquer pergunta sobre a API.

---

## Guia de integração completo

# Vitrin Digital — Guia de Integração

> Integre pagamentos na sua aplicação em minutos. Checkout transparente, Pix, Pix Automático (recorrência via SPI/BC), boleto, cartão de crédito, assinaturas e produtos avulsos — tudo via API REST.

**Recursos**:
- 📖 [Swagger UI público](https://api.vitrin.digital/api/public/docs/) — explore interativamente
- 📦 [Schema OpenAPI](/openapi.json) — importe direto no Postman ou Insomnia
- 📜 Este guia — referência completa, passo a passo

---

## ⚡ Integre em 15 minutos

Os 5 passos abaixo cobrem o caso mais comum: **receber um pagamento Pix** e ser notificado quando ele for confirmado.

### 1. Cadastre-se e copie sua API key (humano, 2 min)

Cadastro, verificação documental e configuração do PIN são feitos no dashboard — não há cURL pra isso. Acesse:

**[vitrin.digital](https://vitrin.digital)** → **Criar conta** → preencha CNPJ, endereço e PIN → conclua o onboarding documental.

Após a aprovação, sua **API key** (`vd_live_...`) fica disponível em `/dashboard/settings/`. Substitua os `vd_live_...` dos exemplos abaixo pela sua chave real.

### 2. Assine os 4 contratos comerciais (humano, 3 min)

A primeira chamada de cobrança retorna **HTTP 403** enquanto os contratos não forem assinados. A assinatura é feita pelo dono da org no dashboard com PIN — não há endpoint REST pra isso (é exigido pela natureza da assinatura eletrônica).

Acesse `/dashboard/contract`, revise os 4 documentos e confirme com seu PIN.

> Sua aplicação pode checar programaticamente se a org está liberada via `GET /contracts/status/` antes de tentar cobrar — útil pra mostrar mensagem amigável no seu UI.

### 3. Crie um cliente (1 min)

```bash
curl -X POST https://api.vitrin.digital/api/v1/customers/ \
  -H "Authorization: Bearer vd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria da Silva",
    "email": "maria@exemplo.com",
    "cpf_cnpj": "12345678909",
    "phone": "11988776655"
  }'
```

Retorna `{ "id": "<customer_id>", ... }`.

### 4. Crie uma cobrança Pix (2 min)

```bash
curl -X POST https://api.vitrin.digital/api/v1/checkout/pix/ \
  -H "Authorization: Bearer vd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "<customer_id>",
    "amount": "99.90",
    "description": "Pedido #1234"
  }'
```

Retorna o `payment_id`, o **QR Code base64** (`qr_code`) e o **copia-cola** (`copy_paste`). Renderize isso na sua UI pro cliente final.

### 5. Configure o webhook e valide a assinatura (5 min)

Configure a URL HTTPS de webhook em `/dashboard/webhooks` (requer PIN). Quando o cliente pagar, a Vitrin envia:

```json
{
  "event": "PAYMENT_RECEIVED",
  "payment": { "id": "pay_xxx", "status": "received", "amount": "99.90" }
}
```

Valide a assinatura HMAC no header `X-Vitrin-Signature` (SHA256 do body com seu webhook secret) — código de exemplo na [seção 5](#5-webhooks). É só. Você está integrado.

---

## Próximos passos

Depois desses 5 passos, você provavelmente vai querer:

- **Boleto** ou **cartão de crédito** → seção [3.2](#32-boleto) e [3.3](#33-cartão-de-crédito)
- **Cobrança recorrente** → [Pix Automático](#36-pix-automático-recorrência-via-spibc) ou [Assinaturas](#6-assinaturas)
- **Antecipar recebíveis** → endpoints `/anticipations/`
- **Sacar saldo** → seção [9](#9-saldo-e-transferências)

---

## 1. Primeiros Passos

### Cadastro e API key (humano, no dashboard)

Cadastro, verificação documental, definição do PIN e geração da primeira API key são feitos no dashboard web — não há endpoint REST pra essas ações. Isso é proposital: o cadastro precisa de upload de documentos físicos, validação CNPJ junto ao processador, e definição do PIN que protege ações sensíveis. Tudo isso é interação humana.

**Como obter sua API key**:

1. Acesse [vitrin.digital](https://vitrin.digital) → **Criar conta**
2. Preencha CNPJ, razão social, endereço e defina seu PIN de 6 dígitos
3. Conclua o onboarding documental enviando RG/CNH dos sócios + contrato social
4. Após aprovação, sua API key (`vd_live_...`) fica disponível em `/dashboard/settings/`

### Autenticação

Todas as requisições da API usam a API key no header:

```
Authorization: Bearer vd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### Rotacionar a API key

Se a key for comprometida ou você quiser rotacionar (boas práticas, CI/CD, etc.), regenere via API. Requer o PIN do dono da org no body:

```
POST /api/v1/auth/api-key/regenerate/

{ "pin": "123456" }
```

A resposta inclui a nova `api_key` — armazene imediatamente, a antiga é invalidada e qualquer chamada subsequente com ela retorna 401.

> **Por que o PIN está aqui?** Rotação de chave é uma operação destrutiva (invalida tudo). O PIN garante que o dono autorizou a ação, mesmo que alguém com acesso à API key consiga fazer a chamada.

---

## 1.5. Status do onboarding (read-only)

Após o cadastro a org passa por verificação documental antes de poder cobrar e sacar. O upload dos documentos é feito **no dashboard** em `/dashboard/onboarding` — sem cURL, sem API. Sua aplicação pode, no entanto, **consultar o status** do onboarding pra mostrar mensagens contextuais ou habilitar funcionalidades só quando a org estiver liberada:

```
GET /api/v1/onboarding/status/
```

**Resposta:**
```json
{
  "subaccount_created": true,
  "org_status": "onboarding",
  "document_status": "PENDING",
  "account_status": {
    "general": "PENDING",
    "documentation": "AWAITING_APPROVAL",
    "commercial_info": "APPROVED",
    "bank_account_info": "APPROVED"
  }
}
```

Quando `account_status.general == "APPROVED"`, a org passa automaticamente para `org_status='active'` e libera saques. O dashboard reflete isso em tempo real.

---

## 1.6. Contratos eletrônicos

A Vitrin opera sob 4 contratos comerciais (Termos de Uso, Anexo Comercial, Política de Chargebacks e Política de Privacidade) que precisam estar **assinados** antes que sua org consiga gerar cobranças. Tentativas de cobrar antes da assinatura retornam **HTTP 403**:

```json
{ "detail": "Voce precisa assinar todos os contratos comerciais antes de operar. Acesse /dashboard/contract para revisar e assinar." }
```

### Como assinar (humano, no dashboard)

A assinatura é feita pelo dono da org em `/dashboard/contract`. Lá ele revisa cada contrato (com as taxas reais preenchidas no Anexo Comercial), faz scroll até o fim e confirma com PIN. **Não há endpoint REST pra assinar** — assinatura eletrônica avançada exige interação humana inequívoca.

### Consultar status (programático)

Antes de cada chamada de cobrança, sua aplicação pode (opcionalmente) checar se está tudo em ordem:

```
GET /api/v1/contracts/status/
```

**Resposta:**
```json
{
  "all_signed": true,
  "pending": [],
  "active": [
    {
      "id": "uuid",
      "contract_slug": "terms-of-use",
      "contract_title": "Termos de Uso",
      "contract_version": 1,
      "signed_at": "2026-04-10T12:34:56Z",
      "valid_until": null,
      "status": "active"
    }
  ]
}
```

Se `all_signed == false`, redirecione o operador para `/dashboard/contract`.

### Re-assinatura quando o contrato muda

Se a Vitrin publicar uma nova versão de qualquer contrato (ex: atualização da Política de Chargebacks), o `pending` volta a ter itens com `reason: "new_version"` e a operação fica bloqueada até nova assinatura. Você é avisado por e-mail com **30 dias de antecedência**.

---

## 2. Clientes

Antes de cobrar, cadastre o pagador.

### Criar

```
POST /api/v1/customers/

{
  "name": "Maria Silva",
  "email": "maria@email.com",
  "cpf_cnpj": "12345678909",
  "phone": "11999887766"
}
```

**Resposta:** retorna `id` do cliente (UUID) para usar nas cobranças.

Campos opcionais de endereço (útil para produtos físicos e defesa de chargeback):
```json
{
  "address": "Rua das Flores",
  "address_number": "42",
  "province": "Centro",
  "postal_code": "01001000",
  "city": "São Paulo",
  "state": "SP"
}
```

### Listar

```
GET /api/v1/customers/?page=1
```

Resposta paginada:
```json
{
  "count": 142,
  "next": "https://api.vitrin.digital/api/v1/customers/?page=2",
  "previous": null,
  "results": [ { "id": "uuid", "name": "Maria Silva", ... } ]
}
```

Filtros aceitos via query string: `email`, `cpf_cnpj`, `name__icontains`.

### Detalhes

```
GET /api/v1/customers/{id}/
```

### Atualizar

```
PUT  /api/v1/customers/{id}/    # substitui todos os campos
PATCH /api/v1/customers/{id}/   # atualiza só os enviados
```

### Excluir

```
DELETE /api/v1/customers/{id}/
```

> Excluir um cliente que tem transações associadas é bloqueado — você recebe HTTP 409. Use para limpar cadastros que nunca pagaram.

---

## 3. Cobranças

### 3.1 Pix

```
POST /api/v1/checkout/pix/

{
  "customer_id": "uuid-do-cliente",
  "amount": 99.90,
  "description": "Plano Mensal"
}
```

**Resposta:**
```json
{
  "payment_id": "uuid-da-transacao",
  "qr_code": "base64-do-qr-code",
  "copy_paste": "00020101021226880014br.gov.bcb...",
  "amount": 99.90,
  "status": "pending"
}
```

O frontend da sua app exibe o QR code (`qr_code` em base64) ou o código copia-e-cola (`copy_paste`).

### 3.2 Boleto

```
POST /api/v1/checkout/boleto/

{
  "customer_id": "uuid-do-cliente",
  "amount": 99.90,
  "description": "Plano Mensal"
}
```

**Resposta:**
```json
{
  "payment_id": "uuid-da-transacao",
  "barcode": "23793.38128 60000.000003 00000.000406 1 84340000009990",
  "url": "https://asaas.com/b/pdf/xxxx",
  "amount": 99.90,
  "status": "pending"
}
```

### 3.3 Cartão de Crédito

#### Passo 1: Tokenizar o cartão

```
POST /api/v1/checkout/tokenize/

{
  "customer_id": "uuid-do-cliente",
  "credit_card": {
    "holderName": "MARIA SILVA",
    "number": "5162306219378829",
    "expiryMonth": "01",
    "expiryYear": "2028",
    "ccv": "318"
  },
  "credit_card_holder_info": {
    "name": "Maria Silva",
    "email": "maria@email.com",
    "cpfCnpj": "12345678909",
    "postalCode": "01001000",
    "addressNumber": "42",
    "phone": "11999887766"
  }
}
```

**Resposta:**
```json
{
  "credit_card_token": "tok_xxxxxxxxxxxxx",
  "credit_card_number": "5162 **** **** 8829",
  "credit_card_brand": "MASTERCARD"
}
```

#### Passo 2: Cobrar com o token

```
POST /api/v1/checkout/pay/

{
  "customer_id": "uuid-do-cliente",
  "amount": 299.90,
  "billing_type": "CREDIT_CARD",
  "installments": 3,
  "credit_card_token": "tok_xxxxxxxxxxxxx",
  "description": "Pacote Premium"
}
```

> **Dados do cartão nunca passam pelo seu servidor.** A tokenização é feita via API e o token é usado para cobranças futuras.

### 3.4 Consultar Parcelamento

Antes de cobrar, consulte as opções de parcelamento com taxas:

```
GET /api/v1/checkout/installments/?amount=299.90
```

**Resposta:**
```json
{
  "amount": 299.90,
  "installments": [
    { "installment_count": 1, "installment_value": 299.90, "total_fee": 18.44, "net_amount": 281.46 },
    { "installment_count": 2, "installment_value": 149.95, "total_fee": 19.94, "net_amount": 279.96 },
    { "installment_count": 3, "installment_value": 99.97, "total_fee": 19.94, "net_amount": 279.96 }
  ]
}
```

### 3.5 Guest Checkout (sem cadastro prévio)

Cria o cliente e cobra em um único passo:

```
POST /api/v1/checkout/guest/

{
  "customer_name": "João Santos",
  "customer_email": "joao@email.com",
  "customer_cpf_cnpj": "98765432100",
  "customer_phone": "11988776655",
  "amount": 49.90,
  "billing_type": "PIX",
  "description": "Ingresso Evento"
}
```

### 3.6 Pix Automático (recorrência via SPI/BC)

Para cobranças recorrentes sem cartão. O pagador escaneia um QR Code uma única vez, autoriza a primeira cobrança + futuras recorrências via app bancário, e a partir daí você gera as cobranças periódicas.

> **Requisitos**: o método precisa estar habilitado pelo admin (`PIX_AUTOMATIC` em `allowed_payment_methods`) e pela própria org em `enabled_payment_methods`. A subconta Asaas precisa estar aprovada (CNPJ ativo há 6+ meses).

#### Passo 1: Criar a autorização (gera QR Code de aceite)

```
POST /api/v1/pix-automatic/authorizations/

{
  "customer_id": "uuid-do-cliente",
  "contract_id": "ASSINATURA-001",
  "frequency": "MONTHLY",
  "start_date": "2026-05-01",
  "value": 99.90,
  "description": "Mensalidade Plus",
  "first_charge_value": 99.90,
  "first_charge_description": "Primeira mensalidade"
}
```

**Campos:**
- `frequency`: `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY`, `ANNUALLY`
- `value` (opcional): trava o valor para todas as cobranças. Se omitido, você define o valor em cada cobrança.
- `finish_date` (opcional): se omitido, prazo indeterminado.
- `first_charge_value`: valor da primeira cobrança (vinculada ao QR Code de aceite — obrigatório).

**Resposta:**
```json
{
  "id": "uuid-da-autorizacao",
  "asaas_authorization_id": "pix_auto_xxx",
  "status": "CREATED",
  "immediate_qr_code": "<base64 PNG do QR Code>",
  "immediate_payload": "00020101021226880014br.gov.bcb...",
  "frequency": "MONTHLY",
  "value": "99.90"
}
```

Renderize o QR Code para o cliente:
```html
<img src="data:image/png;base64,<immediate_qr_code>" alt="QR Code Pix Automatico" />
```

Ou ofereça o copia-e-cola via `immediate_payload`.

#### Passo 2: Aguardar o aceite (via webhook)

Quando o cliente escaneia e aceita no app bancário, a autorização vai de `CREATED` para `ACTIVE`. Você recebe o evento:

```
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED
```

#### Passo 3: Gerar cobranças recorrentes

Com a autorização `ACTIVE`, gere cada cobrança periódica:

```
POST /api/v1/pix-automatic/authorizations/{id}/charges/

{
  "value": 99.90,
  "due_date": "2026-06-01",
  "description": "Mensalidade junho"
}
```

> **Janela do BC**: o `due_date` deve estar entre **2 e 10 dias úteis** no futuro. Tentativas fora dessa janela retornam HTTP 400.
>
> Se a autorização tem `value` fixo, você precisa enviar exatamente esse valor.

**Resposta:** retorna a Transaction criada (mesmo formato do `/checkout/pix/`).

#### Outras operações

```
GET    /api/v1/pix-automatic/authorizations/                      # Listar autorizações
GET    /api/v1/pix-automatic/authorizations/{id}/                 # Detalhes
GET    /api/v1/pix-automatic/authorizations/{id}/instructions/    # Listar cobranças geradas
POST   /api/v1/pix-automatic/authorizations/{id}/sync/            # Forçar sync com Asaas
DELETE /api/v1/pix-automatic/authorizations/{id}/                 # Cancelar (PIN obrigatório)
GET    /api/v1/pix-automatic/instructions/                        # Todas as instruções da org
```

#### Status possíveis

| Autorização | Significado |
|-------------|-------------|
| `CREATED` | Aguardando aceite do pagador |
| `ACTIVE` | Aceita — cobranças podem ser geradas |
| `CANCELLED` | Cancelada (pela org ou pelo pagador) |
| `REFUSED` | Recusada pelo banco do pagador |
| `EXPIRED` | Expirada sem aceite |

| Instrução (cobrança) | Significado |
|----------------------|-------------|
| `AWAITING_REQUEST` | Criada localmente |
| `SCHEDULED` | Agendada no SPI |
| `DONE` | Pagamento confirmado |
| `CANCELLED` | Cancelada antes do débito |
| `REFUSED` | Recusada (saldo insuficiente, divergência etc.) |

### 3.7 Repasse de taxas ao cliente final

Por padrão, a taxa da plataforma é descontada do valor que você recebe. Se quiser **repassar a taxa para o cliente final** (ele paga produto + taxa, você recebe o valor cheio), ative o toggle em `/dashboard/settings/` ou via API:

```
PATCH /api/v1/settings/
{ "pass_fees_to_customer": true }
```

Quando ativo, uma cobrança de R$ 100 vira R$ 105,49 para o cliente, e a sua org recebe os R$ 100 inteiros (a taxa de R$ 5,49 sai do bolso do pagador).

> Esse comportamento se aplica a Pix, Boleto e Cartão. **Não se aplica** a Pix Automático (a janela do BC não permite alteração de valor pós-aceite).

---

## 4. Polling de Status (Pix)

Para Pix, faça polling até o pagamento ser confirmado:

```
GET /api/v1/payments/{payment_id}/status/
```

**Resposta:**
```json
{
  "payment_id": "uuid",
  "status": "pending",
  "confirmed": false,
  "pix_copy_paste": "00020101..."
}
```

Faça polling a cada 3-5 segundos. Quando `confirmed: true`, o pagamento foi recebido.

---

## 5. Webhooks

### Configurar

Acesse **Configurações** no dashboard ou via API:

```
PUT /api/v1/webhooks/config/

{
  "webhook_url": "https://suaapp.com/webhooks/vitrin",
  "pin": "123456"
}
```

O secret HMAC é gerado automaticamente.

### Receber eventos

A Vitrin envia um POST para a sua URL quando eventos ocorrem:

```
POST https://suaapp.com/webhooks/vitrin

Headers:
  X-Vitrin-Signature: sha256=abc123...
  X-Vitrin-Event: PAYMENT_RECEIVED
  X-Vitrin-Event-Id: PAYMENT_RECEIVED:pay_xxx:2026-04-09
  Content-Type: application/json

Body:
{
  "event": "PAYMENT_RECEIVED",
  "payment": {
    "id": "pay_xxx",
    "status": "RECEIVED",
    "value": 99.90,
    "netValue": 96.41,
    "billingType": "PIX",
    "customer": "cus_xxx"
  }
}
```

### Validar assinatura

```python
import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)
```

### Eventos suportados

| Evento | Quando |
|--------|--------|
| `PAYMENT_RECEIVED` | Pagamento confirmado |
| `PAYMENT_CONFIRMED` | Pagamento confirmado (cartão) |
| `PAYMENT_OVERDUE` | Pagamento vencido |
| `PAYMENT_REFUNDED` | Reembolso processado |
| `PAYMENT_CHARGEBACK_REQUESTED` | Chargeback aberto |
| `PAYMENT_DELETED` | Pagamento cancelado |
| `SUBSCRIPTION_CREATED` | Assinatura criada |
| `SUBSCRIPTION_DELETED` | Assinatura cancelada |
| `PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED` | Autorização Pix Automático criada |
| `PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED` | Pagador aceitou — autorização ativa |
| `PIX_AUTOMATIC_RECURRING_AUTHORIZATION_REFUSED` | Autorização recusada pelo banco |
| `PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED` | Autorização cancelada |
| `PIX_AUTOMATIC_RECURRING_AUTHORIZATION_EXPIRED` | Autorização expirou sem aceite |
| `PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED` | Instrução de cobrança criada |
| `PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED` | Instrução agendada no SPI |
| `PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED` | Instrução recusada (ver `refusalReason`) |
| `PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED` | Instrução cancelada |

---

## 6. Assinaturas

Recorrência via cartão de crédito ou boleto. Cada plano define a periodicidade e o valor; cada assinatura vincula um cliente a um plano.

### Planos

**Criar:**
```
POST /api/v1/plans/

{
  "name": "Plano Pro",
  "price": 179.90,
  "billing_cycle": "monthly",
  "description": "Acesso completo"
}
```

Ciclos: `weekly`, `biweekly`, `monthly`, `bimonthly`, `quarterly`, `semiannually`, `yearly`.

**Listar / Detalhes / Atualizar / Excluir:**
```
GET    /api/v1/plans/
GET    /api/v1/plans/{id}/
PUT    /api/v1/plans/{id}/        # substitui
PATCH  /api/v1/plans/{id}/        # parcial
DELETE /api/v1/plans/{id}/        # bloqueado se houver assinaturas ativas
```

### Assinaturas

**Criar:**
```
POST /api/v1/subscriptions/

{
  "customer_id": "uuid-do-cliente",
  "plan_id": "uuid-do-plano",
  "billing_type": "CREDIT_CARD",
  "credit_card_token": "tok_xxx"
}
```

Para boleto, omita o token e use `"billing_type": "BOLETO"`.

**Listar:**
```
GET /api/v1/subscriptions/?page=1
```

Resposta paginada. Filtros aceitos: `status`, `customer_id`, `plan_id`.

**Detalhes (com dados ao vivo do processador):**
```
GET /api/v1/subscriptions/{id}/detail/
```

Retorna o histórico de cobranças geradas, próxima fatura, e status atual sincronizado com o Asaas.

**Cancelar:**
```
POST /api/v1/subscriptions/{id}/cancel/
```

---

## 7. Produtos e Pedidos

Para vendas avulsas (eventos, pacotes, créditos, ingressos, infoprodutos).

### Produtos

**Criar:**
```
POST /api/v1/products/

{
  "name": "Evento Premium",
  "product_type": "one_time",
  "price": 347.00,
  "description": "Acesso a 1 evento com recursos Pro",
  "stock": 100
}
```

**Tipos** (`product_type`):
- `one_time` — pagamento único (ingresso, infoproduto, serviço)
- `pack` — pacote com N unidades (curso com aulas, conjunto de itens)
- `credits` — créditos (saldo pré-pago para uso futuro)

**Listar / Detalhes / Atualizar / Excluir:**
```
GET    /api/v1/products/
GET    /api/v1/products/{id}/
PUT    /api/v1/products/{id}/
PATCH  /api/v1/products/{id}/
DELETE /api/v1/products/{id}/
```

Filtros: `active`, `product_type`, `name__icontains`.

### Pedidos

**Criar:**
```
POST /api/v1/orders/create/

{
  "customer_id": "uuid-do-cliente",
  "product_id": "uuid-do-produto",
  "billing_type": "PIX",
  "quantity": 1
}
```

O pedido cria a cobrança automaticamente. Quando o webhook `PAYMENT_RECEIVED` chega, o pedido muda para `paid`.

**Listar:**
```
GET /api/v1/orders/?status=paid&page=1
```

Status possíveis: `pending`, `paid`, `fulfilled`, `cancelled`. Filtros: `status`, `product_id`, `customer_id`.

**Detalhes:**
```
GET /api/v1/orders/{id}/
```

Inclui o cliente, produto, transação vinculada e timestamps de cada transição de status.

**Marcar como entregue (fulfill):**
```
POST /api/v1/orders/{id}/fulfill/
```

Use depois que você entregou o produto (mandou ingresso por e-mail, liberou acesso ao curso, despachou o item físico). Marca `fulfilled_at` e expõe ao cliente final via dashboard.

> Pedidos são **read-only** via REST (não há PUT/PATCH/DELETE direto). Para modificar, cancele e crie um novo.

---

## 8. Reembolso e Cancelamento

### Reembolso (requer PIN)

```
POST /api/v1/payments/{id}/refund/

{
  "pin": "123456",
  "amount": 50.00
}
```

Omita `amount` para reembolso total.

### Cancelar cobrança pendente

```
POST /api/v1/payments/{id}/cancel/
```

Só funciona para cobranças com status `pending` ou `confirmed`.

---

## 9. Saldo e Transferências

### Consultar saldo

```
GET /api/v1/balance/
```

**Resposta:**
```json
{
  "available": 1500.00,
  "total": 2300.00,
  "pending": 800.00,
  "withdrawal_fees": { "pix": 3.49, "ted": 9.49 }
}
```

- **available**: pronto para saque
- **pending**: aguardando compensação (D+1 Pix, D+2 Boleto, D+30 Crédito)
- **total**: available + pending

### Transferir via Pix (requer PIN)

```
POST /api/v1/transfers/pix/

{
  "value": 500.00,
  "pix_key": "12345678909",
  "pix_key_type": "CPF",
  "pin": "123456"
}
```

Tipos de chave: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP` (aleatória).

### Transferir via dados bancários (requer PIN)

```
POST /api/v1/transfers/bank/

{
  "value": 500.00,
  "bank_code": "237",
  "agency": "0001",
  "account": "12345",
  "account_digit": "6",
  "account_type": "CONTA_CORRENTE",
  "owner_name": "Maria Silva",
  "cpf_cnpj": "12345678909",
  "pin": "123456"
}
```

### Histórico de transferências

```
GET /api/v1/transfers/
```

Combina transferências locais (já solicitadas pela sua org) + dados ao vivo do processador (status real, falhas, datas de efetivação).

---

## 10. Antecipação de Recebíveis

Antecipação te permite receber agora valores que cairiam no futuro (cartão D+30, parcelado D+(30·N), boleto D+2). A taxa é proporcional ao tempo restante até a liberação original e é aplicada por transação.

> **Pré-requisito**: a org precisa ter `allow_anticipation=true` (ativado pelo admin no signup). Tentativas com a feature desabilitada retornam HTTP 403.

### Listar transações elegíveis

```
GET /api/v1/anticipations/?status=eligible
```

Lista as Transactions com `status='received'` que ainda não foram antecipadas. Use `?status=anticipated` para ver as já antecipadas.

### Simular antes de solicitar

Antes de gastar, simule pra ver quanto você recebe líquido:

```
POST /api/v1/anticipations/simulate/

{ "payment_id": "uuid-da-transacao" }
```

**Resposta** (vinda do processador):
```json
{
  "value": 100.00,
  "fee": 5.50,
  "netValue": 94.50
}
```

> Em sandbox, o processador pode recusar a simulação (a subconta de teste não tem permissão para antecipar). O dashboard cai em uma estimativa local com base nas suas taxas — programaticamente, trate o erro 502 e calcule você mesmo se quiser.

### Solicitar antecipação (requer PIN)

```
POST /api/v1/anticipations/request/

{
  "payment_id": "uuid-da-transacao",
  "pin": "123456"
}
```

**Resposta:**
```json
{
  "transaction_id": "uuid",
  "anticipated": true,
  "anticipation_fee": 5.50,
  "result": { ... resposta crua do processador ... }
}
```

A Transaction passa a ter `anticipated=true` e o valor cai em `available` no `/balance/` em D+2 útil.

---

## 11. Defesa de Chargeback

Quando você recebe um chargeback (`PAYMENT_CHARGEBACK_REQUESTED`), tem **prazo restrito** para contestar (geralmente 7-10 dias corridos). A Vitrin compila automaticamente o **dossiê de defesa** com todas as evidências disponíveis da transação:

```
GET /api/v1/payments/{id}/chargeback-defense/
```

**Resposta:**
```json
{
  "transaction": {
    "id": "uuid",
    "amount": 99.90,
    "billing_type": "CREDIT_CARD",
    "installments": 1,
    "paid_at": "2026-04-09T15:30:00Z",
    "payer_ip": "189.6.x.y"
  },
  "customer": {
    "name": "Maria Silva",
    "cpf_cnpj": "12345678909",
    "email": "maria@email.com",
    "phone": "11988776655",
    "address": "Rua das Flores, 42 - Centro",
    "city_state": "São Paulo/SP"
  },
  "order": {
    "product_name": "Curso Premium",
    "fulfilled_at": "2026-04-09T16:00:00Z"
  },
  "subscription": null,
  "previous_transactions": [
    { "id": "uuid", "amount": 49.90, "paid_at": "2026-03-15T..." }
  ],
  "webhook_events": [
    { "event_type": "PAYMENT_CONFIRMED", "created_at": "..." },
    { "event_type": "PAYMENT_RECEIVED", "created_at": "..." }
  ],
  "audit_trail": [
    { "action": "transaction.created", "timestamp": "...", "ip_address": "..." }
  ]
}
```

Use esses dados pra montar a contestação no painel da bandeira (Visa/Master) ou via processador. O ideal é guardar tudo: comprovante de entrega, IP do pagador, transações anteriores do mesmo cliente bem-sucedidas, fulfillment do pedido, eventos de webhook que comprovam a confirmação do pagamento.

> **Boas práticas para reduzir chargebacks**: cobre só após confirmar identidade, marque pedidos como `fulfilled` assim que entregar, mantenha cadastro de cliente completo (endereço!), responda chargebacks rapidamente.

---

## 12. Configurações da Org

Self-service de tudo que você pode customizar pelo dashboard `/dashboard/settings/`.

### Ler configurações atuais

```
GET /api/v1/settings/
```

**Resposta:**
```json
{
  "enabled_payment_methods": ["PIX", "CREDIT_CARD", "BOLETO"],
  "org_max_installments": 12,
  "org_min_installment_value": "10.00",
  "auto_anticipation_enabled": false,
  "checkout_logo": "https://...",
  "checkout_primary_color": "#00BCB5",
  "webhook_url": "https://suaapp.com/webhooks/vitrin",
  "pass_fees_to_customer": false,

  "allowed_payment_methods": ["PIX", "CREDIT_CARD", "BOLETO"],
  "max_installments": 12,
  "min_installment_value": "10.00",
  "allow_anticipation": true,
  "allow_auto_anticipation": false,

  "fee_percentage_pix": "5.49",
  "fee_fixed_pix": "3.49",
  "fee_percentage_credit": "5.49",
  "anticipation_rate_credit_vista": "2.99",
  "withdrawal_fee_fixed_pix": "3.49"
}
```

Os campos dividem-se em três blocos:

| Bloco | Editável pela org? |
|---|---|
| **Preferências da org** (`enabled_payment_methods`, `org_max_installments`, `auto_anticipation_enabled`, `checkout_logo`, `checkout_primary_color`, `pass_fees_to_customer`) | ✅ via PATCH |
| **Limites da plataforma** (`allowed_payment_methods`, `max_installments`, `allow_anticipation`) | ❌ definido pelo admin no onboarding |
| **Tabela de taxas** (`fee_*`, `anticipation_*`, `withdrawal_*`) | ❌ congelada no Anexo Comercial assinado |

### Atualizar (parcial)

```
PATCH /api/v1/settings/

{
  "enabled_payment_methods": ["PIX", "CREDIT_CARD"],
  "checkout_primary_color": "#FD8000",
  "auto_anticipation_enabled": true
}
```

> A `enabled_payment_methods` precisa ser um subconjunto de `allowed_payment_methods`. Tentar habilitar um método não-permitido retorna HTTP 400.

### Configurar webhook (já documentado em §5)

`PUT /api/v1/webhooks/config/` — requer PIN.

---

## 13. Relatórios

Relatórios agregados sobre a operação da sua org. Todos retornam dados restritos à org autenticada.

### Overview do dashboard

```
GET /api/v1/reports/overview/?days=30
```

**Resposta:**
```json
{
  "total_revenue": 28900.50,
  "total_transactions": 142,
  "active_subscriptions": 23,
  "active_customers": 89,
  "anticipated_value": 8500.00,
  "by_method": {
    "PIX": 18200.00,
    "CREDIT_CARD": 9100.50,
    "BOLETO": 1600.00
  }
}
```

### Receita por dia

```
GET /api/v1/reports/revenue/?days=30
```

Retorna uma série temporal com receita bruta e líquida por dia, pronta para gráficos.

### Receita mensal

```
GET /api/v1/reports/revenue/monthly/?months=12
```

### Transações com filtros

```
GET /api/v1/reports/transactions/?status=received&billing_type=PIX&from=2026-04-01&to=2026-04-30
```

Filtros: `status`, `billing_type`, `customer_id`, `from`, `to`, `min_amount`, `max_amount`.

### Churn de assinaturas

```
GET /api/v1/reports/churn/
```

Retorna taxa de cancelamento por mês, MRR perdido e principais motivos.

### Relatório de antecipações

```
GET /api/v1/reports/anticipation/?from=2026-04-01&to=2026-04-30
```

Resumo de antecipações solicitadas no período: total antecipado, taxa total paga, economia média de tempo.

---

## 14. Referência Rápida de Endpoints

### Checkout
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/checkout/pix/` | Cobrar via Pix |
| POST | `/checkout/boleto/` | Cobrar via Boleto |
| POST | `/checkout/tokenize/` | Tokenizar cartão |
| POST | `/checkout/pay/` | Cobrar com token |
| POST | `/checkout/guest/` | Checkout sem cadastro prévio |
| GET | `/checkout/installments/?amount=X` | Consultar parcelamento |

### Pix Automático
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/pix-automatic/authorizations/` | Listar autorizações |
| POST | `/pix-automatic/authorizations/` | Criar (gera QR Code de aceite) |
| GET | `/pix-automatic/authorizations/{id}/` | Detalhes |
| DELETE | `/pix-automatic/authorizations/{id}/` | Cancelar (PIN) |
| POST | `/pix-automatic/authorizations/{id}/charges/` | Criar cobrança recorrente (2-10 dias úteis) |
| GET | `/pix-automatic/authorizations/{id}/instructions/` | Listar instruções da autorização |
| POST | `/pix-automatic/authorizations/{id}/sync/` | Forçar sync com Asaas |
| GET | `/pix-automatic/instructions/` | Todas as instruções da org |
| GET | `/pix-automatic/instructions/{id}/` | Detalhe da instrução |

### Transações
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/transactions/` | Listar transações |
| GET | `/payments/{id}/status/` | Status (polling Pix) |
| POST | `/payments/{id}/refund/` | Reembolsar (PIN) |
| POST | `/payments/{id}/cancel/` | Cancelar pendente |
| GET | `/payments/{id}/chargeback-defense/` | Dossiê de defesa |

### Clientes
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/customers/` | Listar clientes (paginado) |
| POST | `/customers/` | Criar cliente |
| GET | `/customers/{id}/` | Detalhes |
| PUT/PATCH | `/customers/{id}/` | Atualizar |
| DELETE | `/customers/{id}/` | Excluir (bloqueado se houver transações) |

### Assinaturas
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/subscriptions/` | Listar assinaturas |
| POST | `/subscriptions/` | Criar assinatura |
| POST | `/subscriptions/{id}/cancel/` | Cancelar |
| GET | `/subscriptions/{id}/detail/` | Detalhe com dados Asaas |

### Planos
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/plans/` | Listar planos |
| POST | `/plans/` | Criar plano |
| PUT | `/plans/{id}/` | Atualizar |
| DELETE | `/plans/{id}/` | Excluir |

### Produtos e Pedidos
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/products/` | Listar produtos |
| POST | `/products/` | Criar produto |
| GET | `/products/{id}/` | Detalhes |
| PUT/PATCH | `/products/{id}/` | Atualizar |
| DELETE | `/products/{id}/` | Excluir |
| POST | `/orders/create/` | Criar pedido (gera cobrança) |
| GET | `/orders/` | Listar pedidos |
| GET | `/orders/{id}/` | Detalhes |
| POST | `/orders/{id}/fulfill/` | Marcar entregue |

### Contratos eletrônicos (read-only)
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/contracts/status/` | Visão geral (`pending` + `active` + `all_signed`) |
| GET | `/contracts/pending/` | Apenas contratos a assinar |
| GET | `/contracts/active/` | Apenas vigentes |
| GET | `/contracts/{id}/preview/` | Render do template para leitura |
| GET | `/contracts/history/` | Histórico de aceitações |
| GET | `/contracts/acceptances/{id}/` | Detalhe de uma aceitação |

> Assinar é ação humana — feita em `/dashboard/contract` com PIN.

### Onboarding (read-only)
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/onboarding/status/` | Status do processador (sincronizado ao vivo) |

> Upload de documentos é ação humana — feita em `/dashboard/onboarding`.

### Auth (rotação de chave)
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/auth/api-key/regenerate/` | Rotaciona a API key (requer PIN) |

> Cadastro, login, PIN e password reset são ações humanas — feitas no dashboard.

### Financeiro
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/balance/` | Saldo (disponível + pendente) |
| GET | `/finance/statement/` | Extrato financeiro |
| POST | `/transfers/pix/` | Transferir via Pix (PIN) |
| POST | `/transfers/bank/` | Transferir via banco (PIN) |
| GET | `/transfers/` | Histórico de transferências |

### Antecipação
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/anticipations/` | Listar transações elegíveis |
| POST | `/anticipations/simulate/` | Simular antecipação |
| POST | `/anticipations/request/` | Solicitar (PIN) |

### Configurações
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/settings/` | Configurações da org |
| PATCH | `/settings/` | Atualizar configurações |
| PUT | `/webhooks/config/` | Configurar webhook (PIN) |
| GET | `/onboarding/status/` | Status do onboarding |

### Relatórios
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/reports/overview/` | Dashboard overview |
| GET | `/reports/revenue/?days=30` | Receita por período |
| GET | `/reports/transactions/` | Transações com filtros |
| GET | `/reports/churn/` | Churn de assinaturas |
| GET | `/reports/anticipation/` | Relatório de antecipações |

---

## 15. Códigos de Erro

| Status | Significado |
|--------|-------------|
| 200 | Sucesso |
| 201 | Criado com sucesso |
| 400 | Dados inválidos (verifique o corpo da requisição) |
| 401 | API key inválida ou expirada |
| 403 | Sem permissão (org suspensa ou feature desabilitada) |
| 404 | Recurso não encontrado |
| 429 | Rate limit excedido (100 req/min padrão) |
| 502 | Erro no processador de pagamentos (Asaas indisponível) |

Todos os erros retornam JSON:
```json
{ "error": "Descrição do erro." }
```

---

## 16. Prazos de Recebimento

| Método | Prazo padrão | Com antecipação |
|--------|-------------|-----------------|
| **Pix** | D+1 | D+2 útil |
| **Boleto** | D+2 | D+2 útil |
| **Crédito à vista** | D+30 | D+2 útil |
| **Crédito parcelado** | 1 parcela a cada 30 dias | Todas em D+2 útil |

---

## 17. Limites e Rate Limiting

| Recurso | Limite |
|---------|--------|
| API key (geral) | 100 req/min |
| Checkout | 30 req/min |
| Webhooks | 500 req/min |

Header `Retry-After` é retornado quando o limite é excedido.

---

## Suporte

- **Dashboard**: https://vitrin.digital/dashboard
- **Swagger / API Docs**: https://api.vitrin.digital/api/docs/
- **Email**: contato@vitrin.digital