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 — explore interativamente
• 📦 Schema OpenAPI — 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 → 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)

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)

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:

{
  "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. É 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 e 3.3
• Cobrança recorrente → Pix Automático ou Assinaturas
• Antecipar recebíveis → endpoints /anticipations/
• Sacar saldo → seção 9

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 → 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:

{
  "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:

{ "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:

{
  "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):

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

<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

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:

{
  "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

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

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:

{
  "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):

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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:

{
  "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

Pix Automático

Transações

Clientes

Assinaturas

Planos

Produtos e Pedidos

Contratos eletrônicos (read-only)

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

Onboarding (read-only)

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

Auth (rotação de chave)

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

Financeiro

Antecipação

Configurações

Relatórios

15. Códigos de Erro

Todos os erros retornam JSON:

{ "error": "Descrição do erro." }

16. Prazos de Recebimento

17. Limites e Rate Limiting

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