# Como consumir API de CPF em R para análise estatística e data science

> Aprenda a consumir a API de consulta de CPF em R usando httr e jsonlite. Guia prático para análise estatística e data science com exemplos de código.

**Publicado:** 25/07/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-r-para-analise-estatistica-e-data-science

---


Para consumir a API de CPF em R, instale os pacotes `httr` e `jsonlite`, depois faça uma requisição GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A resposta JSON retorna nome, gênero e data de nascimento do titular, que podem ser convertidos diretamente em dataframes para análise estatística e enriquecimento de datasets.

## Introdução

A linguagem R é amplamente utilizada por cientistas de dados, estatísticos e analistas para processamento e análise de dados. Em projetos que envolvem dados de pessoas físicas no Brasil, é comum a necessidade de validar CPFs para garantir a qualidade e a confiabilidade das bases de dados utilizadas em análises.

Integrar uma API de consulta de CPF diretamente em scripts R permite automatizar a validação de cadastros, enriquecer datasets com informações cadastrais e garantir que os dados utilizados em modelos estatísticos sejam precisos.

---

## Pré-requisitos

Antes de começar, certifique-se de ter:

* **R instalado** -- Versão 4.0 ou superior recomendada.

* **RStudio** (opcional) -- Ambiente de desenvolvimento integrado para R.

* **Conta na CPFHub.io** -- Para obter a chave de API. O plano gratuito oferece 50 consultas/mês sem necessidade de cartão de crédito.

* **Pacotes httr e jsonlite** -- Para realizar requisições HTTP e processar JSON.

Instale os pacotes necessários caso ainda não os tenha:

```r
install.packages("httr")
install.packages("jsonlite")
```

---

## Consultando a API de CPF em R com httr

O pacote httr é a forma mais direta de fazer requisições HTTP em R. Abaixo está um exemplo completo de como consultar um CPF na API da CPFHub.io.

```r
library(httr)
library(jsonlite)

api_key <- "SUA_CHAVE_DE_API"
cpf <- "12345678900"
url <- paste0("https://api.cpfhub.io/cpf/", cpf)

response <- GET(
 url,
 add_headers(
 "x-api-key" = api_key,
 "Accept" = "application/json"
 ),
 timeout(10)
)

if (status_code(response) == 200) {
 dados <- fromJSON(content(response, as = "text", encoding = "UTF-8"))
 if (dados$success) {
 cat("Nome:", dados$data$name, "\n")
 cat("Data de nascimento:", dados$data$birthDate, "\n")
 cat("Gênero:", dados$data$gender, "\n")
 } else {
 cat("CPF não encontrado.\n")
 }
} else {
 cat("Erro na consulta:", status_code(response), "\n")
}
```

### Resposta esperada

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

---

## Criando uma função reutilizável

Para facilitar o uso em projetos maiores, encapsule a lógica em uma função reutilizável:

```r
library(httr)
library(jsonlite)

consultar_cpf <- function(cpf, api_key) {
 url <- paste0("https://api.cpfhub.io/cpf/", cpf)

 response <- tryCatch(
 GET(
 url,
 add_headers(
 "x-api-key" = api_key,
 "Accept" = "application/json"
 ),
 timeout(10)
 ),
 error = function(e) {
 message("Erro na requisição: ", e$message)
 return(NULL)
 }
 )

 if (is.null(response)) return(NULL)

 if (status_code(response) == 200) {
 dados <- fromJSON(content(response, as = "text", encoding = "UTF-8"))
 if (dados$success) {
 return(dados$data)
 }
 } else if (status_code(response) == 429) {
 message("Rate limit atingido. Aguarde antes de tentar novamente.")
 } else {
 message("Erro HTTP: ", status_code(response))
 }

 return(NULL)
}

# Uso
resultado <- consultar_cpf("12345678900", "SUA_CHAVE_DE_API")
if (!is.null(resultado)) {
 print(resultado)
}
```

---

## Validando uma lista de CPFs em lote

Em cenários de data science, é comum ter uma base de dados com centenas ou milhares de registros que precisam de validação. Abaixo está um exemplo de como validar uma lista de CPFs e criar um dataframe com os resultados.

```r
library(httr)
library(jsonlite)

api_key <- "SUA_CHAVE_DE_API"

cpfs <- c("12345678900", "98765432100", "11122233344")

validar_lote <- function(cpfs, api_key, intervalo = 2) {
 resultados <- data.frame(
 cpf = character(),
 nome = character(),
 genero = character(),
 data_nascimento = character(),
 valido = logical(),
 stringsAsFactors = FALSE
 )

 for (cpf in cpfs) {
 resultado <- consultar_cpf(cpf, api_key)

 if (!is.null(resultado)) {
 nova_linha <- data.frame(
 cpf = resultado$cpf,
 nome = resultado$name,
 genero = resultado$gender,
 data_nascimento = resultado$birthDate,
 valido = TRUE,
 stringsAsFactors = FALSE
 )
 } else {
 nova_linha <- data.frame(
 cpf = cpf,
 nome = NA,
 genero = NA,
 data_nascimento = NA,
 valido = FALSE,
 stringsAsFactors = FALSE
 )
 }

 resultados <- rbind(resultados, nova_linha)
 Sys.sleep(intervalo) # Respeitar rate limit
 }

 return(resultados)
}

df_resultados <- validar_lote(cpfs, api_key)
print(df_resultados)
```

O parâmetro `intervalo` garante que o rate limit da API seja respeitado. No plano gratuito, o limite é de 1 requisição a cada 2 segundos. No plano Pro, esse intervalo pode ser reduzido para 1 segundo.

---

## Análise estatística dos dados retornados

Com os dados validados em um dataframe, é possível realizar análises estatísticas diretamente em R.

### Distribuição por gênero

```r
tabela_genero <- table(df_resultados$genero)
barplot(tabela_genero, main = "Distribuição por Gênero", col = c("steelblue", "salmon"))
```

### Distribuição etária

```r
library(lubridate)

df_resultados$data_nasc_parsed <- dmy(df_resultados$data_nascimento)
df_resultados$idade <- as.numeric(difftime(Sys.Date(), df_resultados$data_nasc_parsed, units = "days")) / 365.25

hist(df_resultados$idade, main = "Distribuição Etária", xlab = "Idade", col = "steelblue")
```

Essas análises são úteis para entender o perfil demográfico de uma base de clientes, segmentar campanhas de marketing ou identificar padrões em datasets de pesquisa.

---

## Boas práticas para uso em projetos de data science

### Armazenamento seguro da chave de API

Nunca inclua a chave de API diretamente no código que será versionado. Utilize variáveis de ambiente:

```r
api_key <- Sys.getenv("CPFHUB_API_KEY")
```

Configure a variável no arquivo `.Renviron`:

```
CPFHUB_API_KEY=sua_chave_aqui
```

### Cache de resultados

Se o mesmo CPF precisar ser consultado múltiplas vezes durante uma análise, armazene os resultados em um arquivo local (CSV ou RDS) para evitar consultas desnecessárias:

```r
saveRDS(df_resultados, "resultados_cpf.rds")
df_cache <- readRDS("resultados_cpf.rds")
```

### Tratamento de rate limit

Implemente lógica de retry com backoff exponencial para lidar com respostas 429 (Too Many Requests) em processos de larga escala.

---

## Planos e limites

| Plano | Consultas/mês | Rate limit | Preço |
| --- | --- | --- | --- |
| Gratuito | 50 | 1 req/2s | R$ 0 |
| Pro | 1.000 | 1 req/s | R$ 149/mês |
| Corporativo | Sob consulta | Personalizado | Sob consulta |

Para projetos de data science com volumes maiores, o plano Pro ou Corporativo oferece a escalabilidade necessária sem comprometer o fluxo de trabalho.

---

## Perguntas frequentes

### Quais pacotes R são necessários para consumir a API de CPF?
Os pacotes essenciais são `httr` (para requisições HTTP) e `jsonlite` (para parsear a resposta JSON). Para análises estatísticas com os dados retornados — como distribuição etária — o pacote `lubridate` facilita a conversão de datas no formato DD/MM/YYYY retornado pela API.

### Como lidar com rate limit ao validar lotes de CPFs em R?
Use a função `Sys.sleep(2)` entre requisições para respeitar o limite de 1 req/2s do plano gratuito. Em projetos maiores com plano Pro (1 req/s), ajuste o intervalo para 1 segundo. Para erros 429 inesperados, implemente retry com backoff exponencial dentro da função de consulta.

### É seguro armazenar a chave de API da CPFHub.io em scripts R?
Nunca inclua a chave diretamente no código versionado. A prática recomendada é usar `Sys.getenv("CPFHUB_API_KEY")` em conjunto com o arquivo `.Renviron`, que é ignorado pelo Git por padrão. Essa abordagem segue as diretrizes de segurança do [OWASP](https://owasp.org/www-project-top-ten/) para proteção de credenciais em aplicações.

### O R consegue processar uma base grande de CPFs com a API da CPFHub.io?
Sim, com a função de validação em lote demonstrada neste artigo. Para bases com milhares de registros, considere o plano Pro (1.000 consultas/mês) ou o Corporativo para volumes maiores. Combine cache local com `saveRDS()` para evitar consultas repetidas ao mesmo CPF e otimizar o uso das cotas disponíveis.

### 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

Consumir a API de consulta de CPF da [**CPFHub.io**](https://www.cpfhub.io/) em R é direto: com os pacotes `httr` e `jsonlite`, você tem acesso a dados cadastrais reais que podem enriquecer datasets, validar registros e alimentar análises estatísticas com qualidade de dados garantida.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a integrar validação de CPF nos seus projetos de data science em R hoje mesmo.