Braziliaanse belastingnummers komen in twee vormen, en ze uit elkaar houden is de eerste stap van elke validatie. De CPF identificeert een natuurlijke persoon; de CNPJ identificeert een rechtspersoon. Beide eindigen met twee controlecijfers in plaats van één, wat een iets ambitieuzere rekenkundige controle een bredere klasse van typfouten laat vangen.
Het paar is een goede casus omdat de nummers kort genoeg zijn om met de hand te controleren, oud genoeg dat hun regels overal openbaar zijn, en verschillend genoeg van elkaar dat één onzorgvuldige routine er minstens één verkeerd doet. Zo zijn ze opgebouwd en dit kan een validator er eerlijk over zeggen.
Wat zijn CPF en CNPJ?
De CPF is de registratie van de individuele belastingbetaler, het nummer waar een Braziliaanse burger om wordt gevraagd bij een balie van een bank, een hoteldienst of een online afrekenpagina. De CNPJ is de registratie van de zakelijke belastingbetaler, het nummer dat op elke factuur en elk visitekaartje van een bedrijf staat. De ene hoort bij een persoon, de andere bij een organisatie, en de registers erachter zijn gescheiden.
Omdat ze parallelle rollen spelen, worden de twee reeksen vaak samen besproken en samen geïmplementeerd, en het gedeelde vocabulaire verbergt dat hun interne opzet niet dezelfde is. Een ontwikkelaar die over de ene leest en aanneemt dat de andere identiek werkt, produceert een routine die geldige waarden ongeveer de helft van de tijd afwijst.
De reeksvoorbeelden in dit artikel zijn synthetische illustraties die alleen zijn gebouwd om te laten zien hoe de twee nummers zich gedragen. Geen echte registratie van enige persoon of enig bedrijf wordt hier weergegeven of aangepast, en een illustratie door de controle halen zegt niets over iemand.
Hoe de twee nummers in vorm verschillen
Het duidelijke verschil is dat het rechtspersoonnummer het langste van de twee is, wat een gevolg is van het grotere register en zijn interne onderverdelingen. Het persoonsnummer is de compactere vorm, afgestemd op een enkel individu zonder filialen.
Het structurele verschil is belangrijker dan de lengte. Het rechtspersoonformaat is samengesteld uit delen die de registratie van het bedrijf op meer dan één niveau identificeren, dus zijn interne velden zijn niet één homogeen blok cijfers. Het persoonsformaat is in wezen vlak: een serielichaam, een regiemarkering en de twee controlecijfers.
Geen van beide formaten moet worden beschreven door de exacte posities in proza op te dreunen. De gepubliceerde regels zijn de bron van waarheid, en een tabel die in een wikipagina wordt gekopieerd veroudert slecht. Behandel de opzet als data die de code leest, niet als kennis die over opmerkingen in drie bestanden is verdeeld.
Het idee van het controlecijfer: gewogen som, dan modulus
Beide formaten leiden hun afsluitende cijfers af met dezelfde familie van rekenkunde, twee keer toegepast. Elk van de laatste twee posities wordt berekend uit de cijfers ervoor: vermenigvuldig elk cijfer met een gewicht dat van zijn positie afhangt, tel de producten op, deel door een modulus, en zet de rest via een gepubliceerde omzetting om in een controlecijfer.
Het tweede cijfer wordt berekend nadat het eerste, en zijn berekening neemt het eerste cijfer op onder zijn invoer. Die ketening is de reden dat de twee niet onafhankelijk kunnen worden geverifieerd: de berekening van het tweede cijfer wijzigen zonder ook het eerste in te voeren, levert waarden op die op zichzelf goed lijken en in combinatie falen.
De familie is de op modulus gebaseerde die in controlecijferalgoritmen wordt besproken, en de omzettingsstap is waar naïeve implementaties afdwalen. Wanneer de deling een rest overlaat die zich niet rechtstreeks in één cijfer laat vertalen, zegt de gepubliceerde regel wat ermee te doen, en een routine die die stap weglaat, zal het met de standaard oneens zijn op een kleine maar reproduceerbare deelverzameling van invoer.
Waarom worden reeksen met allemaal hetzelfde cijfer uitgesloten?
Herhaalde cijfers zijn het klassieke tegenvoorbeeld voor elke modulaire controle. Een reeks die uit één herhaald teken bestaat, verslaat eenvoudige rekenkunde omdat de gewichten en de herhaalde waarden op een manier op elkaar inwerken die de som onveranderd laat, zodat het controlecijfer overeenkomend uitkomt. De gepubliceerde regels sluiten zulke reeksen daarom ronduit uit in plaats van erop te vertrouwen dat de rekenkunde ze opmerkt.
Die uitsluiting is geen beperking van het algoritme; het is een bewuste verklaring dat een registratienummer van die vorm nooit zal worden uitgegeven. Een validator die de rekenkunde implementeert maar de uitsluiting overslaat, accepteert een waarde die het register zelf nooit zou hebben gegenereerd, en dat is precies het soort gat waardoor plaatsvervangende tekst een formulier door glipt.
Dezelfde redenering is het veralgemenen waard. Telkens wanneer een schema een uitzondering definieert, maakt die uitzondering deel uit van de regel, niet van een optionele extra, en de plek om haar te implementeren is naast de rekenkunde in plaats van bij de aanroeper.
Formaatcontroles en registerstatus zijn verschillende dingen
Een geslaagde controle betekent dat de twee afsluitende cijfers overeenkomen met het lichaam. Niets meer. Of het nummer ooit is uitgegeven, of het nog actief is, of het bij de persoon hoort die het typt — dat alles leeft in het register van de belastingdienst, dat een offline routine niet kan zien.
Het register is ook het verkeerde ding om achteloos te raadplegen. Iemands belastingstatus opvragen is een andere activiteit dan controleren of een reeks goed gevormd is, en het draagt juridische en privacygevolgen die een formuliervalidatie nooit draagt. De rekenkunde lokaal bouwen en het register behandelen als een aparte, bewuste integratie voorkomt dat die twee zorgen in elkaar lekken.
De fouttekst moet dat onderscheid dragen. Een gebruiker die te horen krijgt dat zijn nummer ongeldig is, kan concluderen dat zijn registratie een probleem heeft, terwijl in feite alleen de reeks de rekenkunde niet haalde. De melding moet zeggen dat de cijfers niet overeenkomen, en de staat van de registratie erbuiten laten.
Voor ontwikkelaars: opschonen, maskeren en foutmeldingen
Een handvol gewoonten houdt dit paar schema’s uit de problemen.
- Normaliseer voor beide op dezelfde manier: verwijder de opmaaktekens, houd de cijfers, en onthoud dat opschonen geen reparatie is.
- Bepaal het schema uit de context, niet uit een gok. Vraag de aanroeper welk soort belastingbetaler het veld verwacht in plaats van het uit de lengte alleen af te leiden.
- Meld welk van de twee cijfers faalde, of dat beide faalden, want de positie van de fout wijst aan waar de typefout zit.
- Log nooit een volledige waarde in productietelemetrie. Registreer de uitspraak en een gemaskeerde vorm.
Dezelfde zorg geldt voor de mensen die de nummers lezen in plaats van de code. Een gemaskeerde vorm houdt genoeg voorste tekens om voor de eigenaar herkenbaar te zijn en laat genoeg achterste weg om voor alle anderen nutteloos te zijn, en de bespreking van het nationale ID-controlecijfer over vergelijking tussen landen is een nuttige metgezel wanneer een product meerdere rechtsgebieden tegelijk verwerkt. Als je product ook grensoverschrijdende rekeningidentificatoren accepteert, laat IBAN-structuur zien hoe een tweede, onafhankelijke controle binnen één reeks meerijdt.
Volgende stappen
Schrijf op welk van de twee schema’s elk veld in je product hoort te bevatten, en test je routine dan met een waarde waarvan het lichaam geldig is en de afsluitende cijfers niet. De nummervalidatietool laat je zien hoe een validator die uitkomst hoort te beschrijven, en nationale ID-validatieregels plaatst het paar in de bredere context van nummerstelsels die zijn ontworpen zonder aan elkaar te denken.