Expose the faixa a missing CEP would have belonged toHEADv0.2.0main

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. The API now attaches that municipality to
the 404, and a caller left with nothing but "does not exist" cannot tell
a typo in a real city from a CEP that was never plausible.

It goes in CEPIS-STATUS, not CEPIS-ADDRESS. The call has still failed
and the address is still empty; putting a localidade where the address
lives would let a caller that forgets to test the status read Areal as
the answer to a CEP that does not exist.

Parsing is best effort throughout. faixa is omitted rather than sent as
null for a band no municipality owns, so its absence is the normal case
and there is a flag instead of a marker value; a block that is missing,
is not an object, or is short of localidade, uf, cep_ini, cep_fim and
ceps is dropped and the not-found comes back clean. Failing a 404 the
caller already understands over a decoration on it would be a poor
trade.

cep_ini and cep_fim are the CEPs that exist, not the bounds the Correios
publish, and the span between them is mostly empty -- hence ceps beside
them, so the pair is not read as a list.

1 files changed, 30 insertions, 1 deletions

diff --git a/copy/cepis-status.cpy b/copy/cepis-status.cpy
index 75632c8..b98a753 100644
--- a/copy/cepis-status.cpy
+++ b/copy/cepis-status.cpy
@@ -1,7 +1,7 @@
 *> ---------------------------------------------------------------------
 *> Status layout without its 01 level, so the library can keep a private
 *> scratch status alongside the caller's without duplicating the
-*> definition. Replace the field-name tag and the level number.
+*> definition. Replace the field-name tag and the two level numbers.
 *>
 *> The six failure categories are split by the decision the caller has to
 *> make, not by the HTTP status that produced them.
@@ -21,3 +21,32 @@
 :L1:  :P:-STATUS-RETRY-AFTER-MS    PIC S9(9)
                                    SIGN IS LEADING SEPARATE.
 :L1:  :P:-STATUS-ATTEMPTS          PIC 9(4).
+
+*> The municipality a CEP that does not exist would have belonged to.
+*> Context for the error, never an address: the lookup is still
+*> :P:-NOT-FOUND and CEPIS-ADDRESS is still empty. Only GET /{cep} fills
+*> it, so it stays absent after a batch or a health call.
+*>
+*> :P:-FAIXA-CEP-INI and :P:-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. The range is sparse: Areal's 118 CEPs are
+*> scattered over the ~4900 numbers between 25845001 and 25849899, so the
+*> pair is a span to show a human, never a list of valid CEPs. That is
+*> what :P:-FAIXA-CEPS counts.
+*>
+*> The API omits "faixa" -- it never sends null -- when the CEP falls in
+*> a band no municipality owns, so test the flag before reading anything
+*> below it.
+:L1:  :P:-FAIXA.
+  :L2:  :P:-FAIXA-PRESENT          PIC X.
+        88  :P:-FAIXA-KNOWN        VALUE "Y".
+        88  :P:-FAIXA-ABSENT       VALUE "N".
+  :L2:  :P:-FAIXA-LOCALIDADE       PIC X(100).
+  :L2:  :P:-FAIXA-UF               PIC X(2).
+  :L2:  :P:-FAIXA-ESTADO           PIC X(60).
+  :L2:  :P:-FAIXA-REGIAO           PIC X(30).
+  :L2:  :P:-FAIXA-IBGE             PIC X(10).
+  :L2:  :P:-FAIXA-CEP-INI          PIC X(8).
+  :L2:  :P:-FAIXA-CEP-FIM          PIC X(8).
+  :L2:  :P:-FAIXA-CEPS             PIC 9(9).