# Como consumir API de CPF em Perl para sistemas legados

> Aprenda a consumir uma API de consulta de CPF em Perl usando LWP::UserAgent e HTTP::Tiny. Guia prático para modernizar sistemas legados.

**Publicado:** 20/06/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/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](https://www.cpfhub.io/) para obter sua API key gratuita.

### Instalando módulos necessários

```bash
cpanm LWP::UserAgent LWP::Protocol::https JSON
```

Ou via CPAN:

```bash
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.

```perl
#!/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:

```perl
#!/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:

```perl
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:

```perl
#!/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:

```json
{
 "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

```perl
#!/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

| Código | Significado | Ação recomendada |
| --- | --- | --- |
| 200 | Consulta bem-sucedida | Processar dados normalmente |
| 400 | CPF com formato inválido | Validar antes de enviar |
| 401 | Chave de API inválida | Verificar no painel |
| 429 | Rate limit excedido | Aguardar intervalo e tentar novamente |
| 500 | Erro interno do servidor | Retry com backoff exponencial |

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](https://owasp.org) 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.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma)

---

## 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.