diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 52 |
1 files changed, 50 insertions, 2 deletions
@@ -168,7 +168,7 @@ CALL "CEPIS-NORMALIZE-CEP" USING CEPIS-CEP-INPUT CEPIS-CEP CEPIS-STATUS | `CFG-BACKOFF-BASE-MS` | `500` | base of the exponential wait | | `CFG-BACKOFF-MAX-MS` | `8000` | cap on each wait, `Retry-After` included | | `CFG-TOTAL-TIMEOUT-MS` | `0` | cap on the whole call, attempts and waits included; `0` means none | -| `CFG-USER-AGENT` | `cepis-cobol/0.1.0 (+https://cep.is)` | identifies the library and version | +| `CFG-USER-AGENT` | `cepis-cobol/0.2.0 (+https://cep.is)` | identifies the library and version | Retries cover 429, 5xx and transport failures, with exponential backoff and full jitter; 400 and 404 are never retried. @@ -189,7 +189,7 @@ already retried on its own before giving up. | condition | when | does retrying help? | | --- | --- | --- | | `CEPIS-INVALID-CEP` | not 8 digits | no | -| `CEPIS-NOT-FOUND` | well-formed, not in the database | no | +| `CEPIS-NOT-FOUND` | well-formed, not in the database; see `CEPIS-FAIXA` | no | | `CEPIS-RATE-LIMITED` | 429; see `CEPIS-STATUS-RETRY-AFTER-MS` | yes, later | | `CEPIS-SERVER-ERROR` | 5xx; see `CEPIS-STATUS-HTTP` | yes, later | | `CEPIS-NETWORK-ERROR` | DNS, connection, timeout, TLS | yes, later | @@ -211,6 +211,54 @@ status seen and `CEPIS-STATUS-ATTEMPTS` how many attempts were made. API is answering instead of it — a captive Wi-Fi portal, a corporate proxy, an HTML error page. Useful as a diagnosis: the problem is not in your code. +### Where a missing CEP would have been + +A `CEPIS-NOT-FOUND` from `CEPIS-LOOKUP` may also carry `CEPIS-FAIXA`: the +municipality the CEP would have belonged to. A CEP that fails is rarely a +random number — it is someone who knows the city and guessed the digits, +and the classic guess is the `-000` that 957 municipalities never received. + +```cobol +IF CEPIS-NOT-FOUND AND CEPIS-FAIXA-KNOWN + DISPLAY "no such CEP -- " FUNCTION TRIM (CEPIS-FAIXA-LOCALIDADE) + "/" CEPIS-FAIXA-UF " has " CEPIS-FAIXA-CEPS + " CEPs, from " CEPIS-FAIXA-CEP-INI + " to " CEPIS-FAIXA-CEP-FIM +END-IF +``` + +**It is still a 404.** The lookup failed, `CEPIS-ADDRESS` is empty, and +nothing in `CEPIS-FAIXA` is an address for the CEP that was asked for. It +says where the guess landed, not what it resolves to. + +`CEPIS-FAIXA-CEP-INI` and `CEPIS-FAIXA-CEP-FIM` are the smallest and the +largest CEP the municipality **actually has**, not the bounds the Correios +publish. The DNE's own start for Areal/RJ is `25845000` — exactly the CEP +that just failed, which is why the range comes back starting one past it, +at `25845001`. + +**The span is sparse, and it is not a list.** Areal's 118 CEPs are +scattered over the ~4900 numbers between `25845001` and `25849899`; almost +none of that interval exists either. That is what `CEPIS-FAIXA-CEPS` is +for — show it next to the pair, and never iterate the two as a range. + +The API omits `faixa` — it never sends it as null — when the CEP falls in a +band no municipality owns, so **test `CEPIS-FAIXA-KNOWN` before reading +anything below it.** A `faixa` that is missing, malformed, or short of its +members leaves the flag off and the not-found otherwise untouched; a +decoration on an error is never worth failing that error over. + +Only `CEPIS-LOOKUP` fills it. `CEPIS-LOOKUP-MANY` and `CEPIS-HEALTH` clear +it, so `CEPIS-FAIXA-ABSENT` holds after a batch or a health call and a +faixa never survives from one lookup into the next. + +| field | bytes | | field | bytes | +| --- | --- | --- | --- | --- | +| `faixa-localidade` | 100 | | `faixa-ibge` | 10 | +| `faixa-uf` | 2 | | `faixa-cep-ini` | 8 | +| `faixa-estado` | 60 | | `faixa-cep-fim` | 8 | +| `faixa-regiao` | 30 | | `faixa-ceps` | `9(9)` | + ## Field widths COBOL records are fixed width. A value longer than its field is truncated |