POST /v1/filters/generate

Converte uma descrição em português nos filtros aceitos por searchCnpjs. Custa 1 crédito. Tem limite próprio de uso por conta.

Créditos

chamada · 1 crédito

Corpo da requisição

Corpo application/json, obrigatório.

{
  "descricao": "fabricantes de embalagens em Joinville com e-mail"
}

Respostas

200 OK

Filtros sugeridos, prontos para searchCnpjs.

{
  "data": {
    "uf": "SP",
    "explicacao": "São Paulo"
  },
  "meta": {
    "request_id": "req_01J8ZK3Q9X",
    "source": "rfb_open_data+oportunidados",
    "data_as_of": "2026-09-01",
    "credits_charged": 1,
    "credits_remaining": 59,
    "credits_reset_at": "2026-10-01T00:00:00-03:00"
  }
}

400 Requisição inválida

descricao ausente, vazia ou com mais de 500 caracteres.

{
  "error": {
    "code": "invalid_filter",
    "message": "Um ou mais parâmetros da requisição são inválidos. Consulte a documentação.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#invalid_filter"
  }
}

401 Não autorizado

Chave ausente, desconhecida, revogada ou expirada.

{
  "error": {
    "code": "invalid_api_key",
    "message": "Chave de API ausente ou inválida.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#invalid_api_key"
  }
}

402 Pagamento necessário

Franquia e pacotes esgotados. Header X-Credits-Reset.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Créditos insuficientes para esta operação. Aguarde a renovação ou adquira mais créditos.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#quota_exceeded"
  }
}

403 Proibido

Conta com billing_state blocked (payment_required).

{
  "error": {
    "code": "payment_required",
    "message": "Sua conta está com pagamento pendente. Regularize para continuar usando a API.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#payment_required"
  }
}

404 Não encontrado

API desligada (CNPJIA_API_ENABLED diferente de on).

{
  "error": {
    "code": "not_found",
    "message": "Recurso não encontrado.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#not_found"
  }
}

429 Excesso de requisições

Limite por minuto da conta, teto diário do gerador ou store do gerador indisponível. Header Retry-After. Sem X-RateLimit-* quando o limite atingido é o de requisições sem chave por IP.

{
  "error": {
    "code": "rate_limited",
    "message": "Limite de requisições excedido. Tente novamente em instantes.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#rate_limited"
  }
}

500 Erro interno

Saída do modelo não interpretável. retryable: true; a operação não é cobrada. Se houve liquidação, o estorno é tentado e pode ficar pendente de retentativa ou recuperação manual. X-RateLimit-* presentes quando a requisição passou pelo controle de requisições por conta; X-Credits-* presentes quando passou pela verificação de saldo (mesmo sem débito). Ausentes quando a falha é anterior (por exemplo, ao consultar o estado da base).

{
  "error": {
    "code": "internal_error",
    "message": "Erro interno. Tente novamente; se persistir, fale com o suporte.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#internal_error"
  }
}

503 Serviço indisponível

Janela mensal de atualização da base. Header Retry-After.

{
  "error": {
    "code": "maintenance",
    "message": "A base está em manutenção. Tente novamente em instantes.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#maintenance"
  }
}

504 Tempo esgotado

Timeout de consulta. retryable: true; nada é cobrado. X-RateLimit-* presentes quando a requisição passou pelo controle de requisições por conta; X-Credits-* presentes quando passou pela verificação de saldo (mesmo sem débito). Ausentes quando a falha é anterior (por exemplo, ao consultar o estado da base).

{
  "error": {
    "code": "upstream_timeout",
    "message": "A operação demorou mais que o esperado. Tente novamente.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#upstream_timeout"
  }
}

Ferramenta MCP

No servidor MCP oficial esta operação é a ferramenta gerar_filtro, com a mesma chave e os mesmos créditos da API.

Exemplo

curl -s "https://api.cnpj.ia.br/v1/filters/generate" \
  -X POST \
  -H "Authorization: Bearer $CNPJIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"descricao":"fabricantes de embalagens em Joinville com e-mail"}'