I numeri fiscali brasiliani si presentano in due forme, e distinguerle è il primo passo di qualsiasi validazione. Il CPF identifica una persona fisica; il CNPJ identifica una persona giuridica. Entrambi si chiudono con due cifre di controllo anziché una, il che permette a un controllo aritmetico un po’ più ambizioso di intercettare una classe più ampia di errori di digitazione.
La coppia è un buon caso di studio perché i numeri sono abbastanza corti da verificare a mano, abbastanza antichi che le loro regole sono pubbliche ovunque, e abbastanza diversi tra loro che un’unica routine distratta ne sbaglierà almeno uno. Ecco come sono costruiti e cosa un validatore può onestamente dire su di essi.
Cosa sono il CPF e il CNPJ?
Il CPF è la registrazione fiscale individuale, il numero che a un cittadino brasiliano viene chiesto allo sportello di una banca, alla reception di un hotel o a una cassa online. Il CNPJ è la registrazione fiscale delle imprese, il numero stampato su ogni fattura e biglietto da visita che un’azienda emette. Uno appartiene a una persona, l’altro a un’organizzazione, e i registri che li sostengono sono separati.
Poiché svolgono ruoli paralleli, le due stringhe sono spesso discusse insieme e implementate insieme, e il vocabolario condiviso nasconde il fatto che le loro disposizioni interne non sono le stesse. Uno sviluppatore che legge di uno e presume che l’altro funzioni allo stesso modo produrrà una routine che rifiuta valori validi circa la metà delle volte.
Gli esempi di stringa in questo articolo sono illustrazioni sintetiche costruite solo per mostrare come si comportano i due numeri. Nessuna registrazione reale appartenente a una persona o a una società è qui riprodotta o adattata, e far passare un’illustrazione attraverso il controllo non dice nulla su nessuno.
In che cosa differiscono nella forma i due numeri
La differenza evidente è che il numero della persona giuridica è il più lungo dei due, il che è una conseguenza del registro più grande e delle sue suddivisioni interne. Il numero della persona è la forma più compatta, dimensionata per un singolo individuo senza filiali.
La differenza strutturale conta più della lunghezza. Il formato della persona giuridica è assemblato da parti che identificano la registrazione della società a più di un livello, quindi i suoi campi interni non sono un unico blocco omogeneo di cifre. Il formato della persona è essenzialmente piatto: un corpo seriale, un marcatore di regione e le due cifre di controllo.
Nessuno dei due formati dovrebbe essere descritto recitando le sue posizioni esatte in prosa. Le regole pubblicate sono la fonte di verità, e una tabella copiata in una pagina wiki invecchia male. Tratta la disposizione come dati che il codice legge, non come conoscenza distribuita attraverso i commenti in tre file.
L’idea della cifra di controllo: somma ponderata, poi modulo
Entrambi i formati derivano le loro cifre finali con la stessa famiglia di aritmetica, applicata due volte. Ciascuna delle ultime due posizioni è calcolata dalle cifre che la precedono: moltiplica ogni cifra per un peso che dipende dalla sua posizione, somma i prodotti, dividi per un modulo e converti il resto in una cifra di controllo tramite una mappatura pubblicata.
La seconda cifra è calcolata dopo la prima, e il suo calcolo include la prima cifra tra i suoi input. È questa concatenazione il motivo per cui le due non possono essere verificate in modo indipendente: cambiare il calcolo della seconda cifra senza inserire anche la prima produce valori che sembrano corretti in isolamento e falliscono in combinazione.
La famiglia è quella basata sul modulo passata in rassegna in Algoritmi cifra di controllo, e il passo di mappatura è il punto in cui le implementazioni ingenue si allontanano. Quando la divisione lascia un resto che non si traduce direttamente in una singola cifra, la regola pubblicata dice cosa farne, e una routine che omette quel passo sarà in disaccordo con lo standard su un sottoinsieme di input piccolo ma riproducibile.
Perché le sequenze con tutte cifre uguali sono escluse?
Le cifre ripetute sono il controesempio classico a qualsiasi controllo modulare. Una stringa composta da un unico carattere ripetuto sconfigge l’aritmetica semplice perché i pesi e i valori ripetuti interagiscono in modo da lasciare il totale invariato, quindi la cifra di controllo risulta corrispondente. Le regole pubblicate escludono quindi tali stringhe in partenza anziché affidarsi all’aritmetica per notarle.
Quell’esclusione non è un limite dell’algoritmo; è un’affermazione deliberata che un numero di registrazione di quella forma non verrà mai emesso. Un validatore che implementa l’aritmetica ma salta l’esclusione accetterà un valore che il registro stesso non avrebbe mai generato, ed è esattamente il tipo di lacuna che lascia passare un testo segnaposto attraverso un modulo.
Lo stesso ragionamento vale la pena di generalizzarlo. Ogni volta che uno schema definisce un’esclusione, l’esclusione fa parte della regola, non è un extra opzionale, e il posto per implementarla è accanto all’aritmetica anziché nel chiamante.
Controlli di formato e stato del registro sono cose diverse
Una prova superata significa che le due cifre finali concordano con il corpo. Niente di più. Se il numero è stato mai emesso, se è ancora attivo, se appartiene alla persona che lo sta digitando — tutto questo vive nel registro dell’autorità fiscale, che una routine offline non può vedere.
Il registro è anche la cosa sbagliata da consultare con leggerezza. Interrogare lo stato fiscale di qualcuno è un’attività diversa dal verificare che una stringa sia ben formata, e comporta conseguenze legali e di privacy che una validazione di modulo non ha mai. Costruire l’aritmetica localmente e trattare il registro come un’integrazione separata e deliberata impedisce a queste due preoccupazioni di infiltrarsi l’una nell’altra.
La formulazione degli errori deve portare con sé quella distinzione. Un utente a cui viene detto che il suo numero non è valido può concludere che la sua registrazione abbia un problema, quando in realtà solo la stringa ha fallito l’aritmetica. Il messaggio dovrebbe dire che le cifre non concordano, e tenere fuori lo stato della registrazione.
Per gli sviluppatori: pulizia, mascheramento e messaggi di errore
Poche abitudini tengono questa coppia di schemi fuori dai guai.
- Normalizza allo stesso modo per entrambi: elimina i segni di presentazione, conserva le cifre e ricorda che pulire non è riparare.
- Decidi lo schema dal contesto, non da un’ipotesi. Chiedi al chiamante quale tipo di contribuente si aspetta il campo invece di dedurlo dalla sola lunghezza.
- Segnala quale delle due cifre è fallita, o se lo sono entrambe, perché la posizione del fallimento indica dove si trova l’errore di battitura.
- Non registrare mai un valore completo nella telemetria di produzione. Registra il giudizio e una forma mascherata.
La stessa cura vale per le persone che leggono i numeri anziché il codice. Una forma mascherata conserva abbastanza caratteri iniziali da essere riconoscibile per il suo proprietario e ne elimina abbastanza di finali da essere inutile per tutti gli altri, e la trattazione delle regole di validazione dei documenti di identità per paese è un utile accompagnamento quando un prodotto gestisce più ordinamenti contemporaneamente. Se il tuo prodotto accetta anche identificatori di conto transfrontalieri, Struttura IBAN mostra come un secondo controllo, indipendente, viaggia dentro un’unica stringa.
Passi successivi
Annota quale dei due schemi ogni campo del tuo prodotto deve contenere, poi prova la tua routine con un valore il cui corpo è lecito e le cui cifre finali non lo sono. Lo strumento di validazione dei numeri ti mostrerà come un validatore dovrebbe descrivere quell’esito, e le regole di validazione dei documenti di identità collocano la coppia nel più ampio contesto dei sistemi di numerazione progettati senza tener conto l’uno dell’altro.