diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 42 |
1 files changed, 42 insertions, 0 deletions
@@ -204,6 +204,48 @@ try { `RateLimitedException` exposes `retryAfter`, `ServerException` exposes `status`, and `NetworkException` exposes `cause`. +### When the CEP does not exist + +A failing CEP is rarely random: it is usually someone who knows the city and +guessed the number — and the classic guess is the `-000`, which 957 +municipalities never received. So `CepNotFoundException` may carry a `faixa` +naming the municipality the CEP *would* have belonged to: + +```dart +try { + final address = await cepis.lookup('25845-000'); +} on cepis.CepNotFoundException catch (e) { + final faixa = e.faixa; + if (faixa != null) { + faixa.localidade; // 'Areal' + faixa.uf; // 'RJ' + faixa.ibge; // '3300225' + faixa.cepIni; // '25845001' (the API's `cep_ini`) + faixa.cepFim; // '25849899' (the API's `cep_fim`) + faixa.ceps; // 118 + } +} +``` + +Three things this is not: + +- **Not an address.** The response is still a 404 and the CEP still does not + exist. `faixa` is context for the error — enough to say "did you mean somewhere + in Areal/RJ?" — and never a value to save as the user's address. +- **Not the Correios' published range.** `cepIni` and `cepFim` are the smallest + and the largest CEP that *actually exist* in the municipality. The DNE's own + start for Areal is `25845000` — exactly the CEP that just failed, which is why + echoing it back would be useless. +- **Not a range of valid CEPs.** It is sparse: Areal's 118 CEPs are scattered + over the ~9000 numbers between the two bounds. That is what `ceps` is for. Do + not iterate the interval and do not offer it as a list of alternatives. + +`faixa` is `null` when the CEP falls in a numeric band no municipality owns — the +API **omits** the block there rather than sending null — and also whenever the +block cannot be read. A malformed one never costs you the clean not-found. + +`e.toString()` mentions the municipality when there is one. + `InvalidCepException` also implements `FormatException`, so code already handling malformed input during validation keeps working without knowing this library exists. |