Integre a Vitrin
com seu LLM favorito.

Você está integrando a Vitrin Digital, um intermediador de pagamentos brasileiro.

Referência completa: https://vitrin.digital/llms-full.txt
Spec OpenAPI 3.0: https://vitrin.digital/openapi.json
Swagger interativo: https://api.vitrin.digital/api/public/docs/

ESCOPO DA INTEGRAÇÃO VIA API:

A API REST cobre operações de comerciante: cobranças, assinaturas, produtos, pedidos, clientes, webhooks, antecipação, transferências, relatórios. **Cadastro, login, definição de PIN, assinatura de contrato e upload de documentos são feitos no dashboard web** (vitrin.digital) — não há endpoints REST para essas ações porque exigem interação humana inequívoca. Sua aplicação consome a API com uma API key obtida pelo dono da org no dashboard depois do onboarding.

CONFIGURAÇÃO DA API:

- URL base: https://api.vitrin.digital/api/v1
- Auth: header `Authorization: Bearer vd_live_<chave>` em todas as chamadas
- Content-Type: application/json em POST/PATCH/PUT
- Encoding: UTF-8

CONVENÇÕES DE DADOS:

- Valores monetários são strings decimais: "99.90" (não centavos, não float)
- Datas no formato ISO 8601: "2026-04-15"
- IDs são UUIDs em string
- Listas retornam paginadas: `{ count, next, previous, results }`
- Erros retornam JSON com chave `error` ou `detail` + status HTTP padrão

MÉTODOS DE PAGAMENTO DISPONÍVEIS:

- Pix instantâneo (`POST /checkout/pix/`) — retorna QR Code base64 e copia-cola
- Pix Automático (`POST /pix-automatic/authorizations/`) — recorrência nativa do BC com aceite único; cobranças posteriores via `POST /pix-automatic/authorizations/{id}/charges/` com due_date entre 2 e 10 dias úteis no futuro
- Boleto (`POST /checkout/boleto/`) — retorna URL do PDF e linha digitável
- Cartão de crédito 1-12x — fluxo de duas etapas: `POST /checkout/tokenize/` (retorna token) → `POST /checkout/pay/` (cobra com o token)

A escolha de qual método oferecer ao seu cliente final é decisão sua.

REQUISITOS TÉCNICOS DA API:

1. Tokenização de cartão: dados de cartão (número, ccv) devem ser enviados ao endpoint `/checkout/tokenize/` que retorna `credit_card_token`. Use o token nas cobranças subsequentes. Esse fluxo é exigido pela conformidade PCI da plataforma.

2. Webhooks: o dono da org configura a URL pelo dashboard (`/dashboard/webhooks`) e recebe um `webhook_secret`. A Vitrin envia eventos para essa URL com header `X-Vitrin-Signature: sha256=<hex>` calculado como HMAC-SHA256 do body cru com o secret. Validar essa assinatura é necessário para confiar no payload.

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

3. Operações sensíveis exigem o PIN do dono da org no body: refund, cancel, transfer (Pix/banco), anticipation request, rotação de api-key. O PIN é definido pelo dono no cadastro inicial. Como expor a entrada do PIN ao usuário é decisão do integrador.

4. Antes da primeira cobrança, a org precisa ter assinado os 4 contratos comerciais (Termos, Anexo Comercial, Política de Chargebacks, LGPD). Isso é feito pelo dono no dashboard. Sua aplicação pode checar via `GET /contracts/status/`. Se `all_signed` for false, mostre uma mensagem orientando o operador a ir para `/dashboard/contract` — tentar cobrar antes retorna HTTP 403.

5. Antes da primeira saída de dinheiro, a org precisa concluir o onboarding documental. Sua aplicação pode checar via `GET /onboarding/status/` se `account_status.general == "APPROVED"`. Upload de documentos é humano (no dashboard).

ENDPOINTS PRINCIPAIS DA API:

- POST /customers/ — cria pagador (retorna id)
- POST /checkout/pix/, /checkout/boleto/, /checkout/pay/ — cobranças
- POST /checkout/tokenize/ — tokenização de cartão
- POST /checkout/guest/ — cria customer + cobrança em uma chamada
- POST /pix-automatic/authorizations/ + .../charges/ — recorrência via Pix Automático
- POST /subscriptions/ + /plans/ — recorrência via cartão
- POST /products/ + /orders/create/ — produtos avulsos
- GET /transactions/ — listar
- GET /balance/ + POST /transfers/pix/|/bank/ — saldo e saques
- POST /anticipations/simulate/ + /anticipations/request/ — antecipação
- POST /payments/{id}/refund/|/cancel/ — reembolso/cancelamento
- GET /payments/{id}/chargeback-defense/ — dossiê para contestação
- GET /onboarding/status/ — checar se a org está aprovada
- GET /contracts/status/ — checar se os contratos estão assinados
- POST /auth/api-key/regenerate/ — rotacionar a API key (requer PIN)

EVENTOS DE WEBHOOK (lista parcial — ver llms-full.txt para a lista completa):

- PAYMENT_RECEIVED, PAYMENT_CONFIRMED, PAYMENT_REFUNDED, PAYMENT_CHARGEBACK_REQUESTED
- SUBSCRIPTION_CREATED, SUBSCRIPTION_DELETED
- PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED|REFUSED|CANCELLED|EXPIRED
- PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED|SCHEDULED|DONE|REFUSED

Para qualquer detalhe que faltar, leia https://vitrin.digital/llms-full.txt — tem o guia completo com exemplos e payloads.

MINHA TAREFA:
[descreva aqui o que você quer integrar]