Como consumir API de CPF em Delphi e Free Pascal

Para consumir a API de CPF do CPFHub.io em Delphi, use o componente THTTPClient (Delphi XE8+) ou TIdHTTP via Indy para versões mais antigas. Em Free Pascal, o módulo fphttpclient resolve a integração com poucas linhas de código. Em todos os casos, basta enviar uma requisição GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key e processar o JSON de resposta.

Introdução

Delphi e Free Pascal continuam sendo linguagens amplamente utilizadas no mercado brasileiro, especialmente em sistemas de gestão empresarial (ERP), automação comercial e aplicações desktop legadas. Muitas dessas aplicações precisam validar CPF de clientes, fornecedores ou funcionários, mas a integração com APIs REST modernas pode parecer desafiadora nesses ambientes.

Pré-requisitos

Antes de começar a codificar, você precisa:

• Conta no CPFHub.io -- Crie uma conta gratuita em cpfhub.io e acesse o painel para gerar sua chave de API.

• Chave de API -- Após o cadastro, gere sua x-api-key no painel de controle (app.cpfhub.io).

• Delphi -- Versão XE ou superior (recomendado Delphi 10.x ou 11.x para THTTPClient nativo).

• Free Pascal -- Versão 3.0 ou superior com Lazarus IDE.

O plano gratuito oferece 50 consultas por mês, ideal para desenvolvimento e testes.

Entendendo a API do CPFHub.io

A API utiliza o método GET, com o CPF enviado diretamente na URL. A autenticação é feita via header x-api-key. Veja o exemplo com cURL:

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json"

A resposta JSON tem a seguinte estrutura:

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

Integração em Delphi com THTTPClient

O THTTPClient, disponível a partir do Delphi XE8, é a forma mais moderna e recomendada para fazer requisições HTTP em Delphi. Ele faz parte da unit System.Net.HttpClient.

Código completo com THTTPClient

uses
    System.SysUtils, System.JSON,
    System.Net.HttpClient, System.Net.HttpClientComponent;

procedure ConsultarCPF(const ACPF: string);
var
    HttpClient: THTTPClient;
    Response: IHTTPResponse;
    JsonObj, DataObj: TJSONObject;
    URL: string;
begin
    URL := Format('https://api.cpfhub.io/cpf/%s', [ACPF]);
    HttpClient := THTTPClient.Create;
    try
    HttpClient.CustomHeaders['x-api-key'] := 'SUA_CHAVE_DE_API';
    HttpClient.Accept := 'application/json';
    HttpClient.ConnectionTimeout := 10000;
    HttpClient.ResponseTimeout := 10000;

    Response := HttpClient.Get(URL);

    if Response.StatusCode = 200 then
    begin
    JsonObj := TJSONObject.ParseJSONValue(Response.ContentAsString) as TJSONObject;
    try
    if JsonObj.GetValue<Boolean>('success') then
    begin
    DataObj := JsonObj.GetValue<TJSONObject>('data');
    WriteLn('CPF: ', DataObj.GetValue<string>('cpf'));
    WriteLn('Nome: ', DataObj.GetValue<string>('name'));
    WriteLn('Gênero: ', DataObj.GetValue<string>('gender'));
    WriteLn('Nascimento: ', DataObj.GetValue<string>('birthDate'));
    end
    else
    WriteLn('CPF não encontrado.');
    finally
    JsonObj.Free;
    end;
    end
    else if Response.StatusCode = 429 then
    WriteLn('Rate limit excedido. Aguarde antes de tentar novamente.')
    else if Response.StatusCode = 401 then
    WriteLn('Chave de API inválida ou ausente.')
    else
    WriteLn('Erro: ', Response.StatusCode, ' - ', Response.StatusText);
    finally
    HttpClient.Free;
    end;
end;

Chamando a função

begin
    ConsultarCPF('12345678900');
end.

Integração em Delphi com Indy (TIdHTTP)

Para versões mais antigas do Delphi que não possuem THTTPClient, o Indy é a alternativa mais comum. O componente TIdHTTP está disponível em praticamente todas as versões do Delphi.

Código completo com Indy

uses
    SysUtils, Classes, IdHTTP, IdSSLOpenSSL, SuperObject;

procedure ConsultarCPFIndy(const ACPF: string);
var
    IdHTTP: TIdHTTP;
    SSLHandler: TIdSSLIOHandlerSocketOpenSSL;
    ResponseStr: string;
    JsonObj, DataObj: ISuperObject;
    URL: string;
begin
    URL := Format('https://api.cpfhub.io/cpf/%s', [ACPF]);
    IdHTTP := TIdHTTP.Create(nil);
    SSLHandler := TIdSSLIOHandlerSocketOpenSSL.Create(nil);
    try
    SSLHandler.SSLOptions.Method := sslvTLSv1_2;
    IdHTTP.IOHandler := SSLHandler;
    IdHTTP.ConnectTimeout := 10000;
    IdHTTP.ReadTimeout := 10000;

    IdHTTP.Request.CustomHeaders.AddValue('x-api-key', 'SUA_CHAVE_DE_API');
    IdHTTP.Request.Accept := 'application/json';

    try
    ResponseStr := IdHTTP.Get(URL);
    JsonObj := SO(ResponseStr);

    if JsonObj.B['success'] then
    begin
    DataObj := JsonObj.O['data'];
    WriteLn('CPF: ', DataObj.S['cpf']);
    WriteLn('Nome: ', DataObj.S['name']);
    WriteLn('Gênero: ', DataObj.S['gender']);
    WriteLn('Nascimento: ', DataObj.S['birthDate']);
    end
    else
    WriteLn('CPF não encontrado.');
    except
    on E: EIdHTTPProtocolException do
    begin
    if E.ErrorCode = 429 then
    WriteLn('Rate limit excedido.')
    else if E.ErrorCode = 401 then
    WriteLn('Chave de API inválida.')
    else
    WriteLn('Erro HTTP: ', E.ErrorCode, ' - ', E.Message);
    end;
    end;
    finally
    SSLHandler.Free;
    IdHTTP.Free;
    end;
end;

Integração em Free Pascal com fphttpclient

O Free Pascal possui o módulo fphttpclient na unit fphttpclient, que permite fazer requisições HTTP de forma simples. Para parsear JSON, utilizamos a unit fpjson e jsonparser.

Código completo em Free Pascal

program ConsultaCPF;

{$mode objfpc}{$H+}

uses
    SysUtils, fphttpclient, opensslsockets, fpjson, jsonparser;

var
    HTTPClient: TFPHTTPClient;
    Response: string;
    JsonData: TJSONData;
    JsonObj, DataObj: TJSONObject;
    CPF, URL: string;
begin
    CPF := '12345678900';
    URL := Format('https://api.cpfhub.io/cpf/%s', [CPF]);

    HTTPClient := TFPHTTPClient.Create(nil);
    try
    HTTPClient.ConnectTimeout := 10000;
    HTTPClient.IOTimeout := 10000;
    HTTPClient.AddHeader('x-api-key', 'SUA_CHAVE_DE_API');
    HTTPClient.AddHeader('Accept', 'application/json');

    try
    Response := HTTPClient.Get(URL);
    JsonData := GetJSON(Response);
    try
    JsonObj := JsonData as TJSONObject;

    if JsonObj.Booleans['success'] then
    begin
    DataObj := JsonObj.Objects['data'];
    WriteLn('CPF: ', DataObj.Strings['cpf']);
    WriteLn('Nome: ', DataObj.Strings['name']);
    WriteLn('Gênero: ', DataObj.Strings['gender']);
    WriteLn('Nascimento: ', DataObj.Strings['birthDate']);
    end
    else
    WriteLn('CPF não encontrado.');
    finally
    JsonData.Free;
    end;
    except
    on E: EHTTPClient do
    WriteLn('Erro HTTP: ', E.Message);
    on E: Exception do
    WriteLn('Erro: ', E.Message);
    end;
    finally
    HTTPClient.Free;
    end;
end.

Boas práticas para Delphi e Free Pascal

Tratamento de timeout

Sempre configure ConnectionTimeout e ReadTimeout (ou IOTimeout no Free Pascal). A API do CPFHub.io responde em aproximadamente 900ms, então um timeout de 10 segundos é adequado para lidar com eventuais variações de rede.

Validação local do CPF antes da requisição

Antes de enviar a requisição à API, valide o formato do CPF localmente. Isso evita consultas desnecessárias e preserva sua cota mensal.

function ValidarFormatoCPF(const ACPF: string): Boolean;
var
    I: Integer;
    CPFLimpo: string;
begin
    CPFLimpo := '';
    for I := 1 to Length(ACPF) do
    if CharInSet(ACPF[I], ['0'..'9']) then
    CPFLimpo := CPFLimpo + ACPF[I];

    Result := Length(CPFLimpo) = 11;
end;

Cache de resultados

Se a sua aplicação consulta o mesmo CPF múltiplas vezes (por exemplo, em processos de vendas recorrentes), implemente um cache local com tempo de expiração. Isso reduz o consumo da sua cota e melhora a performance.

Gerenciamento da chave de API

Nunca inclua a chave de API diretamente no código-fonte em produção. Utilize arquivos de configuração (.ini ou .json) ou variáveis de ambiente. Em Delphi, o TIniFile ou TJSONObject podem ser usados para carregar a chave de um arquivo externo.

Tratamento de erros HTTP

A API retorna códigos HTTP padrão que devem ser tratados na sua aplicação:

Para o plano gratuito, o rate limit é de 1 requisição a cada 2 segundos. Se você precisar de mais velocidade, o plano Pro permite 1 requisição por segundo com 1.000 consultas mensais.

Perguntas frequentes

O THTTPClient do Delphi suporta HTTPS para chamar a API do CPFHub.io?

Sim. O THTTPClient, disponível a partir do Delphi XE8, usa WinHTTP internamente no Windows, que suporta HTTPS nativamente sem dependências externas. Para versões mais antigas com Indy, é necessário configurar o TIdSSLIOHandlerSocketOpenSSL e garantir que as DLLs do OpenSSL estejam presentes na pasta da aplicação.

Como proteger a chave de API em aplicações Delphi distribuídas?

Nunca compile a chave diretamente no executável. Use um arquivo .ini ou .json externo, carregado via TIniFile ou TJSONObject, e instrua os clientes a manter esse arquivo fora da pasta pública de instalação. Para maior segurança, considere criptografar o arquivo de configuração com DPAPI (Windows) ou uma chave derivada de hardware.

O Free Pascal consegue consumir a API sem o Lazarus IDE?

Sim. O módulo fphttpclient faz parte da RTL padrão do Free Pascal e funciona em modo console sem necessidade do Lazarus. Basta compilar com fpc e garantir que o pacote opensslsockets esteja disponível para habilitar suporte a HTTPS — disponível na instalação padrão do FPC 3.0+.

Como garantir conformidade com a LGPD ao consultar CPF em aplicações desktop?

Armazene a chave de API e os resultados das consultas com controle de acesso restrito — apenas o processo ou usuário que precisar dos dados deve acessá-los. Consulte apenas os campos necessários para a operação e não persista dados de CPF além do tempo exigido pela transação. A ANPD orienta que o princípio da necessidade deve guiar qualquer tratamento de dados pessoais, inclusive em aplicações desktop legadas.

Conclusão

Integrar a API de consulta de CPF do CPFHub.io em aplicações Delphi e Free Pascal é um processo direto, independentemente da versão ou framework HTTP utilizado. Com THTTPClient, Indy ou fphttpclient, bastam algumas linhas de código para automatizar a validação de CPF em sistemas de gestão, ERP, PDV ou qualquer aplicação desktop. O plano gratuito com 50 consultas por mês é perfeito para desenvolvimento e testes, e a migração para o plano Pro é transparente quando a demanda crescer.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF ao seu sistema Delphi ou Free Pascal hoje mesmo.