SDK Ruby

SDK oficial para Ruby 3.0+ com interface idiomática, tratamento de erros por exceção e compatível com Rails.

Instalação

bash

gem install cpfhub

Com Bundler, adicione ao Gemfile:

Ruby

gem 'cpfhub'

Depois:

bash

bundle install

Requerimentos: Ruby 3.0+

Inicialização

Ruby

require 'cpfhub'

client = CPFHub::Client.new(
  api_key: ENV['CPFHUB_API_KEY'],
  # timeout: 10 # opcional, padrão: 10 segundos
)

Opções do construtor

Opção	Tipo	Padrão	Descrição
`api_key`	`String`	-	Sua API Key (obrigatório)
`timeout`	`Integer`	`10`	Timeout em segundos
`base_url`	`String`	`https://api.cpfhub.io`	URL base da API

Métodos

`client.lookup(cpf)`

Consulta um CPF e retorna os dados de identidade.

Ruby

result = client.lookup('12345678909')

puts result.data.name    # "João da Silva"
puts result.data.gender  # "M"

Retorno: CPFHub::Result

Ruby

# Result
result.success   # => true
result.data      # => CPFHub::Data

# Data
result.data.cpf        # => "12345678909"
result.data.name       # => "João da Silva"
result.data.name_upper # => "JOÃO DA SILVA"
result.data.gender     # => "M"
result.data.birth_date # => "15/04/1985"
result.data.day        # => 15
result.data.month      # => 4
result.data.year       # => 1985

Tratamento de erros

Ruby

require 'cpfhub'

client = CPFHub::Client.new(api_key: ENV['CPFHUB_API_KEY'])

begin
  result = client.lookup('12345678909')
rescue CPFHub::Error => e
  puts e.code        # "CPF_NOT_FOUND"
  puts e.message     # "CPF not found in our database"
  puts e.status_code # 404
end

Códigos de erro

`e.code`	`e.status_code`	Descrição
`CPF_NOT_FOUND`	`404`	CPF não encontrado (sem consumo de crédito)
`INVALID_CPF_FORMAT`	`400`	Formato inválido
`INVALID_CPF_DIGITS`	`422`	Dígitos verificadores inválidos
`MISSING_API_KEY`	`401`	API Key ausente
`INVALID_API_KEY`	`401`	API Key inválida
`RATE_LIMIT_EXCEEDED`	`429`	Limite de taxa excedido
`INSUFFICIENT_CREDITS`	`403`	Sem créditos disponíveis

Exemplos de integração

Rails - Controller

Ruby

class CpfsController < ApplicationController
  def show
    result = cpfhub_client.lookup(params[:id])
    render json: result.data
  rescue CPFHub::Error => e
    render json: { error: e.code }, status: e.status_code
  end

  private

  def cpfhub_client
    @client ||= CPFHub::Client.new(api_key: Rails.application.credentials.cpfhub_api_key)
  end
end

Inicializador Rails

Ruby

# config/initializers/cpfhub.rb
CPFHubClient = CPFHub::Client.new(
  api_key: Rails.application.credentials.dig(:cpfhub, :api_key)
)

ActiveModel validation

Ruby

class User < ApplicationRecord
  validate :cpf_valido, if: :cpf_changed?

  private

  def cpf_valido
    CPFHubClient.lookup(cpf)
  rescue CPFHub::Error => e
    errors.add(:cpf, :invalid) if e.code == 'CPF_NOT_FOUND'
  end
end

Repositório e suporte

github.com/cpfhub/cpfhub-ruby - código-fonte, issues e contribuições
RubyGems: cpfhub - versões e changelog

Atualizado em 12 de maio de 2026