CPFHub.io
Começar grátis

Consultar CPF com Ruby on Rails

Consulte CPF com Ruby on Rails usando um service object com Net::HTTP, chamado a partir de um controller. A API Key fica nas credentials do Rails.

Usando Cursor, Lovable, v0 ou outra IA? Copie o prompt da Consulta Simples e cole no seu assistente.

Abrir no Cursor

Antes de começar

  1. Crie uma conta grátis em app.cpfhub.io: o plano Grátis tem 50 créditos e não pede cartão.
  2. Copie sua API Key em app.cpfhub.io/api-keys.
  3. Guarde a chave em uma variável de ambiente, nunca no código:
bash
export CPFHUB_API_KEY="sua_api_key"

Exemplo

Guarde a chave nas credentials (bin/rails credentials:edit) como cpfhub_api_key, ou na variável de ambiente CPFHUB_API_KEY.

Ruby
# app/services/cpfhub_client.rb
require 'net/http'

class CpfhubClient
  class Error < StandardError; end

  # Retorna o hash "data" ou nil quando o CPF não está na base (404).
  def self.lookup(cpf)
    uri = URI("https://api.cpfhub.io/cpf/#{cpf}")
    req = Net::HTTP::Get.new(uri)
    req['x-api-key'] = Rails.application.credentials.cpfhub_api_key || ENV.fetch('CPFHUB_API_KEY')

    res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 5, read_timeout: 10) do |http|
      http.request(req)
    end
    body = JSON.parse(res.body)

    case res.code.to_i
    when 200 then body['data']
    when 404 then nil
    else
      # error vem como texto ("...") ou como objeto ({ "message" => "..." })
      erro = body['error']
      raise Error, "#{res.code}: #{erro.is_a?(Hash) ? erro['message'] : erro}"
    end
  end
end
Ruby
# app/controllers/cpfs_controller.rb
class CpfsController < ApplicationController
  def show
    cpf = params[:id].to_s.gsub(/\D/, '')
    return render(json: { error: 'CPF deve ter 11 dígitos' }, status: :bad_request) unless cpf.length == 11

    dados = CpfhubClient.lookup(cpf)
    if dados
      render json: dados
    else
      render json: { error: 'CPF não encontrado' }, status: :not_found
    end
  rescue CpfhubClient::Error => e
    # 401, 403, 422, 429 e 5xx: registre e não exponha detalhes ao cliente
    Rails.logger.error("CPFHub.io #{e.message}")
    render json: { error: 'Consulta de CPF indisponível no momento' }, status: :service_unavailable
  end
end

Adicione a rota resources :cpfs, only: :show no config/routes.rb e teste com curl http://localhost:3000/cpfs/12345678909.

Resposta

CPF encontrado (200, consome 1 crédito):

JSON
{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "Fulano de Tal",
    "nameUpper": "FULANO DE TAL",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}

CPF não encontrado (404, não consome crédito):

JSON
{
  "success": false,
  "data": null,
  "error": { "message": "CPF não encontrado na base de dados" }
}

O CPF 12345678909 é fictício, usado só nos exemplos. gender pode vir null.

Erros

StatusO que significaO que fazer
404CPF não está na baseTrate como "não encontrado". Não consome crédito.
400 / 422CPF sem 11 dígitos ou com dígito verificador inválidoCorrija a entrada. Não consome crédito.
401API Key ausente ou inválidaConfira a variável CPFHUB_API_KEY.
403Créditos esgotados ou conta inativaVeja o saldo em GET /quota ou recarregue no dashboard.
429Limite de requisições por minutoEspere os segundos do header Retry-After e tente de novo.
5xxFalha temporáriaTente de novo após alguns segundos.

O campo error pode vir como texto ("error": "...") ou como objeto ("error": { "message": "..." }), conforme o status. Os exemplos acima tratam os dois formatos. Lista completa em Códigos de Erro.

Próximos passos