Como consumir API de CPF em Perl para sistemas legados

Para consumir a API de CPF da CPFHub.io em Perl, você usa LWP::UserAgent ou HTTP::Tiny para fazer uma requisição GET com o header x-api-key, decodifica o JSON da resposta com o módulo JSON e extrai nome, data de nascimento e gênero do titular. A integração funciona a partir do Perl 5.14 e não exige reescrita do sistema legado.

Introdução

Muitas empresas brasileiras ainda operam com sistemas legados escritos em Perl, especialmente em setores como telecomunicações, seguradoras, governo e instituições financeiras. Esses sistemas, embora maduros e estáveis, frequentemente precisam incorporar funcionalidades modernas, como a validação de CPF via API REST.

A boa notícia é que Perl possui módulos excelentes para consumir APIs HTTP, tornando possível integrar serviços externos sem a necessidade de reescrever todo o sistema.

1. Pré-requisitos

Para seguir este guia, você precisará de:

• Perl 5.14 ou superior -- Disponível na maioria dos sistemas Unix/Linux.

• Módulos LWP::UserAgent ou HTTP::Tiny -- LWP faz parte do pacote libwww-perl; HTTP::Tiny é incluído no core do Perl a partir da versão 5.14.

• Módulo JSON -- Para decodificar a resposta da API.

• Conta na CPFHub.io -- Cadastre-se em cpfhub.io para obter sua API key gratuita.

Instalando módulos necessários

cpanm LWP::UserAgent LWP::Protocol::https JSON

Ou via CPAN:

cpan install LWP::UserAgent JSON

2. Consumindo a API com LWP::UserAgent

O LWP::UserAgent é o módulo HTTP mais tradicional e completo do Perl. Ele oferece suporte a SSL, redirecionamentos, cookies e configuração avançada de timeouts.

#!/usr/bin/perl
use strict;
use warnings;
use LWP::UserAgent;
use JSON qw(decode_json);

my $cpf = '12345678900';
my $api_key = 'SUA_CHAVE_DE_API';
my $url = "https://api.cpfhub.io/cpf/$cpf";

my $ua = LWP::UserAgent->new(
    timeout => 30,
);

my $response = $ua->get($url,
    'x-api-key' => $api_key,
    'Accept' => 'application/json',
);

if ($response->is_success) {
    my $data = decode_json($response->decoded_content);

    if ($data->{success}) {
    my $info = $data->{data};
    print "Nome: $info->{name}\n";
    print "Nome (maiusculas): $info->{nameUpper}\n";
    print "Genero: $info->{gender}\n";
    print "Nascimento: $info->{birthDate}\n";
    print "Dia: $info->{day}, Mes: $info->{month}, Ano: $info->{year}\n";
    } else {
    print "Consulta nao retornou dados.\n";
    }
} else {
    print "Erro HTTP: " . $response->status_line . "\n";
    print "Corpo: " . $response->decoded_content . "\n";
}

3. Consumindo a API com HTTP::Tiny

O HTTP::Tiny é mais leve e faz parte do core do Perl desde a versão 5.14, o que significa que não requer instalação adicional em muitos sistemas:

#!/usr/bin/perl
use strict;
use warnings;
use HTTP::Tiny;
use JSON qw(decode_json);

my $cpf = '12345678900';
my $api_key = 'SUA_CHAVE_DE_API';
my $url = "https://api.cpfhub.io/cpf/$cpf";

my $http = HTTP::Tiny->new(
    timeout => 30,
);

my $response = $http->get($url, {
    headers => {
    'x-api-key' => $api_key,
    'Accept' => 'application/json',
    },
});

if ($response->{success}) {
    my $data = decode_json($response->{content});

    if ($data->{success}) {
    my $info = $data->{data};
    print "Nome: $info->{name}\n";
    print "CPF: $info->{cpf}\n";
    print "Genero: $info->{gender}\n";
    print "Nascimento: $info->{birthDate}\n";
    } else {
    print "Consulta sem sucesso.\n";
    }
} else {
    print "Erro: $response->{status} $response->{reason}\n";
}

4. Criando um módulo reutilizável

Para sistemas maiores, encapsule a lógica em um módulo Perl reutilizável:

package CpfHub;
use strict;
use warnings;
use LWP::UserAgent;
use JSON qw(decode_json);

sub new {
    my ($class, %args) = @_;
    my $self = {
    api_key => $args{api_key} || die("api_key é obrigatória"),
    timeout => $args{timeout} || 30,
    ua => LWP::UserAgent->new(timeout => $args{timeout} || 30),
    };
    return bless $self, $class;
}

sub consultar {
    my ($self, $cpf) = @_;
    $cpf =~ s/\D//g;

    my $url = "https://api.cpfhub.io/cpf/$cpf";

    my $response = $self->{ua}->get($url,
    'x-api-key' => $self->{api_key},
    'Accept' => 'application/json',
    );

    unless ($response->is_success) {
    warn "CPFHub erro HTTP: " . $response->status_line;
    return undef;
    }

    my $data = decode_json($response->decoded_content);
    return $data->{success} ? $data->{data} : undef;
}

1;

Uso do módulo:

#!/usr/bin/perl
use strict;
use warnings;
use CpfHub;

my $cpfhub = CpfHub->new(api_key => 'SUA_CHAVE_DE_API', timeout => 30);
my $resultado = $cpfhub->consultar('12345678900');

if ($resultado) {
    print "Nome: $resultado->{name}\n";
    print "Nascimento: $resultado->{birthDate}\n";
} else {
    print "CPF nao encontrado.\n";
}

5. Exemplo de resposta da API

A API da CPFHub.io retorna um objeto JSON estruturado:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Joao da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

• success -- Indica se a consulta foi bem-sucedida.
• name / nameUpper -- Nome completo do titular em formato padrão e maiúsculas.
• gender -- Gênero do titular (M ou F).
• birthDate -- Data de nascimento no formato dd/mm/aaaa.
• day, month, year -- Componentes da data separados, úteis para cálculos e validações.

6. Integração com sistemas legados existentes

A principal vantagem de usar Perl para consumir a API é a capacidade de integrar a validação de CPF em sistemas já existentes sem grandes refatorações. Alguns cenários comuns incluem:

• Scripts de processamento em lote -- Validar CPFs em arquivos CSV ou bancos de dados antes de gerar relatórios ou notas fiscais.

• Sistemas de billing -- Confirmar dados cadastrais antes de emitir cobranças.

• Aplicações CGI -- Adicionar validação de CPF em formulários web legados.

• Jobs cron -- Agendar verificações periódicas de CPFs cadastrados.

Exemplo de processamento em lote

#!/usr/bin/perl
use strict;
use warnings;
use CpfHub;

my $cpfhub = CpfHub->new(api_key => 'SUA_CHAVE_DE_API', timeout => 30);

open(my $fh, '<', 'cpfs.csv') or die "Erro ao abrir arquivo: $!";

while (my $linha = <$fh>) {
    chomp $linha;
    my ($cpf, $nome_cadastrado) = split /;/, $linha;

    my $resultado = $cpfhub->consultar($cpf);

    if ($resultado) {
    my $nome_api = $resultado->{nameUpper};
    if (uc($nome_cadastrado) eq $nome_api) {
    print "OK: $cpf - $nome_api\n";
    } else {
    print "DIVERGENCIA: $cpf - Cadastro: $nome_cadastrado | API: $nome_api\n";
    }
    } else {
    print "NAO ENCONTRADO: $cpf\n";
    }

    sleep 2; # Respeitar rate limit do plano gratuito
}

close $fh;

7. Tratamento de erros e rate limits

O plano gratuito permite 1 requisição a cada 2 segundos (50 consultas/mês); ao atingir as 50 consultas, cada consulta adicional é cobrada a R$0,15 — o serviço não é interrompido. O plano Pro (R$149/mês) oferece 1.000 consultas/mês com rate limit de 1 requisição por segundo.

Perguntas frequentes

Qual módulo Perl devo usar para consumir a API: LWP::UserAgent ou HTTP::Tiny?

Para sistemas que precisam de SSL, cookies e controle fino de timeout, LWP::UserAgent é mais completo. Para scripts simples em servidores onde a instalação de dependências extras é difícil, HTTP::Tiny é suficiente e já vem no core do Perl desde a versão 5.14.

Como tratar o rate limit de 1 requisição a cada 2 segundos em processamento em lote?

Adicione sleep 2 entre chamadas no loop de processamento. Para volumes maiores, considere o plano Pro, que permite 1 requisição por segundo, ou paralelizar workers respeitando o limite por chave de API.

O módulo JSON precisa ser instalado separadamente no Perl?

Sim. JSON não faz parte do core do Perl. Instale via CPAN com cpanm JSON ou cpan install JSON. Em sistemas Debian/Ubuntu, também está disponível como libjson-perl via apt. A OWASP recomenda validar e sanitizar todos os dados de entrada antes de processar JSON externo.

Como integrar a validação de CPF em um sistema CGI legado em Perl?

Carregue o módulo CpfHub no script CGI, capture o CPF do formulário via CGI.pm ou variáveis de ambiente, chame $cpfhub->consultar($cpf) e exiba o resultado na página. A validação pode ser feita no POST do formulário antes de gravar no banco.

Conclusão

Consumir a API de consulta de CPF em Perl é uma solução prática para modernizar sistemas legados sem a necessidade de reescrevê-los. Tanto o LWP::UserAgent quanto o HTTP::Tiny oferecem suporte completo para requisições HTTPS, permitindo integrar a validação de CPF em scripts de processamento em lote, sistemas de billing e aplicações web legadas.

A CPFHub.io oferece 50 consultas mensais gratuitas, documentação com exemplos prontos e suporte para sistemas em produção de qualquer porte.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito.