Consulta de CNPJ (lookups.cnpj)

client.lookups.cnpj consulta os dados cadastrais de uma pessoa jurídica pela API de Consulta de CNPJ v3, em https://legalentity.api.nfe.io. A v3 aceita o CNPJ alfanumérico.

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.

Métodos

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

Dados cadastrais

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

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:

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 e Consulta de CEP.
• Empresas: cadastre a empresa emissora.