Saldo de Créditos

Retorna o plano atual, os créditos restantes e usados, o status de cobrança e os identificadores da conta. Consulta somente leitura: não consome crédito e funciona mesmo com saldo zerado.

⚠

Mudança em 04/10/2026

A partir de hoje, GET /quota e a ferramenta MCP get_quota_info deixam de devolver staticCreditCost, realtimeCreditCost, overageEnabled, overagePriceInCents, staticRateLimitPerMinute e realtimeRateLimitPerMinute. Os custos por consulta (padrão de 1 crédito na Consulta Simples e 1,5 na Consulta em Tempo Real) e as regras de excedente do seu plano ficam no dashboard. Os limites padrão são 30/min na Consulta Simples (cada envio de lote conta como 1) e 5/min na Consulta em Tempo Real; planos personalizados podem ter limites diferentes, então confirme com o suporte da CPFHub.io. Respostas 429 trazem o header Retry-After. Veja Limites de Uso.

Endpoint

GEThttps://api.cpfhub.io/quota

Autenticação

Envie sua API Key no header x-api-key. Veja Autenticação.

Parâmetros

Este endpoint não recebe parâmetros de path ou query.

Headers

Header	Obrigatório	Descrição
`x-api-key`	Sim	Sua API Key do CPFHub.io

Exemplos de requisição

curl "https://api.cpfhub.io/quota" \
  -H "x-api-key: $CPFHUB_API_KEY"

Resposta de sucesso

HTTP 200 OK

JSON

{
  "success": true,
  "data": {
    "plan": "Básico",
    "remainingCredits": 750,
    "usedCredits": 250,
    "billingStatus": "active",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "usuario@exemplo.com"
  }
}

Campos da resposta

Campo	Tipo	Descrição
`success`	`boolean`	`true` se a requisição foi processada com sucesso
`data.plan`	`string`	Nome do plano da sua assinatura: `Grátis`, `Micro`, `Básico`, `Intermediário`, `Avançado` ou um plano personalizado. O plano Pro do site corresponde a Micro, Básico, Intermediário ou Avançado, conforme o volume (veja Limites de Uso). Contas sem assinatura retornam `"unknown"`
`data.remainingCredits`	`integer`	Créditos que ainda restam na franquia do período, arredondados para baixo. Um saldo de 1,4 aparece como `1`. Nunca fica negativo: em planos com excedente, continua em `0` enquanto as consultas seguem sendo cobradas como excedente
`data.usedCredits`	`number`	Créditos consumidos pela conta inteira (todas as chaves) no período atual. Em planos pagos, o período é o ciclo de cobrança da assinatura. No plano Grátis, é o mês corrente (UTC). Pode ter casas decimais e passar da franquia em planos com excedente
`data.billingStatus`	`"active"` \| `"free"`	Elegibilidade ao plano: `"active"` quando a conta tem uma assinatura que dá acesso ao plano, inclusive assinatura no plano Gratuito e status como `past_due`; `"free"` quando não há assinatura válida, por exemplo `canceled`, `unpaid` ou `incomplete_expired`. Nesse caso, `plan` pode vir como `"unknown"`
`data.userId`	`string`	Identificador único do usuário
`data.email`	`string`	Endereço de e-mail associado à conta

✦

Funciona com saldo zerado

GET /quota continua respondendo quando o saldo de créditos chega a zero. Assim você consulta o saldo pelo seu sistema e se antecipa antes que as consultas parem.

ℹ

Saldo fracionado

A Consulta Simples custa 1 crédito e a Consulta em Tempo Real custa 1,5 crédito por padrão, então o saldo pode ficar fracionado. Como remainingCredits é arredondado para baixo, confira os custos específicos do seu plano no dashboard antes de decidir se o saldo cobre a próxima consulta.

Como monitorar o saldo

Crie um alerta quando remainingCredits passar de um limite seu (por exemplo, 10% da franquia).
Acompanhe usedCredits para medir o consumo total no período.
Consulte no dashboard os custos e as regras de excedente específicas do seu plano.
Os limites padrão são 30/min na Consulta Simples (cada envio de lote conta como 1) e 5/min na Consulta em Tempo Real. Planos personalizados podem ter limites diferentes; confirme com o suporte da CPFHub.io. Acima do limite, a API responde 429 com o header Retry-After.
A franquia do período é usedCredits + remainingCredits enquanto o saldo não zera.

Códigos de status

Status	Descrição
`200 OK`	Consulta de saldo bem-sucedida
`401 Unauthorized`	API Key ausente, inválida ou inativa
`403 Forbidden`	Conta inativa ou bloqueada
`500 Internal Server Error`	Erro interno ao validar a assinatura (`"Erro ao validar assinatura"`)
`503 Service Unavailable`	Saldo temporariamente indisponível (`error: "usage_unavailable"`). Tente novamente em alguns segundos.

Nesses erros, error vem como string. GET /quota não tem limite por minuto e não consome crédito.

⚠

Mantenha sua API Key em segurança

Nunca exponha sua API Key em código público, repositórios ou aplicações executadas diretamente no navegador. Realize as chamadas à API sempre a partir do seu backend ou servidor.

Para a lista completa de códigos de erro e mensagens, veja Códigos de Erro.

Atualizado em 3 de outubro de 2026