Como consumir API de CPF em R para análise estatística 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:

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.

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

{
    "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:

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.

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

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

Distribuição etária

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:

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:

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

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

Conclusão

Consumir a API de consulta de CPF da 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 — 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.