---
title: "Consulta de CNPJ (lookups.cnpj) no SDK Python da NFE.io"
description: "Consulte dados cadastrais e inscrições estaduais de uma empresa por CNPJ, numérico ou alfanumérico, com client.lookups.cnpj e cnpj_state_taxes (API v3)."
source_url: https://nfe.io/docs/desenvolvedores/bibliotecas/python/recursos/consulta-cnpj/
product: bibliotecas
last_updated: 2026-10-14
tags: ["python", "referencia", "consulta"]
integration: ["sdk"]
---

# Consulta de CNPJ (`lookups.cnpj`)

`client.lookups.cnpj` consulta os dados cadastrais de uma pessoa jurídica pela
[API de Consulta de CNPJ v3](/desenvolvedores/rest-api/consulta-de-cnpj-v3), em
`https://legalentity.api.nfe.io`. A v3 aceita o **CNPJ alfanumérico**.

:::note Use a `data_api_key`
As consultas usam a chave de dados (`data_api_key` ou `NFE_DATA_API_KEY`), não a principal. Com a
chave errada, a API responde `403` e o SDK levanta `PermissionDeniedError`. Veja
[Configuração](../configuration.md).
:::

## Métodos

```python
lookups.cnpj(cnpj, *, update_address=None, update_city_code=None, options=None) -> LegalEntity
lookups.cnpj_state_taxes(cnpj, state, *, options=None) -> LegalEntity
```

## Dados cadastrais

```python
from nfeio import NfeClient

client = NfeClient()

empresa = client.lookups.cnpj("00.000.000/0001-91")  # com ou sem máscara
print(empresa["name"], empresa["tradeName"])
print(empresa.federal_tax_number)  # "00000000000191"
print(empresa.status, empresa.opened_on, empresa.share_capital)  # str, datetime, Decimal
print(empresa["address"]["city"]["code"], empresa["address"]["state"])
```

Propriedades tipadas de `LegalEntity`: `federal_tax_number` (14 posições), `status`, `opened_on`,
`status_on` e `share_capital` (`Decimal`). Os demais campos (razão social, endereço, atividades,
sócios) ficam no acesso por chave, com os nomes da API.

`update_address=True` e `update_city_code=True` pedem à API que atualize o endereço e o código do
município a partir da base oficial.

## Inscrições estaduais

```python
from nfeio import NfeClient

client = NfeClient()

resultado = client.lookups.cnpj_state_taxes("00000000000191", "SP")
for inscricao in resultado["stateTaxes"]:
    print(inscricao["taxNumber"], inscricao["status"])
```

Devolve um `LegalEntity`, com a lista de inscrições no estado em `["stateTaxes"]`.

## Validação local

O SDK normaliza (remove pontos, barra e traço; converte letras para maiúsculas) e confere os
dígitos verificadores do CNPJ, numérico ou alfanumérico, e a UF **antes** da requisição. Um valor
inválido levanta `InvalidParameterError` e não gera cobrança:

```python
from nfeio import InvalidParameterError, NfeClient

client = NfeClient(api_key="chave-de-exemplo", data_api_key="chave-de-dados-de-exemplo")

try:
    client.lookups.cnpj("00.000.000/0001-00")
except InvalidParameterError as erro:
    print(erro.param, "-", erro)

try:
    client.lookups.cnpj_state_taxes("00000000000191", "XX")
except InvalidParameterError as erro:
    print(erro.param, "-", erro)
```

Um CNPJ válido que não existe na base da Receita volta como `NotFoundError`.

## Veja também

- [Consulta de CPF](./natural-person-lookup.md) e [Consulta de CEP](./addresses.md).
- [Empresas](./companies.md): cadastre a empresa emissora.