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

> Aprenda a consumir APIs REST de CPF em Ruby usando Net::HTTP e Faraday. Exemplos práticos, tratamento de erros e integração com Rails.

**Publicado:** 18/05/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-apis-rest-de-cpf-em-ruby-com-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.

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

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

### Consulta com Faraday

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

| Recurso | Net::HTTP | Faraday |
| --- | --- | --- |
| Instalação | Nenhuma (stdlib) | `gem install faraday` |
| Middleware | Não | Sim |
| Retry automático | Manual | Middleware integrado |
| Teste com stubs | Complexo | Faraday::Test adapter |
| Configuração | Verbose | Fluente |

---

## Integração com Rails

```ruby
# 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)](https://www.gov.br/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.

### 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)
- [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura)
- [Como consumir API de CPF em Ruby on Rails com Faraday](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-ruby-on-rails-com-faraday)
- [Autenticação em APIs REST: como garantir segurança na consulta de CPF](https://cpfhub.io/blog/autenticacao-apis-rest-seguranca-consulta-cpf)

---

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