# 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 "Ministério da Fazenda".

CPF stands for "Cadastro de Pessoa Física" (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 - dígitos de verificaçã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 Inscrição e de Situaçã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 nã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.

1 POD Error

The following errors were encountered while parsing the POD:

- Around line 112:
Non-ASCII character seen before =encoding in '"Ministério'. Assuming ISO8859-1