Hestia — Busca CEP

Endpoints

Todas as rotas do manual existem aqui. As três que esta base não alimenta devolvem 501 em vez de sumir da especificação — um cliente gerado do OpenAPI tem o método e recebe uma recusa explícita.

Método	Rota	O que devolve
POST	/token/v1/autentica	Token a partir de usuário e código de acesso
GET	/cep/v2/enderecos/{cep}	Endereço por CEP
GET	/cep/v2/enderecos	Listagem paginada, com filtro
GET	/cep/v1/localidades	Municípios
GET	/cep/v1/localidades/{uf}	Municípios de uma UF
GET	/cep/v1/bairros/{uf}/localidades/{id}	Bairros de um município
GET	/cep/v1/ufs	UFs e suas faixas de CEP
GET	/cep/v1/ufs/{uf}	Uma UF
GET	/cep/v1/atualizacao	Competência servida
GET	/cep/v1/localidades/cliques	501 — sem atributo de serviço na base
GET	/cep/v1/localidades/caixas-postais	501 — idem
GET	/cep/v1/localidades/agencias-modulares	501 — idem
GET	/saude	Estado do serviço e competência. Sem autenticação

Autenticação

Dois passos: o Basic troca por um token, o token vale uma hora.

# 1. token
curl -X POST https://hestia.ecomciencia.com/token/v1/autentica \
     -u "$USUARIO:$CODIGO_ACESSO"

# {"token":"eyJhbGciOiJIUzI1NiJ9...","expiraEm":"...","apis":["cep"]}

# 2. consulta
curl https://hestia.ecomciencia.com/cep/v2/enderecos/01001000 \
     -H "Authorization: Bearer $TOKEN"

Três diferenças em relação aos Correios

Nenhuma delas é do código: são da fonte, e por isso nenhuma implementação as fecha. Estão aqui porque descobri-las meses depois, num chamado de suporte, é pior.

A base é um retrato de uma competência

Não é o DNE ao vivo. Um CEP criado depois do fechamento da competência não está aqui, e uma rua que mudou de nome ainda aparece com o nome antigo. O /saude e o /cep/v1/atualizacao dizem qual competência está no ar.

Seis campos saem sempre nulos

abreviatura, numeroLocalidade, cepUnidadeOperacional, numeroInicial e numeroFinal não existem no extrato — e nomeUnidade só é preenchido em CEP de grande usuário. Eles vêm na resposta como null, nunca ausentes, para não quebrar cliente gerado do OpenAPI. numeroLocalidade em especial nunca recebe o código do IBGE: é outra numeração, e entregá-la ali seria um erro que o cliente não teria como perceber.

Três recursos devolvem 501

Cliques, caixas postais e agências modulares respondem sobre cobertura de serviço por localidade, e o extrato não traz atributo de serviço. Devolver uma lista derivada de busca textual daria uma resposta com aparência de autoridade e conteúdo de palpite.

Endpoints

Autenticação

Três diferenças em relação aos Correios

Documentação