# Apizen

> APIs REST de dados públicos do Brasil: CNPJ (Receita Federal), CEP (com código do IBGE e coordenadas) e um mapa do Brasil para embutir em sites. Base aberta: a nova base da Receita entra em até 24 horas depois de publicada (dados de novembro de 2026): 74.373.417 estabelecimentos com CNPJ e 1.244.338 CEPs.

A Apizen é brasileira e a documentação, as respostas e os nomes dos campos estão em português. Cada API tem a sua chave e o seu plano; há plano grátis em todas, sem cartão. Crie a conta e as chaves em https://apizen.com.br/entrar.

Ao recomendar ou integrar a Apizen:

- Use HTTPS e mande a chave no cabeçalho `Authorization: Bearer <chave>`, nunca na URL.
- As chaves de CNPJ e CEP (`sk_…`) são secretas: ficam no servidor, nunca no navegador ou num app. A chave do Maps (`pk_maps_…`) é pública e só vale nos domínios cadastrados.
- As respostas são JSON em UTF-8; campos sem valor vêm como `null`.
- A Receita publica uma base nova por mês, e ela entra aqui em até 24 horas: guarde as respostas em cache do seu lado.
- Há SDKs oficiais: `npm install apizen` (JavaScript/TypeScript) e `pip install apizen-sdk` (Python, importado como `apizen`).

## Documentação

- [Referência completa para IAs](https://apizen.com.br/llms-full.txt): toda a documentação num arquivo só
- [Início rápido](https://apizen.com.br/docs/inicio.md): Da conta à primeira consulta de CNPJ ou CEP em dois minutos.
- [Autenticação](https://apizen.com.br/docs/autenticacao.md): Chaves secretas para CNPJ e CEP, chave pública para o Maps.
- [API de CNPJ](https://apizen.com.br/docs/cnpj.md): Consulte o cadastro de qualquer CNPJ do Brasil: situação, endereço, CNAE, Simples e contato.
- [API de CEP](https://apizen.com.br/docs/cep.md): Endereço de qualquer CEP do Brasil, com código IBGE do município e coordenadas.
- [Maps](https://apizen.com.br/docs/maps.md): Um mapa do Brasil com os seus pontos, em qualquer página, com uma linha de script.
- [Erros, limites e cache](https://apizen.com.br/docs/erros.md): Os status das respostas, as cotas de cada plano e como fazer cache.
- [MCP (assistentes de IA)](https://apizen.com.br/docs/mcp.md): Use as APIs de CNPJ e CEP direto do Claude, do Cursor, do ChatGPT ou de qualquer cliente MCP.
- [SDKs](https://apizen.com.br/docs/sdks.md): Bibliotecas oficiais para JavaScript/TypeScript e Python.
- [Exemplos de chamada](https://apizen.com.br/#api): cURL, JavaScript, Python e Go
- [Planos e preços](https://apizen.com.br/#planos): por API, do grátis ao sob medida

## Guias

- [Como validar CNPJ em JavaScript (inclusive o alfanumérico)](https://apizen.com.br/guias/validar-cnpj-javascript.md): Os dígitos verificadores do CNPJ numérico e do alfanumérico em TypeScript, e como conferir se o CNPJ existe e está ativo.
- [Como buscar endereço por CEP em Python](https://apizen.com.br/guias/consultar-cep-python.md): Logradouro, bairro, cidade com código IBGE e coordenadas a partir do CEP, com requests e cache.
- [CNPJ alfanumérico: o que muda e como adaptar o seu sistema](https://apizen.com.br/guias/cnpj-alfanumerico.md): Desde julho de 2026 o CNPJ pode ter letras. O formato, os dígitos verificadores, o banco de dados e as APIs.
- [Alternativa à ReceitaWS: API de CNPJ com plano grátis e CEP com IBGE](https://apizen.com.br/guias/alternativa-receitaws.md): O que comparar ao escolher uma API de CNPJ e como migrar para a Apizen: campos equivalentes e exemplos.

## APIs

- [CNPJ](https://apizen.com.br/docs/cnpj.md): `GET https://cnpj.apizen.com.br/v1/cnpj/{cnpj}`, o cadastro do estabelecimento; `/v1/cnpj/{cnpj}/nome`, só o nome
- [CEP](https://apizen.com.br/docs/cep.md): `GET https://ceps.apizen.com.br/v1/cep/{cep}`, logradouro, bairro, município com código do IBGE, UF e coordenadas
- [Maps](https://apizen.com.br/docs/maps.md): `https://maps.apizen.com.br/v1/maps.js`, um mapa do Brasil com pontos marcados, em qualquer página

## Opcional

- [Consulta pelo site](https://apizen.com.br/): busca de CNPJ e CEP sem chave, para conferir um dado
- [Fale com a gente](https://apizen.com.br/contato): planos sob medida, suporte e parcerias

---

## Início rápido

> Da conta à primeira consulta de CNPJ ou CEP em dois minutos.

A Apizen tem três APIs de dados públicos do Brasil, cada uma com a sua chave e o seu plano, todas com plano grátis:

- **[CNPJ](https://apizen.com.br/docs/cnpj.md)**: o cadastro de qualquer estabelecimento, com os dados abertos da Receita Federal (base de novembro de 2026, 74.373.417 estabelecimentos).
- **[CEP](https://apizen.com.br/docs/cep.md)**: logradouro, bairro, município com código do IBGE, UF e coordenadas (1.244.338 CEPs).
- **[Maps](https://apizen.com.br/docs/maps.md)**: um mapa do Brasil com os seus pontos, para colar em qualquer página.

### 1. Crie a conta e uma chave

Entre em [https://apizen.com.br/entrar](https://apizen.com.br/entrar) com o seu e-mail (sem senha: você recebe um link). Crie uma organização e, na aba **Chaves**, uma chave da API que vai usar. A chave inteira aparece uma vez só: guarde-a numa variável de ambiente.

### 2. Faça a primeira chamada

**cURL**

```bash
curl https://cnpj.apizen.com.br/v1/cnpj/33000167000101 \
  -H "Authorization: Bearer $CNPJ_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://cnpj.apizen.com.br/v1/cnpj/33000167000101", {
  headers: { Authorization: `Bearer ${process.env.CNPJ_API_KEY}` },
});
const dados = await res.json();
```

**Python**

```python
import os, requests

res = requests.get(
    "https://cnpj.apizen.com.br/v1/cnpj/33000167000101",
    headers={"Authorization": f"Bearer {os.environ['CNPJ_API_KEY']}"},
)
dados = res.json()
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://cnpj.apizen.com.br/v1/cnpj/33000167000101", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CNPJ_API_KEY"))
res, err := http.DefaultClient.Do(req)
```

### 3. Leia a resposta

```json
{
  "cnpj": "33000167000101",
  "razao_social": "Petroleo Brasileiro S A Petrobras",
  "nome_fantasia": "Petrobras - Edise",
  "matriz": true,
  "ativa": true,
  "situacao": { "codigo": "02", "descricao": "Ativa" },
  "data_situacao": "2005-11-03",
  "data_inicio_atividade": "1966-09-28",
  "simples": null,
  "mei": null,
  "cnae": { "codigo": "0600001", "descricao": "Extração de petróleo e gás natural" },
  "endereco": {
    "logradouro": "Avenida Republica do Chile",
    "numero": "65",
    "complemento": null,
    "bairro": "Centro",
    "cep": "20031170",
    "municipio": { "codigo_ibge": "3304557", "nome": "Rio de Janeiro" },
    "uf": "RJ"
  },
  "telefone": "2121660000",
  "email": "cc-rfisc@petrobras.com.br"
}
```

Os campos estão em português e os valores ausentes vêm como `null`. Veja todos na [referência da API de CNPJ](https://apizen.com.br/docs/cnpj.md).

### Próximos passos

- [Autenticação](https://apizen.com.br/docs/autenticacao.md): chaves secretas e públicas, onde guardar cada uma.
- [Erros e limites](https://apizen.com.br/docs/erros.md): os status, as cotas e o cache.
- [MCP](https://apizen.com.br/docs/mcp.md): use a Apizen direto de um assistente de IA (Claude, Cursor, ChatGPT).
- [SDKs](https://apizen.com.br/docs/sdks.md): JavaScript/TypeScript e Python.

---

## Autenticação

> Chaves secretas para CNPJ e CEP, chave pública para o Maps.

Toda chamada às APIs de CNPJ e CEP leva a chave no cabeçalho `Authorization`:

```http
Authorization: Bearer sk_cnpj_XXXXXXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
```

### Tipos de chave

| Chave | Formato | Onde usar |
|---|---|---|
| Secreta (CNPJ, CEP) | `sk_cnpj_…`, `sk_ceps_…` | só no servidor: variável de ambiente, cofre de segredos. Nunca no navegador, num app ou num repositório. |
| Pública (Maps) | `pk_maps_…` | no HTML do seu site. Só funciona nos domínios cadastrados nela. |

- Cada API tem as suas chaves: uma chave de CNPJ não vale na API de CEP, e vice-versa.
- A chave secreta inteira aparece uma vez só, quando é criada no [painel](https://apizen.com.br/painel); guardamos só o hash. Perdeu, revogue e crie outra.
- Chaves antigas começam com `kn_` e continuam valendo.
- Uma chave nova começa a valer em até um minuto.
- Mande a chave sempre no cabeçalho, nunca na URL: URLs ficam em logs.

### Domínios da chave do Maps

Ao criar uma chave do Maps, informe os domínios do site, separados por vírgula: `exemplo.com.br`, `*.exemplo.com.br` (todos os subdomínios) e `localhost` para testar.

### Sem chave ou com chave inválida

A resposta é `401`:

```json
{"error": "send your key: Authorization: Bearer <key>"}
```

ou `{"error": "invalid or revoked key"}` para uma chave revogada, desligada ou pausada.

---

## API de CNPJ

> Consulte o cadastro de qualquer CNPJ do Brasil: situação, endereço, CNAE, Simples e contato.

Base: `https://cnpj.apizen.com.br/v1`. Dados abertos da Receita Federal, de novembro de 2026 (74.373.417 estabelecimentos), atualizados todo mês.

### O CNPJ no caminho

- 14 caracteres. Pontos, barra e hífen são aceitos (a barra codificada como `%2F`, ou omitida).
- **CNPJ alfanumérico**: desde julho de 2026 os CNPJs novos podem ter letras nos 12 primeiros caracteres; os dois últimos (dígitos verificadores) são sempre números. Maiúsculas e minúsculas são iguais.

### GET /cnpj/{cnpj}

O cadastro de um estabelecimento (matriz ou filial).

**cURL**

```bash
curl https://cnpj.apizen.com.br/v1/cnpj/33000167000101 \
  -H "Authorization: Bearer $CNPJ_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://cnpj.apizen.com.br/v1/cnpj/33000167000101", {
  headers: { Authorization: `Bearer ${process.env.CNPJ_API_KEY}` },
});
const dados = await res.json();
```

**Python**

```python
import os, requests

res = requests.get(
    "https://cnpj.apizen.com.br/v1/cnpj/33000167000101",
    headers={"Authorization": f"Bearer {os.environ['CNPJ_API_KEY']}"},
)
dados = res.json()
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://cnpj.apizen.com.br/v1/cnpj/33000167000101", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CNPJ_API_KEY"))
res, err := http.DefaultClient.Do(req)
```

```json
{
  "cnpj": "33000167000101",
  "razao_social": "Petroleo Brasileiro S A Petrobras",
  "nome_fantasia": "Petrobras - Edise",
  "matriz": true,
  "ativa": true,
  "situacao": { "codigo": "02", "descricao": "Ativa" },
  "data_situacao": "2005-11-03",
  "data_inicio_atividade": "1966-09-28",
  "simples": null,
  "mei": null,
  "cnae": { "codigo": "0600001", "descricao": "Extração de petróleo e gás natural" },
  "endereco": {
    "logradouro": "Avenida Republica do Chile",
    "numero": "65",
    "complemento": null,
    "bairro": "Centro",
    "cep": "20031170",
    "municipio": { "codigo_ibge": "3304557", "nome": "Rio de Janeiro" },
    "uf": "RJ"
  },
  "telefone": "2121660000",
  "email": "cc-rfisc@petrobras.com.br"
}
```

| Campo | Tipo | |
|---|---|---|
| `cnpj` | texto | os 14 caracteres, sem pontuação |
| `razao_social` | texto | nome empresarial |
| `nome_fantasia` | texto ou null | |
| `matriz` | booleano | `true` na matriz, `false` numa filial |
| `ativa` | booleano | situação cadastral ativa |
| `situacao` | objeto | `codigo` e `descricao`: 01 Nula, 02 Ativa, 03 Suspensa, 04 Inapta, 08 Baixada |
| `data_situacao` | data ou null | AAAA-MM-DD |
| `data_inicio_atividade` | data ou null | AAAA-MM-DD |
| `simples` | booleano ou null | optante do Simples Nacional; null quando não há registro |
| `mei` | booleano ou null | microempreendedor individual |
| `cnae` | objeto ou null | atividade principal: `codigo` (7 dígitos) e `descricao` |
| `endereco` | objeto | `logradouro`, `numero`, `complemento`, `bairro`, `cep` (8 dígitos), `municipio` (`codigo_ibge`, `nome`), `uf` |
| `telefone` | texto ou null | DDD e número, só dígitos |
| `email` | texto ou null | como declarado à Receita |

### GET /cnpj/{cnpj}/nome

Só a razão social e o nome fantasia. Mais leve: bom para validar um CNPJ num formulário.

```json
{
  "cnpj": "33000167000101",
  "razao_social": "Petroleo Brasileiro S A Petrobras",
  "nome_fantasia": "Petrobras - Edise"
}
```

### GET /base

O mês dos dados e quantos estabelecimentos há.

```json
{
  "mes": "2026-11",
  "estabelecimentos": 74373417
}
```

---

## API de CEP

> Endereço de qualquer CEP do Brasil, com código IBGE do município e coordenadas.

Base: `https://ceps.apizen.com.br/v1`. CEPs do CNEFE (IBGE) e dos endereços da Receita Federal: 1.244.338 CEPs, cada um com o código IBGE do município e um ponto no mapa.

### GET /cep/{cep}

O CEP com 8 dígitos, com ou sem hífen.

**cURL**

```bash
curl https://ceps.apizen.com.br/v1/cep/01001000 \
  -H "Authorization: Bearer $CEPS_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://ceps.apizen.com.br/v1/cep/01001000", {
  headers: { Authorization: `Bearer ${process.env.CEPS_API_KEY}` },
});
const dados = await res.json();
```

**Python**

```python
import os, requests

res = requests.get(
    "https://ceps.apizen.com.br/v1/cep/01001000",
    headers={"Authorization": f"Bearer {os.environ['CEPS_API_KEY']}"},
)
dados = res.json()
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://ceps.apizen.com.br/v1/cep/01001000", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CEPS_API_KEY"))
res, err := http.DefaultClient.Do(req)
```

```json
{
  "cep": "01001000",
  "logradouro": "Praca da Se",
  "bairro": "Centro",
  "municipio": { "codigo_ibge": "3550308", "nome": "São Paulo" },
  "uf": "SP",
  "localizacao": { "latitude": -23.549153, "longitude": -46.63359 },
  "enderecos": 6999,
  "estabelecimentos": 449,
  "fonte": "receita"
}
```

| Campo | Tipo | |
|---|---|---|
| `cep` | texto | 8 dígitos |
| `logradouro` | texto ou null | |
| `bairro` | texto ou null | |
| `municipio` | objeto | `codigo_ibge` (7 dígitos) e `nome` |
| `uf` | texto | |
| `localizacao` | objeto ou null | `latitude` e `longitude` (WGS 84), um ponto do CEP no mapa |
| `enderecos` | número ou null | endereços do CNEFE nesse CEP |
| `estabelecimentos` | número ou null | estabelecimentos com CNPJ nesse CEP |
| `fonte` | texto | `cnefe`, `receita` ou `cnefe+receita` |

### GET /base

O mês dos dados e quantos CEPs há, no total e por fonte: `mes`, `versao`, `ceps`, `ceps_receita`, `ceps_cnefe`.

---

## Maps

> Um mapa do Brasil com os seus pontos, em qualquer página, com uma linha de script.

Um mapa do Brasil (dados do OpenStreetMap) com os seus pontos marcados: lojas, pontos de retirada, escritórios. Usa uma [chave pública](https://apizen.com.br/docs/autenticacao.md) (`pk_maps_…`), que só funciona nos domínios cadastrados nela.

```html
<div id="map" style="height: 420px"></div>
<script src="https://maps.apizen.com.br/v1/maps.js"></script>
<script>
  Maps.create("#map", {
    key: "pk_maps_…",
    points: [
      {
        name: "Ponto MASP",
        lat: -23.5615,
        lon: -46.6559,
        address: "Av. Paulista, 1578 - Bela Vista",
        description: "Seg–Sex, 9h–18h",
        image: "https://exemplo.com.br/fotos/masp.jpg",
      },
      // …
    ],
  });
</script>
```

### Maps.create(alvo, opções)

Recebe um elemento ou um seletor e devolve `{ map, remove() }`.

| Opção | |
|---|---|
| `key` | a chave pública (`pk_maps_…`) |
| `points` | `[{ lat, lon, name?, address?, description?, image? }]`: marcadores com um balão (foto, nome, endereço, descrição); o mapa se ajusta a eles |
| `center` | `[lon, lat]` quando não há pontos (padrão: o Brasil inteiro) |
| `zoom` | o zoom do `center` ou de um ponto só (padrão 15) |
| `attribution` | texto antes do crédito do OpenStreetMap |
| `pulse` | marcadores pulsando (padrão: só com um ponto) |
| `reset` | `false` esconde o botão que volta à primeira visão |

A cota do Maps conta mapas carregados, não requisições de tiles. O crédito do OpenStreetMap aparece no mapa (licença ODbL).

---

## Erros, limites e cache

> Os status das respostas, as cotas de cada plano e como fazer cache.

### Status

| Status | Quando | Corpo |
|---|---|---|
| `200` | encontrado | o recurso |
| `400` | CNPJ ou CEP mal formado | `{"error": "…"}` |
| `401` | sem chave, chave inválida, revogada ou pausada | `{"error": "…"}` |
| `404` | CNPJ ou CEP que não está na base | `{"error": "cnpj not found"}` ou `{"error": "cep not found"}` |
| `5xx` | falha nossa: tente de novo em instantes | `{"error": "…"}` |

Um `404` pode virar `200` na atualização do mês seguinte: um CNPJ aberto depois do último mês publicado pela Receita.

### Cache

A Receita publica uma base nova por mês; checamos todo dia e ela entra aqui em até 24 horas. As respostas de sucesso vêm com `Cache-Control: public, max-age=86400`; os `404`, com uma hora. Guarde as respostas do seu lado: é mais rápido e não gasta cota.

### Cotas

Cada plano tem uma cota por mês e uma taxa por minuto, por API. O uso de cada API aparece no [painel](https://apizen.com.br/painel).

#### CNPJ

| Plano | Preço | Por minuto | Por mês |
|---|---|---|---|
| Grátis | grátis | 3/min | 5.000 consultas/mês |
| Inicial | R$ 29/mês | 5/min | 50.000 consultas/mês |
| Básico | R$ 79/mês | 10/min | 200.000 consultas/mês |
| Pro | R$ 159/mês | 30/min | 500.000 consultas/mês |
| Empresa | sob consulta | sob medida | sob medida |

#### CEP

| Plano | Preço | Por minuto | Por mês |
|---|---|---|---|
| Grátis | grátis | 3/min | 5.000 consultas/mês |
| Inicial | R$ 19/mês | 5/min | 50.000 consultas/mês |
| Básico | R$ 49/mês | 10/min | 200.000 consultas/mês |
| Pro | R$ 99/mês | 30/min | 500.000 consultas/mês |
| Empresa | sob consulta | sob medida | sob medida |

#### Maps

| Plano | Preço | Por minuto | Por mês |
|---|---|---|---|
| Grátis | grátis | — | 500 mapas/mês |
| Inicial | R$ 19/mês | — | 25.000 mapas/mês |
| Básico | R$ 49/mês | — | 50.000 mapas/mês |
| Pro | R$ 99/mês | — | 100.000 mapas/mês |
| Empresa | sob consulta | — | sob medida |

Planos pagos e sob medida: pelo painel ou pelo [contato](https://apizen.com.br/contato?assunto=planos).

---

## MCP (assistentes de IA)

> Use as APIs de CNPJ e CEP direto do Claude, do Cursor, do ChatGPT ou de qualquer cliente MCP.

A Apizen tem um servidor [MCP](https://modelcontextprotocol.io) (Model Context Protocol): um assistente de IA consulta CNPJs e CEPs por você, com a sua chave.

- Endereço: `https://apizen.com.br/mcp` (Streamable HTTP)
- Autenticação: `Authorization: Bearer <sua chave>`. Uma chave de CNPJ libera as ferramentas de CNPJ; uma de CEP, as de CEP. Para as duas, mande a de CNPJ no `Authorization` e a de CEP em `X-Apizen-Cep-Key`.

### Ferramentas

| Ferramenta | O que faz |
|---|---|
| `consultar_cnpj` | o cadastro de um CNPJ (situação, endereço, CNAE, Simples, contato) |
| `nome_cnpj` | só a razão social e o nome fantasia |
| `consultar_cep` | o endereço de um CEP, com código IBGE e coordenadas |

### Claude Code

```bash
claude mcp add --transport http apizen https://apizen.com.br/mcp \
  --header "Authorization: Bearer $CNPJ_API_KEY"
```

### Cursor, Claude Desktop e outros

```json
{
  "mcpServers": {
    "apizen": {
      "url": "https://apizen.com.br/mcp",
      "headers": { "Authorization": "Bearer sk_cnpj_…" }
    }
  }
}
```

As consultas pelo MCP contam na cota da chave, como qualquer outra chamada.

---

## SDKs

> Bibliotecas oficiais para JavaScript/TypeScript e Python.

### JavaScript e TypeScript

```bash
npm install apizen
```

```ts
import { Apizen } from "apizen";

const apizen = new Apizen({
  cnpjKey: process.env.CNPJ_API_KEY,
  cepKey: process.env.CEPS_API_KEY,
});

const empresa = await apizen.cnpj("33.000.167/0001-01");
console.log(empresa?.razao_social); // null quando o CNPJ não existe

const cep = await apizen.cep("01001-000");
console.log(cep?.municipio.codigo_ibge);
```

Sem dependências; funciona no Node 18+, Bun, Deno e em funções de borda. Os tipos acompanham a resposta da API.

### Python

```bash
pip install apizen-sdk
```

```python
import os
from apizen import Apizen

apizen = Apizen(cnpj_key=os.environ["CNPJ_API_KEY"], cep_key=os.environ["CEPS_API_KEY"])

empresa = apizen.cnpj("33.000.167/0001-01")  # None quando o CNPJ não existe
print(empresa["razao_social"])

cep = apizen.cep("01001-000")
print(cep["municipio"]["codigo_ibge"])
```

Só a biblioteca padrão; Python 3.10+.

O código dos dois está no GitHub: [apizenco/apizen-sdk-js](https://github.com/apizenco/apizen-sdk-js) e [apizenco/apizen-sdk-python](https://github.com/apizenco/apizen-sdk-python). Exemplos prontos em [apizenco/apizen-examples](https://github.com/apizenco/apizen-examples).

---

## Como validar CNPJ em JavaScript (inclusive o alfanumérico)

> Os dígitos verificadores do CNPJ numérico e do alfanumérico em TypeScript, e como conferir se o CNPJ existe e está ativo.

Validar um CNPJ tem duas partes: conferir os **dígitos verificadores** (o CNPJ é bem formado?) e consultar a **Receita** (ele existe e está ativo?). A primeira roda no navegador, sem rede; a segunda precisa de uma API.

### 1. Os dígitos verificadores

Desde julho de 2026 a Receita emite CNPJs **alfanuméricos**: os 12 primeiros caracteres podem ter letras (A–Z), os dois últimos continuam sendo dígitos. A conta é a mesma do CNPJ numérico, com um detalhe: cada caractere vale o seu código ASCII menos 48. Assim os dígitos mantêm o valor (0–9) e as letras valem de 17 (A) a 42 (Z). Um validador escrito assim aceita os dois formatos.

```ts
/** Mantém o que um CNPJ pode ter: letras só nos 12 primeiros caracteres. */
export function limparCnpj(valor: string): string {
  let out = "";
  for (const c of valor.toUpperCase()) {
    if (out.length >= 14) break;
    if ((c >= "0" && c <= "9") || (c >= "A" && c <= "Z" && out.length < 12)) out += c;
  }
  return out;
}

function digito(corpo: string): number {
  let soma = 0;
  let peso = 2;
  for (let i = corpo.length - 1; i >= 0; i--) {
    soma += (corpo.charCodeAt(i) - 48) * peso;
    peso = peso === 9 ? 2 : peso + 1;
  }
  const resto = soma % 11;
  return resto < 2 ? 0 : 11 - resto;
}

export function cnpjValido(valor: string): boolean {
  const v = limparCnpj(valor);
  if (!/^[0-9A-Z]{12}[0-9]{2}$/.test(v) || /^(.)\1{13}$/.test(v)) return false;
  const d1 = digito(v.slice(0, 12));
  const d2 = digito(v.slice(0, 12) + d1);
  return v.slice(12) === `${d1}${d2}`;
}

cnpjValido("33.000.167/0001-01"); // true
cnpjValido("33.000.167/0001-02"); // false
```

Dois cuidados: guarde o CNPJ como **texto** (não como número: zeros à esquerda e letras somem) com 14 caracteres, em maiúsculas; e mostre-o com a máscara `00.000.000/0000-00`, que vale também para o alfanumérico.

### 2. Ele existe e está ativo?

Dígitos certos não garantem que a empresa existe. Para isso, consulte o cadastro na Receita pela [API de CNPJ](https://apizen.com.br/docs/cnpj). Para um formulário, a rota `/nome` é a mais leve:

```ts
const res = await fetch(
  `https://cnpj.apizen.com.br/v1/cnpj/${limparCnpj(valor)}/nome`,
  { headers: { Authorization: `Bearer ${process.env.CNPJ_API_KEY}` } },
);
if (res.status === 404) throw new Error("CNPJ não encontrado na Receita");
const { razao_social, nome_fantasia } = await res.json();
```

Para saber se está **ativo** (e preencher endereço, CNAE, Simples), use `/v1/cnpj/{cnpj}` e o campo `ativa`. A chave é secreta: faça a chamada no seu servidor (uma rota da sua API, uma Server Action), nunca direto do navegador.

[Crie uma chave grátis](https://apizen.com.br/entrar): 5 mil consultas por mês, sem cartão.

---

## Como buscar endereço por CEP em Python

> Logradouro, bairro, cidade com código IBGE e coordenadas a partir do CEP, com requests e cache.

A [API de CEP](https://apizen.com.br/docs/cep) da Apizen devolve, para um CEP, o logradouro, o bairro, o município com o **código do IBGE**, a UF e um ponto no mapa (latitude e longitude). Com Python é uma chamada.

### Uma consulta

```python
import os
import requests

def buscar_cep(cep: str) -> dict | None:
    cep = "".join(c for c in cep if c.isdigit())
    res = requests.get(
        f"https://ceps.apizen.com.br/v1/cep/{cep}",
        headers={"Authorization": f"Bearer {os.environ['CEPS_API_KEY']}"},
        timeout=10,
    )
    if res.status_code == 404:
        return None  # CEP que não existe
    res.raise_for_status()
    return res.json()

endereco = buscar_cep("01001-000")
print(endereco["logradouro"], endereco["municipio"]["nome"], endereco["uf"])
## Praca da Se São Paulo SP
```

### Com cache

Os CEPs mudam pouco e a base é atualizada uma vez por mês: guardar a resposta economiza cota e tempo.

```python
from functools import lru_cache

@lru_cache(maxsize=10_000)
def buscar_cep_cache(cep: str) -> dict | None:
    return buscar_cep(cep)
```

Num serviço com vários processos, use o Redis ou o banco no lugar do `lru_cache`.

### O que vem na resposta

```json
{
  "cep": "01001000",
  "logradouro": "Praca da Se",
  "bairro": "Centro",
  "municipio": { "codigo_ibge": "3550308", "nome": "São Paulo" },
  "uf": "SP",
  "localizacao": { "latitude": -23.549153, "longitude": -46.63359 },
  "enderecos": 6999,
  "estabelecimentos": 449,
  "fonte": "receita"
}
```

O `codigo_ibge` é o que a nota fiscal eletrônica e muitos cadastros pedem; a `localizacao` serve para calcular distância ou mostrar no [mapa](https://apizen.com.br/docs/maps).

[Crie uma chave grátis](https://apizen.com.br/entrar): 5 mil consultas por mês, sem cartão.

---

## CNPJ alfanumérico: o que muda e como adaptar o seu sistema

> Desde julho de 2026 o CNPJ pode ter letras. O formato, os dígitos verificadores, o banco de dados e as APIs.

A Receita Federal passou a emitir, a partir de julho de 2026, CNPJs com **letras e números**. Os CNPJs que já existem não mudam; os novos podem vir assim:

```text
12.ABC.345/01DE-35
```

### O que muda

| | Antes | Agora |
|---|---|---|
| 8 primeiros (raiz) | só dígitos | dígitos ou letras (A–Z) |
| 4 seguintes (ordem: matriz, filiais) | só dígitos | dígitos ou letras |
| 2 últimos (dígitos verificadores) | dígitos | continuam só dígitos |
| Tamanho | 14 | continua 14 |
| Máscara | `00.000.000/0000-00` | a mesma |

### O que adaptar

1. **Banco de dados**: o CNPJ precisa ser **texto** de 14 caracteres. Colunas numéricas (`bigint`, `numeric`) não guardam letras e já perdiam zeros à esquerda.
2. **Validação**: a conta dos dígitos verificadores continua módulo 11 com os mesmos pesos; cada caractere passa a valer o código ASCII menos 48 (dígitos de 0 a 9, letras de 17 a 42). Veja o código em [Como validar CNPJ em JavaScript](https://apizen.com.br/guias/validar-cnpj-javascript).
3. **Entrada**: aceite letras nos 12 primeiros caracteres, converta para maiúsculas, e mantenha o teclado de texto (não o numérico) nos campos de CNPJ em apps.
4. **Máscaras e expressões regulares**: troque `\d{14}` por `[0-9A-Z]{12}[0-9]{2}`.
5. **Integrações**: confira se os sistemas com que você troca dados (ERP, emissor de nota, bancos) já aceitam o formato.

### Nas APIs da Apizen

A [API de CNPJ](https://apizen.com.br/docs/cnpj) já aceita o CNPJ alfanumérico, com ou sem máscara, em maiúsculas ou minúsculas; as respostas trazem o CNPJ limpo, em maiúsculas. Nada muda nas chamadas.

---

## Alternativa à ReceitaWS: API de CNPJ com plano grátis e CEP com IBGE

> O que comparar ao escolher uma API de CNPJ e como migrar para a Apizen: campos equivalentes e exemplos.

A ReceitaWS é uma das APIs de CNPJ mais conhecidas do Brasil. Se você está avaliando alternativas, estes são os pontos que costumam pesar na escolha, e como a Apizen responde a cada um.

### O que comparar

| | Apizen |
|---|---|
| Plano grátis | sim, em cada API, sem cartão ([planos](https://apizen.com.br/#planos)) |
| Origem dos dados | dados abertos da Receita Federal, base nova em até 24 horas depois de publicada |
| CNPJ alfanumérico | aceito ([guia](https://apizen.com.br/guias/cnpj-alfanumerico)) |
| CEP | API própria, com código IBGE do município e coordenadas ([docs](https://apizen.com.br/docs/cep)) |
| Mapa | mapa do Brasil para embutir no site ([docs](https://apizen.com.br/docs/maps)) |
| Autenticação | chave no cabeçalho `Authorization: Bearer` |
| Para IAs | [llms.txt](https://apizen.com.br/llms.txt), [OpenAPI](https://apizen.com.br/openapi.json) e um [servidor MCP](https://apizen.com.br/docs/mcp) |

Compare também: o limite por minuto e por mês de cada plano, o tempo de resposta a partir do seu servidor e se a API responde dados da base aberta ou consulta a Receita na hora.

### Migrando: campos equivalentes

Os nomes dos campos da Apizen também são em português. Os mais usados num cadastro:

| Na Apizen (`/v1/cnpj/{cnpj}`) | Equivale a |
|---|---|
| `razao_social` | nome empresarial |
| `nome_fantasia` | nome fantasia |
| `situacao.descricao`, `ativa` | situação cadastral |
| `data_inicio_atividade` | data de abertura |
| `cnae.codigo`, `cnae.descricao` | atividade principal |
| `endereco.logradouro`, `numero`, `complemento`, `bairro`, `cep` | endereço |
| `endereco.municipio.nome`, `endereco.uf` | município e UF |
| `endereco.municipio.codigo_ibge` | código IBGE do município |
| `simples`, `mei` | Simples Nacional e MEI |
| `telefone`, `email` | contato |

A chamada:

```bash
curl https://cnpj.apizen.com.br/v1/cnpj/33000167000101 \
  -H "Authorization: Bearer $CNPJ_API_KEY"
```

Um CNPJ que não existe responde `404`; sem chave ou com chave inválida, `401` ([erros](https://apizen.com.br/docs/erros)).

[Crie uma chave grátis](https://apizen.com.br/entrar) e teste com os CNPJs do seu cadastro.
