Consulta de CEP (lookups.cep)

client.lookups.cep devolve o endereço de um CEP pela API de Consulta de Endereços, em https://address.api.nfe.io. O uso mais comum é obter o código IBGE do município (city.code), exigido no endereço do tomador da NFS-e.

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.cep(cep, *, options=None) -> Address

Exemplo

from nfeio import NfeClient

client = NfeClient()

endereco = client.lookups.cep("01310-100")  # com ou sem traço
print(endereco.postal_code)                 # "01310100"
print(endereco["street"], endereco["district"])
print(endereco["city"]["code"], endereco["city"]["name"], endereco["state"])

Address tem uma propriedade tipada, postal_code (8 dígitos, sem traço). Os demais campos (street, streetSuffix, district, city, state, country, additionalInformation) ficam no acesso por chave.

Montar o endereço do tomador

from nfeio import NfeClient
from nfeio.types import AddressParams

client = NfeClient()

endereco = client.lookups.cep("01310-100")
address: AddressParams = {
    "country": "BRA",
    "postalCode": endereco.postal_code or "",
    "street": endereco["street"],
    "number": "2000",
    "district": endereco["district"],
    "city": {"code": endereco["city"]["code"], "name": endereco["city"]["name"]},
    "state": endereco["state"],
}

O resultado pode ir direto em borrower.address na emissão da NFS-e.

Validação local

O CEP precisa ter 8 dígitos (o traço é opcional). Fora disso, o SDK levanta InvalidParameterError antes da requisição:

from nfeio import InvalidParameterError, NfeClient

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

try:
    client.lookups.cep("0131-010")
except InvalidParameterError as erro:
    print(erro.param, "-", erro)  # cep - cep must have 8 digits, got '0131-010'

Um CEP com formato válido que não existe na base volta como erro da API (InvalidRequestError ou NotFoundError).

Veja também

• Consulta de CNPJ e Consulta de CPF.
• Notas de serviço: o endereço do tomador na emissão.