diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 78 |
1 files changed, 67 insertions, 11 deletions
@@ -6,7 +6,7 @@ widget fills the street, neighbourhood, city and state fields you point it at. Official Correios data (DNE). One `<script>` tag, no build step, no framework, no dependencies. -**3.3 KB minified and gzipped** (7.7 KB minified, 7859 bytes). +**3.7 KB minified and gzipped** (8.8 KB minified, 9042 bytes). ```html <script src="cepis-autofill.js"></script> @@ -134,15 +134,16 @@ to render nothing and drive your own UI from `onStatus`. Every failure has its own message, in Portuguese, and reaches both the status region and `onError`: -| `error.code` | message | worth retrying? | -| ------------------ | ------------------------------------------------------------------------- | --------------- | -| `invalid` | CEP inválido. Digite os 8 dígitos. | no | -| `not_found` | CEP não encontrado. Confira o número ou preencha o endereço manualmente. | no | -| `rate_limited` | Muitas consultas em pouco tempo. Aguarde alguns segundos e tente de novo. | later | -| `server` | O serviço de CEP está indisponível. Preencha o endereço manualmente. | later | -| `network` | Não foi possível consultar o CEP. Verifique sua conexão e tente de novo. | later | -| `timeout` | A consulta do CEP demorou demais. Tente de novo ou preencha manualmente. | later | -| `invalid_response` | Resposta inesperada do serviço de CEP. Preencha o endereço manualmente. | probably not | +| `error.code` | message | worth retrying? | +| ------------------ | ----------------------------------------------------------------------------------------- | --------------- | +| `invalid` | CEP inválido. Digite os 8 dígitos. | no | +| `not_found` | CEP não encontrado. Confira o número ou preencha o endereço manualmente. | no | +| `not_found` + city | CEP não encontrado. Esse número seria de Areal/RJ, que tem CEPs de 25845-001 a 25849-899. | no | +| `rate_limited` | Muitas consultas em pouco tempo. Aguarde alguns segundos e tente de novo. | later | +| `server` | O serviço de CEP está indisponível. Preencha o endereço manualmente. | later | +| `network` | Não foi possível consultar o CEP. Verifique sua conexão e tente de novo. | later | +| `timeout` | A consulta do CEP demorou demais. Tente de novo ou preencha manualmente. | later | +| `invalid_response` | Resposta inesperada do serviço de CEP. Preencha o endereço manualmente. | probably not | Override any of them with `messages`: @@ -156,6 +157,59 @@ CepisAutofill.attach({ `rate_limited` carries `retryAfterMs` and `server` carries `status`. +### When the CEP does not exist, but the city does + +A CEP that fails is rarely a random number. It is usually someone who knows +the city and guessed the last digits — most often the `-000` that 957 +municipalities never received. Areal/RJ, for one, answers from `25845-001` +up, and never at `25845-000`. + +So when the API can tell which municipality the number would have belonged +to, the message says it: + +> CEP não encontrado. Esse número seria de Areal/RJ, que tem CEPs de +> 25845-001 a 25849-899. + +**Nothing is filled in.** This is still a `not_found`: the address does not +exist, so the widget writes no field — not the city, not the state, nothing. +Filling the city from a CEP that does not exist would quietly produce a wrong +address, which is worse than an empty form. Only the wording of the message +changes. + +The range is not a list of valid CEPs either. `cep_ini` and `cep_fim` are the +lowest and the highest CEP that really exist in that municipality, and what +lies between them is sparse — Areal has 118 CEPs spread over some 4,900 +numbers. Show it as a hint of where to look; never suggest a CEP from inside +it. + +Where the API says nothing about a municipality, the plain +`CEP não encontrado…` message stands, exactly as before. The same goes for a +reply this widget cannot make sense of. + +Two extra entries in `messages` carry the wording, with `{localidade}`, +`{uf}`, `{cep_ini}` and `{cep_fim}` filled in: + +| key | used when | +| ---------------------- | ------------------------------------------- | +| `not_found_city_range` | the municipality and its first and last CEP | +| `not_found_city` | the municipality, but no usable range | + +```js +CepisAutofill.attach({ + cep: "#cep", + localidade: "#cidade", + messages: { + not_found_city_range: + "Esse CEP não existe. Em {localidade}/{uf} eles vão de {cep_ini} a {cep_fim}.", + }, +}); +``` + +`onError` gets the whole thing as `error.faixa` — `localidade`, `uf`, and +whichever of `estado`, `regiao`, `ibge`, `cep_ini`, `cep_fim` and `ceps` the +API sent — for a richer UI of your own. It is absent, never null, when there +is no municipality to name. + ### Looking a CEP up yourself `CepisAutofill.lookup` is the request layer on its own — same cache, same @@ -169,7 +223,9 @@ address.uf; // "SP" It resolves to the API's own JSON: Portuguese field names, empty strings rather than nulls, and `geo` present only for the roughly 57% of CEPs that -have a coordinate. +have a coordinate. It rejects with a `CepisAutofillError`, whose `faixa` — +when the CEP does not exist but its municipality does — is +[described above](#when-the-cep-does-not-exist-but-the-city-does). ## Mapping your platform's fields |