Consulta de endereços (addresses)

O recurso $nfe->addresses consulta endereços por CEP. Faz parte da família de dados addresses, servida por address.api.nfe.io/v2 (o host já embute a versão).

Família de dados — configure dataApiKey

addresses usa a dataApiKey quando presente, com fallback para a apiKey. Configure dataApiKey: para separar a chave de consulta da chave de emissão. Veja Configuração.

Métodos

Método	Descrição	Retorno
lookupByPostalCode($cep)	Consulta um endereço por CEP.	AddressLookupResponse

CEP é o único endpoint

Não existe busca por termo livre nem por filtro — lookupByPostalCode() é o único método. Não procure search()/lookupByTerm(): esses endpoints não existem mais na API.

Consultar por CEP

$nfe = new Nfe\Client(
    apiKey: $_ENV['NFE_API_KEY'],
    dataApiKey: $_ENV['NFE_DATA_API_KEY'] ?? null,
);

$resposta = $nfe->addresses->lookupByPostalCode('01310-100');

$endereco = $resposta->addresses[0];
$endereco['street'];         // "Avenida Paulista"
$endereco['city'] ?? null;   // dados do município

$resposta->raw;              // payload original completo, se precisar

O CEP é aceito com ou sem hífen e é normalizado para 8 dígitos.

CEP é validado antes do HTTP

Um CEP que não normalize para 8 dígitos lança Nfe\Exception\InvalidRequestException antes de qualquer requisição. Veja Tratamento de erros.

O envelope { address } é desembrulhado

A API responde { "address": { … } }; o SDK desembrulha para ->addresses — uma lista de 1 elemento — para manter o shape estável.

Veja também

• Configuração — modelo de duas chaves e dataApiKey.
• Consulta de CNPJ e Consulta de CPF — outras famílias de dados.