Les numéros fiscaux brésiliens se présentent sous deux formes, et les distinguer est la première étape de toute validation. Le CPF identifie une personne physique ; le CNPJ identifie une personne morale. Tous deux se terminent par deux chiffres de contrôle plutôt qu’un seul, ce qui permet à une arithmétique un peu plus ambitieuse d’intercepter une classe plus large de fautes de frappe.
Ce couple est une bonne étude de cas, car ces numéros sont assez courts pour être vérifiés à la main, assez anciens pour que leurs règles soient publiques partout, et assez différents l’un de l’autre pour qu’une routine unique et négligée se trompe au moins sur l’un des deux. Voici comment ils sont construits et ce qu’un validateur peut honnêtement en dire.
Que sont le CPF et le CNPJ ?
Le CPF est le registre d’imposition des personnes physiques, le numéro qu’on demande à un citoyen brésilien au guichet d’une banque, à la réception d’un hôtel ou lors d’un paiement en ligne. Le CNPJ est le registre d’imposition des entreprises, le numéro imprimé sur chaque facture et chaque carte de visite qu’une société émet. L’un appartient à une personne, l’autre à une organisation, et les registres qui les sous-tendent sont distincts.
Parce qu’ils jouent des rôles parallèles, les deux chaînes sont souvent discutées et implémentées ensemble, et le vocabulaire partagé masque le fait que leurs dispositions internes ne sont pas identiques. Un développeur qui lit la documentation de l’un et suppose que l’autre fonctionne de la même manière produira une routine qui rejette des valeurs valides environ une fois sur deux.
Les exemples de chaînes de cet article sont des illustrations synthétiques construites uniquement pour montrer comment les deux numéros se comportent. Aucune immatriculation réelle appartenant à une personne ou à une entreprise n’est reproduite ni adaptée ici, et faire passer une illustration par le contrôle ne dit rien sur qui que ce soit.
En quoi les deux numéros diffèrent par leur forme
La différence évidente est que le numéro de personne morale est le plus long des deux, ce qui découle d’un registre plus vaste et de ses subdivisions internes. Le numéro de personne physique est la forme la plus compacte, dimensionnée pour un individu unique sans succursales.
La différence structurelle compte davantage que la longueur. Le format de personne morale est assemblé à partir d’éléments qui identifient l’immatriculation de l’entreprise à plus d’un niveau, si bien que ses champs internes ne forment pas un bloc homogène de chiffres. Le format de personne physique est essentiellement plat : un corps de série, un marqueur de région et les deux chiffres de contrôle.
Aucun des deux formats ne devrait être décrit en récitant ses positions exactes en prose. Les règles publiées sont la source de vérité, et un tableau recopié dans une page wiki vieillit mal. Traitez la disposition comme une donnée que le code lit, et non comme une connaissance répartie dans les commentaires de trois fichiers.
L’idée du chiffre de contrôle : somme pondérée, puis modulo
Les deux formats dérivent leurs chiffres finaux avec la même famille d’arithmétique, appliquée deux fois. Chacune des deux dernières positions est calculée à partir des chiffres qui la précèdent : multipliez chaque chiffre par un poids qui dépend de sa position, additionnez les produits, divisez par un modulo et convertissez le reste en chiffre de contrôle au moyen d’une correspondance publiée.
Le second chiffre est calculé après le premier, et son calcul inclut le premier chiffre parmi ses entrées. C’est cet enchaînement qui empêche de vérifier les deux indépendamment : modifier le calcul du second chiffre sans aussi y injecter le premier produit des valeurs qui semblent correctes isolément et échouent en combinaison.
Cette famille est celle fondée sur un modulo, étudiée dans les algorithmes de chiffre de contrôle, et l’étape de correspondance est celle où les implémentations naïves dérivent. Lorsque la division laisse un reste qui ne se traduit pas directement en un seul chiffre, la règle publiée indique quoi en faire, et une routine qui omet cette étape divergera de la norme sur un sous-ensemble d’entrées petit mais reproductible.
Pourquoi les séquences de chiffres tous identiques sont-elles exclues ?
Les chiffres répétés sont le contre-exemple classique de tout contrôle modulaire. Une chaîne composée d’un seul caractère répété défait l’arithmétique simple, car les poids et les valeurs répétées interagissent d’une manière qui laisse le total inchangé, de sorte que le chiffre de contrôle ressort en correspondance. Les règles publiées excluent donc d’emblée de telles chaînes plutôt que de compter sur l’arithmétique pour les repérer.
Cette exclusion n’est pas une limite de l’algorithme ; c’est l’affirmation délibérée qu’un numéro d’immatriculation de cette forme ne sera jamais émis. Un validateur qui implémente l’arithmétique mais omet l’exclusion acceptera une valeur que le registre lui-même n’aurait jamais générée, ce qui est exactement le type de faille qui laisse passer un texte de remplacement dans un formulaire.
Le même raisonnement mérite d’être généralisé. Chaque fois qu’un schéma définit une exception, cette exception fait partie de la règle, et non d’un supplément facultatif, et l’endroit où l’implémenter est à côté de l’arithmétique plutôt que chez l’appelant.
Les contrôles de format et le statut au registre sont deux choses différentes
Un contrôle réussi signifie que les deux chiffres finaux s’accordent avec le corps. Rien de plus. Savoir si le numéro a déjà été émis, s’il est encore actif, s’il appartient à la personne qui le saisit — tout cela réside dans le registre de l’administration fiscale, qu’une routine hors ligne ne peut pas voir.
Le registre est aussi la mauvaise chose à consulter à la légère. Interroger le statut fiscal de quelqu’un est une activité différente de la vérification qu’une chaîne est bien formée, et elle comporte des conséquences juridiques et de confidentialité qu’une validation de formulaire n’a jamais. Construire l’arithmétique localement et traiter le registre comme une intégration séparée et délibérée évite que ces deux préoccupations ne se contaminent.
Le libellé des erreurs doit porter cette distinction. Un utilisateur à qui l’on dit que son numéro est invalide peut en conclure que son immatriculation a un problème, alors qu’en réalité seule la chaîne a échoué à l’arithmétique. Le message doit dire que les chiffres ne s’accordent pas, et laisser l’état de l’immatriculation en dehors de cela.
Pour les développeurs : nettoyage, masquage et messages d’erreur
Quelques habitudes gardent ce couple de schémas hors de difficulté.
- Normalisez de la même façon pour les deux : retirez les marques de présentation, gardez les chiffres, et rappelez-vous que nettoyer n’est pas réparer.
- Décidez du schéma d’après le contexte, pas d’après une supposition. Demandez à l’appelant quel type de contribuable le champ attend plutôt que de le déduire de la seule longueur.
- Signalez lequel des deux chiffres a échoué, ou si les deux ont échoué, car la position de l’échec indique où se trouve la faute de frappe.
- Ne journalisez jamais une valeur complète dans la télémétrie de production. Consignez le verdict et une forme masquée.
Le même soin s’applique aux personnes qui lisent les numéros plutôt qu’au code. Une forme masquée conserve assez de caractères de tête pour être reconnaissable par son propriétaire et retire assez de caractères de queue pour être inutile à tous les autres, et la discussion sur le chiffre de contrôle des pièces d’identité nationales à propos de la comparaison entre pays est un complément utile lorsqu’un produit gère plusieurs juridictions à la fois. Si votre produit accepte aussi des identifiants de compte transfrontaliers, la structure IBAN montre comment un second contrôle indépendant voyage à l’intérieur d’une seule chaîne.
Étapes suivantes
Notez lequel des deux schémas chaque champ de votre produit est censé contenir, puis testez votre routine avec une valeur dont le corps est autorisé et dont les chiffres finaux ne le sont pas. L’outil de validation de numéros vous montrera comment un validateur doit décrire ce résultat, et les règles de validation des pièces d’identité nationales replace ce couple dans le contexte plus large de systèmes de numérotation conçus sans tenir compte les uns des autres.