From 83ce95cf10fd9e9d581362453c558239d37ae06e Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:46:40 -0300 Subject: Name the municipality when the CEP does not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Answering only "não encontrei" wastes the trip. A CEP that fails is almost never a random number: it is someone who knows the city and guessed the rest, most often at the "-000" that 957 municipalities never received. The API now names that municipality on the 404, so the reply names it too. It stays an answer to a failure. No 📮, no address block, and no CEP suggested from inside the range — the range is sparse (Areal's 118 CEPs span nearly five thousand numbers), so the reply gives the count and says so instead of letting the two ends read as a list of valid CEPs. cep.is/go v0.1.0 discards the 404 body, so internal/lookup reads it with one extra GET, on that path alone and never inside a retry. Everything that can go wrong there — a slow answer, broken JSON, a faixa naming no municipality — falls back to the reply the bot has always given. The wrapper goes away the day the library exposes the field. --- README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index b81b553..aad82cf 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,36 @@ os dois casos: com precisão de logradouro sai um link de mapa; quando o CEP é geral do município, sai um aviso com o raio da área em vez de um pino, porque o ponto é o centroide da cidade e pode errar dezenas de quilómetros. +## Quando o CEP não existe + +Um CEP que falha quase nunca é um número aleatório — é alguém que sabe a cidade +e chutou o resto, quase sempre no `-000` que 957 municípios nunca receberam. +Dizer só "não encontrei" desperdiça a viagem, então o bot diz de que cidade o +número seria: + +``` +🔍 CEP não encontrado na base dos Correios (DNE). +Ele cairia em Areal/RJ, que tem 118 CEPs, de 25845-001 a 25849-899. +A faixa é esparsa: nem todo número entre os dois é um CEP válido. +Confira os oito dígitos — a base é atualizada a cada quinze dias. +``` + +Continua sendo um erro, e a resposta é escrita para não ser confundida com um +acerto: não é um endereço, e os dois extremos não são uma lista de CEPs +válidos — os 118 de Areal estão espalhados por quase cinco mil números, que é +para isso que a contagem vai junto. O bot também nunca sugere um CEP de dentro +da faixa. + +A cidade vem no próprio 404 da API, no objeto `faixa`. Quando o CEP cai num +intervalo que os Correios não deram a município nenhum, o objeto não vem e a +resposta é a de sempre, sem a linha do meio. + +Por enquanto isso custa um GET a mais, e só no caminho do 404: o `cep.is/go` +v0.1.0 joga fora o corpo da resposta 404, e é de lá que a faixa é lida +(`internal/lookup`). Qualquer problema nessa segunda consulta — lentidão, JSON +quebrado, faixa sem município — cai de volta na resposta de sempre. Some quando +a biblioteca expuser o campo. + ## Criando o bot O username e o token são criados por você no -- cgit v1.3