Créditos, franquia e rate limit
Quanto custa cada operação em créditos, como funciona a franquia mensal com hard cap, o que acontece nos limites de requisições por minuto e como ler GET /v1/usage.
Tudo custa em créditos, e você sabe o custo antes de chamar: a consulta basic custa 1, a full 6, a busca 1 por empresa retornada, e erros custam 0. Cada plano dá uma franquia mensal e um limite de requisições por minuto; quando a franquia acaba a API para de responder com 402, e nada é cobrado sem uma ação sua.
Pesos por operação
| Operação | Créditos |
|---|---|
GET /v1/cnpjs/{cnpj}?profile=basic |
1 |
GET /v1/cnpjs/{cnpj}?profile=full |
6 |
GET /v1/cnpjs (busca) |
1 por empresa retornada, até 20 por página; página vazia custa 0 |
POST /v1/filters/generate |
1 por chamada |
GET /v1/usage |
0 |
GET /v1/status |
0, sem chave |
GET /v1/demo |
0, sem chave |
| Qualquer erro (4xx, 5xx) | 0 |
Só respostas 200 são cobradas. Uma consulta full a uma empresa com pedido de remoção ativo (meta.suppressed: true) custa 1 crédito, porque os contatos não são entregues.
Franquia por plano
| Plano | Créditos por mês | Requisições por minuto | Busca |
|---|---|---|---|
| Free | 60 | 3 | não |
| Starter | 15000 | 30 | Filtros de cadastro, local e nome |
| Pro | 100000 | 120 | Todos os filtros, com sócio, raio, faturamento e funcionários |
| Business | 500000 | 300 | Todos os filtros, com sócio, raio, faturamento e funcionários |
| Scale | 3000000 | 600 | Todos os filtros, com sócio, raio, faturamento e funcionários |
A franquia renova no primeiro dia do mês-calendário e não acumula: crédito não usado em um mês não passa para o seguinte. No Free a chave nasce com 15 créditos e a verificação do e-mail libera os 60 do mês. Preços e a calculadora de custo estão em /precos; a mesma tabela em Markdown está em /pricing.md.
Quando a franquia acaba
Hard cap: a API responde 402 quota_exceeded e o header X-Credits-Reset diz quando a franquia renova. Não há cobrança por excedente nem recarga automática. Para continuar antes do reset, o assinante pago compra um pacote avulso, consumido depois da franquia, do mais antigo para o mais novo, com validade de 12 meses:
| Pacote | Preço | Créditos |
|---|---|---|
| Pacote 8 mil | R$ 50 | 8000 |
| Pacote 35 mil | R$ 200 | 35000 |
| Pacote 100 mil | R$ 500 | 100000 |
O Free não compra pacote; precisa assinar. Upgrade é imediato, cobra a diferença proporcional; downgrade vale no próximo ciclo. Pagamento por cartão ou PIX, com NFS-e em toda cobrança.
Rate limit
O limite de requisições por minuto é por conta: todas as chaves da conta somam no mesmo contador. Não há limite de concorrência nem de burst separado no v0. Ao exceder, a API responde 429 rate_limited com Retry-After em segundos; espere esse tempo e repita. Nas respostas 200 de consulta, busca e geração de filtro, X-RateLimit-Limit e X-RateLimit-Remaining mostram o limite do plano e o que sobra na janela corrente.
Os endpoints sem chave, GET /v1/status e GET /v1/demo, têm um limite próprio por endereço IP, porque não há conta para contar. Eles servem a páginas públicas e a testes, não a produção. O gerador de filtros (POST /v1/filters/generate) tem ainda um teto diário por conta; passar dele também responde 429 rate_limited com Retry-After.
Headers das respostas
O contrato declara, resposta por resposta, quais headers vêm em cada status. A regra geral: X-Request-Id em toda resposta; X-RateLimit-* nas que passaram pelo controle de requisições por conta, inclusive 4xx posteriores; X-Credits-* nas que passaram pela verificação de saldo, mesmo sem débito; Retry-After em 429 e 503.
| Header | Conteúdo |
|---|---|
X-Request-Id |
Identificador da chamada, o mesmo de meta.request_id; em toda resposta, inclusive antes da autenticação |
X-Client-Request-Id |
Eco do X-Request-Id que você enviou, quando ele tem 8 a 64 caracteres de A-Z a-z 0-9 _ -; ausente se não enviou ou o valor é inválido |
X-Credits-Charged |
Créditos desta chamada; 0 em página vazia e em 5xx após estorno |
X-Credits-Remaining |
Créditos restantes na franquia mais pacotes |
X-Credits-Reset |
Quando a franquia renova (RFC 3339) |
X-RateLimit-Limit |
Requisições por minuto do plano, por conta |
X-RateLimit-Remaining |
Requisições restantes no minuto corrente |
Retry-After |
Só em 429 e 503: segundos até tentar de novo |
Access-Control-Allow-Origin |
Só em GET /v1/status e GET /v1/demo, quando a resposta é produzida pela própria operação |
Cache-Control |
Só no 200 de GET /v1/status e dos arquivos de descoberta (/openapi.json, /robots.txt, /llms.txt, /.well-known/api-catalog): cache público |
Consultar o uso
GET /v1/usage custa 0 créditos e devolve a franquia, o consumo do ciclo, os pacotes, o limite de requisições por minuto e a data do reset. O portal mostra os mesmos números, com o débito de cada chamada por request_id. Na janela mensal de atualização da base, GET /v1/usage responde 503 maintenance como as demais operações.
curl
curl "https://api.cnpj.ia.br/v1/usage" \
-H "Authorization: Bearer $CNPJIA_KEY"
Campos da resposta, como o contrato os declara (sem envelope data):
| Campo | Tipo |
|---|---|
plan |
free ou starter ou pro ou business ou scale |
credits_allowance |
integer |
credits_used |
integer |
credits_remaining |
integer |
packs |
array de sku, credits_remaining, expires_at |
rpm |
integer |
search_enabled |
boolean |
cycle_reset_at |
string (date-time) |
Desempenho
A latência por endpoint passa a ser publicada em cnpjia.statuspage.io quando houver medição em produção. Até lá, nenhuma página das docs afirma número de latência, disponibilidade ou SLA.
Perguntas frequentes
Se eu ultrapassar a franquia, vou pagar excedente?
Não. A franquia tem hard cap: acabou, a API responde 402 quota_exceeded até o reset ou até você comprar um pacote avulso. Nenhuma cobrança acontece sem uma ação sua.
Crédito não usado passa para o mês seguinte?
O da franquia, não: ela renova no primeiro dia do mês-calendário e o saldo anterior zera. Os pacotes avulsos são diferentes: valem doze meses e só são consumidos depois da franquia.
O rate limit é por chave ou por conta?
Por conta. Todas as chaves da conta somam no mesmo contador de requisições por minuto. Criar mais chaves organiza o consumo, mas não multiplica o limite; para mais requisições por minuto, o caminho é o plano.
Erros e 404 consomem crédito?
Não. Só respostas 200 são cobradas. Um 404 not_found, um 429 rate_limited ou um 504 upstream_timeout deixam o saldo como estava.
Qual é a latência da API?
Ainda não publicamos número. A medição por endpoint em produção vai para a status page quando existir; até lá as docs não afirmam latência, disponibilidade nem SLA.