From 82d92ed4291663bae94014b4363064dbb26c6a51 Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:25:04 -0300 Subject: Name the municipality behind a CEP that does not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A CEP that fails a lookup is rarely a random number: it is usually someone who knows the city and guessed the digits, and the classic guess is the -000 that 957 municipalities never received. The API now attaches a faixa block to the 404 naming the municipality that band belongs to, so the caller can answer "no, but you were looking at Areal/RJ" instead of just "no". It stays an error. Faixa hangs off CepNotFoundException, never off Address, and cepIni/cepFim are the extremes that actually exist in the municipality rather than the range the Correios publish — echoing back the published start would return the very CEP that just failed. The interval is sparse, which is what ceps is for; it is not a list of alternatives. Parsing is deliberately forgiving: a missing, empty or malformed block is null. Losing a clean not-found to a parse error over the hint attached to it would be a bad trade. --- CHANGELOG.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'CHANGELOG.md') diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f9e0cb..df0c793 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## 0.2.0 + +- `CepNotFoundException` now carries `faixa`: the municipality the CEP would + have belonged to, when the API names one. Still a 404 — it is context for the + error, not an address. +- New `Faixa` model. Its `cepIni`/`cepFim` are the smallest and the largest CEP + that *exist* in the municipality, not the Correios' published bounds, and the + interval between them is sparse — read `ceps` for how sparse. +- `CepNotFoundException.toString` mentions the municipality when there is one. +- A missing, empty or malformed `faixa` yields `null` and never turns a + not-found into a parse failure. + ## 0.1.0 - First release: `lookup`, `lookupMany`, `health` and `normalizeCep`, with -- cgit v1.3