Compra de créditos

Os créditos são a unidade de consumo da Scoring API do vario. Ao se cadastrar você recebe 250 créditos de boas-vindas. Quando eles se esgotarem, você pode recarregar escolhendo o valor em USD que deseja carregar.

ℹ

O vario não armazena nem retém o texto analisado. Cada chamada ao endpoint de análise é stateless e independente.

Preço e equivalências

$0,150 USD por crédito.

Modo	Créditos por chamada	Custo por chamada
`screening`	1 crédito	$0,150
`fast`	2 créditos	$0,300
`full`	3 créditos	$0,450

Opções de recarga (por valor)

Escolha quanto deseja carregar; os créditos são calculados automaticamente.

ID opção	Valor USD	Créditos	Chamadas `screening`	Chamadas `fast`	Chamadas `full`
`top75`	$75	500	500	250	166
`top150`	$150	1.000	1.000	500	333
`top300`	$300	2.000	2.000	1.000	666
`top1000`	$1.000	6.666	6.666	3.333	2.222
`custom`	livre	calculado	—	—	—

Para custom, o valor mínimo é $10 e o máximo é $5.000.

1. Ver opções disponíveis

GET /api/public/checkout/credits/preview

Endpoint público, sem autenticação. Retorna as opções de recarga disponíveis.

curl https://api.vario.lat/api/public/checkout/credits/preview

Resposta 200:

{
  "options": [
    { "id": "top75",   "label": "$75",    "amount_usd": 75.0,    "credits_preview": 500,   "status": "available" },
    { "id": "top150",  "label": "$150",   "amount_usd": 150.0,   "credits_preview": 1000,  "status": "available" },
    { "id": "top300",  "label": "$300",   "amount_usd": 300.0,   "credits_preview": 2000,  "status": "available" },
    { "id": "top1000", "label": "$1.000", "amount_usd": 1000.0,  "credits_preview": 6666,  "status": "available" },
    { "id": "custom",  "label": "outro",  "amount_usd": null,    "credits_preview": null,  "status": "available" }
  ],
  "current_balance": null,
  "pricing_note": "$0.150 per credit."
}

ℹ

O campo current_balance é null neste endpoint público. Para ver seu saldo atual, use GET /api/v1/api-keys/credits com autenticação.

2. Iniciar recarga

POST /api/public/checkout/credits

Inicia o processo de pagamento para o valor selecionado. O endpoint retorna um transaction_id usado para abrir o overlay de pagamento do Paddle.

Auth: nenhuma (pública). O tenant_id identifica o comprador.

Parâmetros da requisição:

Campo	Tipo	Obrigatório	Descrição
`top_up_id`	`string`	Sim	Opção a comprar: `"top75"`, `"top150"`, `"top300"`, `"top1000"` ou `"custom"`.
`tenant_id`	`string (uuid)`	Sim	Identificador do tenant que receberá os créditos.
`custom_amount_usd`	`float`	Apenas se `top_up_id == "custom"`	Valor em USD (mín $10, máx $5.000).

Exemplo — opção fixa:

curl -X POST https://api.vario.lat/api/public/checkout/credits \
  -H "Content-Type: application/json" \
  -d '{
    "top_up_id": "top300",
    "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Resposta 200:

{
  "transaction_id": "txn_01jxabc123def456",
  "top_up_id": "top300",
  "credits": 2000,
  "amount_usd": 300.0
}

Abrir o overlay de pagamento com o transaction_id retornado:

Paddle.Checkout.open({ transactionId: response.transaction_id });

Ao concluir o pagamento, os créditos ficam disponíveis imediatamente no saldo do tenant.

Erros possíveis:

HTTP	Descrição
`400`	`top_up_id` inválido.
`422`	`custom_amount_usd` ausente, menor que $10 ou maior que $5.000.
`402`	O tenant não possui método de pagamento cadastrado.
`404`	Tenant não encontrado.
`502`	Erro do provedor de pagamentos.

3. Consultar saldo atual

GET /api/v1/api-keys/credits

Retorna o saldo de créditos disponíveis do tenant autenticado.

curl https://api.vario.lat/api/v1/api-keys/credits \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Resposta 200:

{
  "balance": 2000,
  "call_cost_screening": 1,
  "call_cost_fast": 2,
  "call_cost_full": 3,
  "estimated_calls_remaining_screening": 2000,
  "estimated_calls_remaining_fast": 1000,
  "estimated_calls_remaining_full": 666,
  "pricing_note": "$0.150 per credit."
}

4. Histórico de uso

GET /api/v1/api-portal/usage

Retorna o consumo de créditos do tenant detalhado por dia.

curl "https://api.vario.lat/api/v1/api-portal/usage?from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Resposta 200:

{
  "period": { "from": "2026-06-01", "to": "2026-06-30" },
  "total_credits_used": 1250,
  "total_calls": 520,
  "daily": [
    { "date": "2026-06-01", "credits_used": 45, "calls": 18 },
    { "date": "2026-06-02", "credits_used": 60, "calls": 24 }
  ]
}

Fluxo completo — recarregar e verificar créditos

# 1. Ver opções disponíveis
curl https://api.vario.lat/api/public/checkout/credits/preview

# 2. Iniciar recarga de $300 (2.000 créditos)
curl -X POST https://api.vario.lat/api/public/checkout/credits \
  -H "Content-Type: application/json" \
  -d '{"top_up_id": "top300", "tenant_id": "SEU-TENANT-UUID"}'

# → Abrir overlay do Paddle com o transaction_id retornado
# → Concluir pagamento no overlay

# 3. Verificar que os créditos foram creditados
curl https://api.vario.lat/api/v1/api-keys/credits \
  -H "Authorization: Bearer vario_SUA_API_KEY"