NAME¶
Business::BR::CPF - Perl module to test for correct CPF numbers
SYNOPSIS¶
use Business::BR::CPF;
print "ok " if test_cpf('390.533.447-05'); # prints 'ok '
print "bad " unless test_cpf('231.002.999-00'); # prints 'bad '
DESCRIPTION¶
The CPF number is an identification number of Brazilian citizens emitted by the
Brazilian Ministry of Revenue, which is called "Ministerio da
Fazenda".
CPF stands for "Cadastro de Pessoa Fisica" (literally, physical person
registration) as opposed to the CNPJ number for companies.
The CPF is comprised of a base of 9 digits and 2 check digits. It is usually
written like '231.002.999-00' so as to be more human-readable.
This module provides "test_cpf" for checking that a CPF number is
correct. Here a
correct CPF number means
- •
- it is 11 digits long
- •
- it satisfies the two check equations mentioned below
Before checking, any non-digit letter is stripped, making it easy to test
formatted entries like '231.002.999-00' and entries with extra blanks like '
999.221.222-00 '.
- test_cpf
-
test_cpf('999.444.333-55') # incorrect CPF, returns 0
test_cpf(' 263.946.533-30 ') # is ok, returns 1
test_cpf('888') # nope, returns undef
Tests whether a CPF number is correct. Before testing, any non-digit
character is stripped. Then it is expected to be 11 digits long and to
satisfy two check equations which validate the last two check digits. See
"THE CHECK EQUATIONS".
The policy to get rid of '.' and '-' is very liberal. It indeeds discards
anything that is not a digit (0, 1, ..., 9) or letter. That is handy for
discarding spaces as well
test_cpf(' 263.946.533-30 ') # is ok, returns 1
But extraneous inputs like '#333%444*2.3+2-00' are also accepted. If you are
worried about this kind of input, just check against a regex:
warn "bad CPF: only digits (11) expected"
unless ($cpf =~ /^\d{11}$/);
warn "bad CPF: does not match mask '___.___.___-__'"
unless ($cpf =~ /^\d{3}\.\d{3}\.\d{3}-\d{2}$/);
NOTE. Integer numbers like 9999811299 (or 99_998_112_99) with fewer than 11
digits will be normalized (eg. to "09999811299") before
testing.
- canon_cpf
-
canon_cpf(99); # returns '00000000099'
canon_cpf('999.999.999-99'); # returns '99999999999'
Brings a candidate for a CPF number to a canonical form. In case, the
argument is an integer, it is formatted to at least eleven digits.
Otherwise, it is stripped of any non-alphanumeric characters and returned
as it is.
- format_cpf
-
format_cpf('00000000000'); # returns '000.000.000-00'
Formats its input into '000.000.000-00' mask. First, the argument is
canon'ed and then dots and hyphen are added to the first 11 digits of the
result.
- parse_cpf
-
($base, $dv) = parse_cpf($cpf);
$hashref = parse_cpf('999.222.111-00'); # { base => '999222111', dv => '00' }
Splits a candidate for CPF number into base and check digits (dv - digitos
de verificaca~o). It canon's the argument before splitting it into 9- and
2-digits parts. In a list context, returns a two-element list with the
base and the check digits. In a scalar context, returns a hash ref with
keys 'base' and 'dv' and associated values.
- random_cpf
-
$rand_cpf = random_cpf($valid);
$correct_cpf = random_cpf();
$cpf = random_cpf(1); # also a correct CPF
$bad_cpf = random_cpf(0); # an incorrect CPF
Generates a random CPF. If $valid is omitted or 1, it is guaranteed to be
correct. If $valid is 0, it is guaranteed to be incorrect.
This function is intented for mass test. (Use it wisely.)
The implementation is simple: just generate a 9-digits random number,
hopefully with a uniform distribution and then compute the check digits.
If $valid==0, the check digits are computed not to satisfy the
check equations.
EXPORT¶
"test_cpf" is exported by default. "canon_cpf",
"format_cpf", "parse_cpf" and "random_cpf" can
be exported on demand.
THE CHECK EQUATIONS¶
A correct CPF number has two check digits which are computed from the base 9
first digits. Consider the CPF number written as 11 digits
c[1] c[2] c[3] c[4] c[5] c[6] c[7] c[8] c[9] dv[1] dv[2]
To check whether a CPF is correct or not, it has to satisfy the check equations:
c[1]*10+c[2]*9+c[3]*8+c[4]*7+c[5]*6+
c[6]*5+c[7]*4+c[8]*3+c[9]*2+dv[1] = 0 (mod 11) or
= 1 (mod 11) (if dv[1]=0)
and
c[2]*10+c[3]*9+c[4]*8+c[5]*7+c[6]*6+
c[7]*5+c[8]*4+c[9]*3+dv[1]*2+dv[2] = 0 (mod 11) or
= 1 (mod 11) (if dv[2]=0)
BUGS¶
I heard that there are exceptions of CPF numbers which don't obey the check
equations and are still authentic. I have never found one of them.
SEE ALSO¶
To make sure this module works, one can try the results obtained against those
found with "Comprovante de Inscrica~o e de Situaca~o Cadastral no
CPF", a web page which the Brazilian Ministry of Revenue provides for
public consultation on regularity status of the taxpayer. This page tells if
the CPF number is a correct entry (11-digits-long with verified check digits),
if it references a real person and if he/she is regular with the government
body.
Given a bad CPF, the after-submit page tells "CPF incorreto". If the
CPF is a good one but does not reference a real person, it says "CPF na~o
existe em nossa base de dados" (CPF does not exist in our database).
Otherwise, it shows a details form for the identified taxpayer.
Note that this module only tests correctness. It doesn't enter the merit whether
the CPF number actually exists at the Brazilian government databases.
As you might have guessed, this is not the first Perl module to approach this
kind of functionality. Take a look at
http://search.cpan.org/search?module=Brasil::Checar::CPF
http://search.cpan.org/search?query=cpf&mode=all
Please reports bugs via CPAN RT,
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Business-BR-Ids By doing so, the
author will receive your reports and patches, as well as the problem and
solutions will be documented.
AUTHOR¶
A. R. Ferreira, <ferreira@cpan.org>
COPYRIGHT AND LICENSE¶
Copyright (C) 2005 by A. R. Ferreira
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself, either Perl version 5.8.6 or, at your option,
any later version of Perl 5 you may have available.
