API de consulta de CEP compatível com a Busca CEP dos Correios: mesmos caminhos, mesmos nomes de campo, mesmos códigos de retorno.
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 |
| POST | /mcp | Camada MCP para agentes de IA — ver abaixo |
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"
Além do contrato dos Correios, o Hestia fala o
Model Context Protocol em
POST /mcp — o padrão aberto pelo qual plataformas agênticas
descobrem e usam ferramentas. O agente consulta CEP como uma ferramenta, sem
código de integração, e deixa de preencher endereço de memória.
| Ferramenta | O que faz |
|---|---|
| consultar_cep | Endereço de um CEP. Devolve encontrado: false se o CEP não estiver na competência servida |
| buscar_enderecos | Busca por UF, município, bairro ou prefixo do logradouro, até 50 por página |
| listar_localidades | Municípios, com o id usado na busca, o código IBGE e o DDD |
| hestia://competencia | Recurso: de qual extrato vêm as respostas |
# OpenClaw openclaw mcp add hestia --url https://hestia.ecomciencia.com/mcp \ --header "Authorization=Bearer $TOKEN_MCP" # Claude Code claude mcp add --transport http hestia https://hestia.ecomciencia.com/mcp \ --header "Authorization: Bearer $TOKEN_MCP" # .mcp.json (Claude Code e clientes com o mesmo formato) {"mcpServers": {"hestia": {"type": "http", "url": "https://hestia.ecomciencia.com/mcp", "headers": {"Authorization": "Bearer $TOKEN_MCP"}}}}
Não é o token de uma hora do /token/v1/autentica: é emitido
pela Ecomciência para a sua credencial, vale até um ano e só funciona em
/mcp — as rotas REST o recusam, e o /mcp recusa o
token delas. Revogar a credencial ou trocar o código de acesso o invalida
na hora. Para obter, escreva para
[email protected].
Cada consulta pelo MCP conta como uma consulta da API; descobrir as ferramentas não conta. O CEP consultado não é registrado, pela mesma razão que no REST: um CEP diz onde alguém mora.
Funciona com qualquer cliente MCP que envie cabeçalho de autorização — conferido com o cliente oficial do protocolo e com o OpenClaw. Conectores que exigem login OAuth ainda não são atendidos.
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.
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.
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.
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.