# Como consumir API de CPF em Delphi e Free Pascal

> Aprenda a integrar a API de consulta de CPF do CPFHub.io em aplicações Delphi e Free Pascal com exemplos de código completos e boas práticas.

**Publicado:** 23/06/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/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](https://www.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:

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

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

```pascal
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

```pascal
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

```pascal
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

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

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

| Código | Significado | Ação recomendada |
| --- | --- | --- |
| 200 | Requisição bem-sucedida | Processar o JSON normalmente |
| 400 | CPF com formato inválido | Validar CPF antes de enviar |
| 401 | Chave de API inválida ou ausente | Verificar configuração da x-api-key |
| 404 | CPF não encontrado | Informar ao usuário |
| 429 | Rate limit excedido | Aguardar e tentar novamente |
| 500 | Erro interno do servidor | Tentar novamente após alguns segundos |

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](https://www.gov.br/anpd) orienta que o princípio da necessidade deve guiar qualquer tratamento de dados pessoais, inclusive em aplicações desktop legadas.

### 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)
- [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf)

---

## 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](https://www.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.