Como consumir APIs REST de CPF em Ruby usando Net::HTTP e Faraday

Para consumir a API de CPF em Ruby, use Net::HTTP quando quiser evitar dependências externas, ou Faraday para produção com retry automático e middleware configurável. Ambas as abordagens funcionam com a API da CPFHub.io via uma requisição GET para https://api.cpfhub.io/cpf/{CPF} autenticada pelo header x-api-key. A latência média da API é de ~900ms — configure read_timeout de pelo menos 10 segundos para cobrir picos eventuais. A API não bloqueia quando o limite mensal é atingido: consultas excedentes são cobradas a R$0,15 cada.

Usando Net::HTTP (nativo)

Sem necessidade de instalar gems adicionais.

require 'net/http'
require 'json'
require 'uri'

def consultar_cpf(cpf)
    uri = URI("https://api.cpfhub.io/cpf/#{cpf}")

    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.open_timeout = 5
    http.read_timeout = 10

    request = Net::HTTP::Get.new(uri)
    request['x-api-key'] = ENV['CPFHUB_API_KEY']
    request['Accept'] = 'application/json'

    response = http.request(request)

    case response.code.to_i
    when 200
    JSON.parse(response.body)
    when 401
    { 'error' => 'Chave de API invalida', 'code' => 401 }
    when 404
    { 'error' => 'CPF nao encontrado', 'code' => 404 }
    else
    { 'error' => "HTTP #{response.code}", 'code' => response.code.to_i }
    end
rescue Net::OpenTimeout, Net::ReadTimeout
    { 'error' => 'Timeout na requisicao', 'code' => 0 }
rescue StandardError => e
    { 'error' => e.message, 'code' => 0 }
end

# Uso
resultado = consultar_cpf('12345678900')

if resultado['success']
    puts "Nome: #{resultado['data']['name']}"
    puts "Nascimento: #{resultado['data']['birthDate']}"
else
    puts "Erro: #{resultado['error']}"
end

Usando Faraday

Instalação

gem install faraday
# ou no Gemfile:
# gem 'faraday'

Consulta com Faraday

require 'faraday'
require 'json'

conn = Faraday.new(url: 'https://api.cpfhub.io') do |f|
    f.request :retry, max: 3, interval: 1, backoff_factor: 2,
    retry_statuses: [500, 502, 503]
    f.response :raise_error
    f.adapter Faraday.default_adapter
end

def consultar_cpf_faraday(conn, cpf)
    response = conn.get("/cpf/#{cpf}") do |req|
    req.headers['x-api-key'] = ENV['CPFHUB_API_KEY']
    req.headers['Accept'] = 'application/json'
    req.options.timeout = 10
    req.options.open_timeout = 5
    end

    JSON.parse(response.body)
rescue Faraday::ClientError => e
    { 'error' => "Erro HTTP: #{e.message}", 'code' => e.response&.dig(:status) }
rescue Faraday::TimeoutError
    { 'error' => 'Timeout', 'code' => 0 }
rescue Faraday::ConnectionFailed
    { 'error' => 'Erro de conexao', 'code' => 0 }
end

Comparativo: Net::HTTP vs. Faraday

Integração com Rails

# app/services/cpf_service.rb
class CpfService
    def initialize
    @conn = Faraday.new(url: 'https://api.cpfhub.io') do |f|
    f.request :retry, max: 3, retry_statuses: [500, 503]
    f.adapter Faraday.default_adapter
    end
    end

    def validar(cpf)
    response = @conn.get("/cpf/#{cpf}") do |req|
    req.headers['x-api-key'] = ENV['CPFHUB_API_KEY']
    req.headers['Accept'] = 'application/json'
    req.options.timeout = 10
    end

    dados = JSON.parse(response.body)
    return nil unless dados['success']

    dados['data']
    rescue StandardError
    nil
    end
end

# Uso no controller
class UsersController < ApplicationController
    def create
    cpf_data = CpfService.new.validar(params[:cpf])

    if cpf_data.nil?
    render json: { error: 'CPF invalido' }, status: :unprocessable_entity
    else
    @user = User.create!(
    cpf_hash: Digest::SHA256.hexdigest(params[:cpf]),
    nome: cpf_data['name']
    )
    render json: @user, status: :created
    end
    end
end

Boas práticas

• Variáveis de ambiente -- Use ENV['CPFHUB_API_KEY'].

• SSL -- Sempre use_ssl = true com Net::HTTP.

• Timeout -- Configure open_timeout e read_timeout.

• Service Object -- Encapsule a lógica de consulta em um service.

• Hash do CPF -- Armazene hash, nunca o CPF em texto plano.

Perguntas frequentes

Net::HTTP ou Faraday: qual escolher para integrar a API de CPF em Ruby?

Net::HTTP é suficiente para scripts simples e protótipos — não exige nenhuma gem adicional. Para aplicações Rails em produção, Faraday é a escolha mais sólida: o middleware de retry lida automaticamente com erros temporários de rede, e o adaptador de teste facilita a criação de stubs nos specs sem fazer chamadas reais à API.

Como configurar timeout corretamente ao consultar a API de CPF em Ruby?

Com Net::HTTP, defina http.open_timeout = 5 (tempo para abrir a conexão) e http.read_timeout = 10 (tempo para receber a resposta). Com Faraday, use req.options.open_timeout e req.options.timeout dentro do bloco de requisição. A API da CPFHub.io opera com latência média de ~900ms; um read timeout de 10 segundos cobre folga suficiente para picos eventuais.

Como armazenar dados de CPF de forma segura em conformidade com a LGPD?

Nunca persista o número do CPF em texto plano no banco de dados. Armazene apenas o hash SHA-256 do documento para fins de identificação interna. Segundo a Autoridade Nacional de Proteção de Dados (ANPD), dados de identificação devem ser tratados com o princípio da necessidade — colete e guarde somente o que for estritamente necessário para a finalidade declarada.

A API CPFHub.io bloqueia requisições quando o limite mensal é atingido?

Não. A CPFHub.io não bloqueia nem retorna erro 429. Ao atingir o limite do plano, cada consulta excedente é cobrada automaticamente a R$0,15. O plano gratuito inclui 50 consultas/mês sem cartão de crédito; o plano Pro oferece 1.000 consultas por R$149/mês. Isso significa que sua integração em Ruby não precisa implementar lógica de pausa para rate limit — apenas trate erros de rede (timeout, 500, 503) com retry e backoff.

Conclusão

Ruby oferece opções sólidas para consumir APIs de CPF. Net::HTTP é ideal quando você não quer dependências extras; Faraday é a melhor escolha para produção com seu middleware de retry e interface modular. Em ambos os casos, a integração com a CPFHub.io leva menos de 30 minutos: uma chamada GET autenticada pelo header x-api-key já retorna nome, data de nascimento e gênero do titular — dados suficientes para validação em tempo real no cadastro ou checkout.

Crie sua conta gratuitamente em cpfhub.io e comece com 50 consultas sem cartão de crédito. Se o volume crescer, o plano Pro (R$149/mês) e o modelo de excedente por R$0,15/consulta garantem que sua aplicação nunca seja interrompida por limite de uso.