Como validar CPF em tempo real em aplicações Rails usando APIs REST

Validar CPF em tempo real em aplicações Ruby on Rails é direto com a API REST da CPFHub.io: basta criar um serviço com a gem HTTParty, fazer uma requisição GET para https://api.cpfhub.io/cpf/{CPF} autenticada pelo header x-api-key, e consumir a resposta JSON com nome, gênero e data de nascimento do titular. O plano gratuito oferece 50 consultas mensais sem cartão de crédito, ideal para começar sem custo.

Introdução

A validação de CPF em tempo real é essencial para aplicações que exigem segurança e conformidade, como fintechs, bancos, marketplaces e sistemas de gestão. No Ruby on Rails, a integração com APIs REST permite validar um CPF instantaneamente, garantindo que os dados sejam precisos e atualizados.

1. Escolhendo uma API confiável

Antes de iniciar a implementação, é fundamental escolher uma API confiável que ofereça:

• Dados padronizados e atualizados diariamente.

• Baixo tempo de resposta (~900ms).

• Segurança e conformidade total com a LGPD.

• Documentação completa com exemplos em Ruby e Rails.

A CPFHub.io atende a todos esses critérios, com plano gratuito de 50 consultas mensais e plano Pro para volumes maiores — sem bloqueio de requisições ao atingir o limite.

2. Configurando a integração no Rails

2.1 Instalando a gem HTTParty

O HTTParty facilita a realização de chamadas HTTP em aplicações Rails.

bundle add httparty

Ou manualmente, edite o Gemfile e adicione:

gem 'httparty'

Depois, execute:

bundle install

2.2 Criando um serviço para consultar CPF

Crie um arquivo de serviço para centralizar as requisições à API.

# app/services/cpf_validator.rb
require 'httparty'

class CpfValidator
    include HTTParty
    base_uri 'https://api.cpfhub.io'

    def self.validate(cpf)
    sanitized_cpf = cpf.gsub(/\D/, '')
    headers = {
    'x-api-key' => ENV['CPFHUB_API_KEY'],
    'Accept' => 'application/json'
    }

    response = get("/cpf/#{sanitized_cpf}", headers: headers)

    if response.success?
    JSON.parse(response.body)
    else
    { error: 'Falha na consulta', status: response.code, message: response.body }
    end
    end
end

O que esse código faz?

• Realiza uma requisição HTTP GET para validar o CPF.

• Envia a chave de API no cabeçalho para autenticação.

• Sanitiza o CPF removendo caracteres não numéricos.

• Retorna os dados do CPF ou uma mensagem de erro em caso de falha.

2.3 Criando um controller para validar CPF

Agora, vamos criar um endpoint no Rails para chamar o serviço de validação.

rails generate controller CpfValidator validate

Edite o arquivo gerado app/controllers/cpf_validator_controller.rb:

class CpfValidatorController < ApplicationController
    def validate
    cpf = params[:cpf]
    result = CpfValidator.validate(cpf)
    render json: result
    end
end

Adicione a rota no config/routes.rb:

get '/validar_cpf/:cpf', to: 'cpf_validator#validate'

3. Testando a validação de CPF

Fazendo uma requisição via cURL

curl -X GET "http://localhost:3000/validar_cpf/12345678900"

Se tudo estiver correto, a resposta da API será semelhante a:

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

4. Benefícios da validação automática de CPF em Rails

• Redução de fraudes -- Evita cadastros falsos em tempo real.

• Melhora na experiência do usuário -- Aprovação rápida e automatizada.

• Conformidade com normas regulatórias -- Segue diretrizes da LGPD.

• Integração simples -- Pode ser implementado facilmente em qualquer aplicação Rails.

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em cerca de 900ms, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

A validação de CPF em tempo real melhora segurança, conformidade e experiência do usuário em aplicações Rails. Com a integração da API da CPFHub.io, seu sistema passa a verificar identidades de forma automática, reduzindo fraudes e garantindo conformidade com a LGPD desde o primeiro cadastro.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.