> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cnpj-api.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skill CNPJ

> Ensine seu agente de IA a consultar dados de empresas brasileiras com um único comando

**Agent Skill** oficial da cnpj-api.com para agentes de codificação com IA (Claude Code, Cursor, Codex, Windsurf, OpenCode e +40 outros). Instala um pacote de conhecimento que o agente já sabe usar: autenticação, endpoints, tratamento de erros e formatação de CNPJ já vêm configurados.

<Frame>
  <img src="https://mintcdn.com/cnpj-api/EtnpaZNB1KGEaYtW/images/skill-cnpj/install-flow.svg?fit=max&auto=format&n=EtnpaZNB1KGEaYtW&q=85&s=9dc85c42751ef81c209ac5192ff6d53a" alt="Instalação com um comando e agente usando a skill" width="960" height="260" data-path="images/skill-cnpj/install-flow.svg" />
</Frame>

## Instalação rápida

Para a maioria dos agentes (Claude Code, Cursor, Codex, Windsurf, etc.), rode no diretório do seu projeto:

```bash theme={null}
npx skills add cnpj-api/skills
```

O CLI coloca os arquivos no diretório correto do seu agente (`.claude/skills/`, `.cursor/skills/`, etc.) automaticamente.

<Note>
  Usando **Claude.ai na web ou no desktop**? A interface web não roda `npx`. Siga o guia
  [Instalar no Claude manualmente](/pt/skill-cnpj-claude-manual) para fazer o upload do ZIP diretamente.
</Note>

## Configuração

1. Crie uma conta grátis em [cnpj-api.com](https://cnpj-api.com) e gere um token.
2. Exporte o token como variável de ambiente:

```bash theme={null}
export CNPJ_API_TOKEN="seu-token-aqui"
```

O agente lê essa variável sempre que a skill for acionada. Nunca armazena ou loga o valor.

## O que está incluído

Cobertura completa da cnpj-api via 8 endpoints:

| Endpoint                    | Plano   | Descrição                         |
| --------------------------- | ------- | --------------------------------- |
| `GET /v1/cnpj/{cnpj}`       | free+   | Dados completos da empresa        |
| `POST /v1/bulk-cnpj`        | **pro** | Consulta em lote (até 20)         |
| `GET /v1/simples/{cnpj}`    | free+   | Status Simples Nacional e SIMEI   |
| `GET /v1/socios/{pessoaId}` | free+   | Perfil do sócio e participações   |
| `GET /v1/cidades/{id}`      | free+   | Agregados por município (IBGE)    |
| `GET /v1/cnae/{cnae}`       | free+   | Agregados por atividade econômica |
| `GET /v1/usage`             | free+   | Plano atual e rate limit          |

Além de scripts auxiliares (`validate-cnpj.ts` e `bulk-lookup.ts`).

## Como usar

Depois de instalada, peça ao agente em linguagem natural:

<CardGroup cols={2}>
  <Card title="Consulta simples" icon="magnifying-glass">
    *"Consulte o CNPJ 82.845.322/0001-04"*
  </Card>

  <Card title="Simples Nacional" icon="shield-check">
    *"Essa empresa é Simples Nacional?"*
  </Card>

  <Card title="Sócios" icon="users">
    *"Me dá os sócios dessa empresa"*
  </Card>

  <Card title="Consulta em lote" icon="layer-group">
    *"Enriquece essa lista de 50 CNPJs"*
  </Card>
</CardGroup>

O agente escolhe o endpoint correto, trata erros, respeita o rate limit e monta as chamadas com `api-token` automaticamente.

## Compatibilidade

Funciona com qualquer agente que suporte o formato [Agent Skills](https://agentskills.io):

<CardGroup cols={4}>
  <Card title="Claude Code" />

  <Card title="Cursor" />

  <Card title="Codex" />

  <Card title="Windsurf" />

  <Card title="OpenCode" />

  <Card title="Amp" />

  <Card title="Antigravity" />

  <Card title="+35 outros" />
</CardGroup>

## Limites e planos

Veja planos e preços em [cnpj-api.com/precos](https://cnpj-api.com/precos). Consulta em lote (`/v1/bulk-cnpj`) requer o plano **Pro**.

## Código aberto

A skill é **MIT** e pública:

* **Repositório:** [github.com/cnpj-api/skills](https://github.com/cnpj-api/skills)
* **Especificação Agent Skills:** [agentskills.io](https://agentskills.io)

Issues e PRs são bem-vindos.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Instalar no Claude manualmente" icon="upload" href="/pt/skill-cnpj-claude-manual">
    Guia passo a passo para Claude.ai (web e desktop) com upload de ZIP.
  </Card>

  <Card title="Repositório no GitHub" icon="github" href="https://github.com/cnpj-api/skills">
    Ver o código da skill, SKILL.md, referências e scripts.
  </Card>
</CardGroup>