Provided by: libbusiness-br-ids-perl_0.0022-1_all 
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.