Consulta de CPF (lookups.cpf)

client.lookups.cpf consulta a situação cadastral de uma pessoa física pela API de Consulta de CPF, em https://naturalperson.api.nfe.io. A consulta exige o CPF e a data de nascimento.

Use a data_api_key

As consultas usam a chave de dados (data_api_key ou NFE_DATA_API_KEY). Veja Configuração.

Método

lookups.cpf(cpf, birth_date, *, options=None) -> NaturalPerson

Exemplo

from datetime import date

from nfeio import NfeClient, NotFoundError

client = NfeClient()

try:
    pessoa = client.lookups.cpf("529.982.247-25", date(1990, 1, 31))  # ou "1990-01-31"
except NotFoundError:
    print("CPF e data de nascimento não conferem")
else:
    print(pessoa["name"], pessoa.status)
    print(pessoa.federal_tax_number, pessoa.birth_on)  # "52998224725", datetime

• birth_date aceita date, datetime (só a data é usada) ou texto "AAAA-MM-DD".
• CPF e data que não conferem voltam como NotFoundError, e não como erro de validação: é assim que a API responde quando a combinação não existe.
• Propriedades tipadas de NaturalPerson: federal_tax_number (11 posições, como str), status e birth_on. O nome e os demais campos ficam no acesso por chave.

Validação local

O CPF tem os dígitos verificadores conferidos e a data tem o formato conferido antes da requisição. Um valor inválido levanta InvalidParameterError, sem cobrança:

from nfeio import InvalidParameterError, NfeClient

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

for cpf, nascimento in [("111.111.111-11", "1990-01-31"), ("529.982.247-25", "31/01/1990")]:
    try:
        client.lookups.cpf(cpf, nascimento)
    except InvalidParameterError as erro:
        print(erro.param, "-", erro)

Veja também

• Consulta de CNPJ e Consulta de CEP.