---
title: "POST /v1/filters/generate"
description: "Gerar filtros de busca a partir de linguagem natural"
canonical: "https://cnpj.ia.br/docs/referencia/generate-filter"
date_modified: 2026-09-02
source: "cnpj.ia.br"
---

docs · base agosto/2026 Atualizado em 02/09/2026

# POST /v1/filters/generate

Gerar filtros de busca a partir de linguagem natural

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.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `descricao` | `string` máx. 500 caracteres | Sim | — |

```json
{
  "descricao": "fabricantes de embalagens em Joinville com mais de 50 funcionários"
}
```

## Respostas

### 200 OK

Filtros sugeridos, prontos para `searchCnpjs`.

| Header | Tipo | Descrição |
| --- | --- | --- |
| `X-Request-Id` | `string` | Identificador da requisição para suporte. |
| `X-Credits-Charged` | `integer` | Créditos debitados nesta resposta. |
| `X-Credits-Remaining` | `integer` | Créditos restantes (franquia + pacotes). |
| `X-Credits-Reset` | `string` formato: `date-time` | Instante do próximo reset da franquia (RFC 3339). |
| `X-RateLimit-Limit` | `integer` | Requisições por minuto do plano (por conta). |
| `X-RateLimit-Remaining` | `integer` | Requisições restantes no minuto corrente. |

### 400 Requisição inválida

Filtro desconhecido ou valor fora do enum.

### 401 Não autorizado

Chave ausente, desconhecida, revogada ou expirada.

### 402 Pagamento necessário

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

### 429 Excesso de requisições

Requisições por minuto da conta excedidas. Header Retry-After.

| Header | Tipo | Descrição |
| --- | --- | --- |
| `Retry-After` | `integer` | Só em 429 e 503: segundos até tentar de novo. |

## 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

```bash
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 mais de 50 funcionários"}'
```