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

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:

✅ Consulta em tempo real na Receita Federal.
✅ Baixo tempo de resposta (1800-2000ms).
✅ Segurança e conformidade com a LGPD.
✅ Geração de comprovante oficial da consulta.

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.

# Adicione a gem ao Gemfile
bundle add httparty

Gemfile

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.

mkdir -p app/services
nano app/services/cpf_validator.rb

Adicione o seguinte código:

require 'httparty'

class CpfValidator
  include HTTParty
  base_uri 'https://api.cpfhub.io/v1/cpf/validate'
  API_KEY = 'SUA_CHAVE_DE_API'

  def self.validate(cpf, birth_date)
    headers = { 'Content-Type' => 'application/json', 'x-api-key' => API_KEY }
    body = { cpf: cpf, birthDate: birth_date }.to_json
    response = post('', headers: headers, body: body)

    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 POST para validar o CPF.

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

• 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

app/controllers/cpf_validator_controller.rb

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

config/routes.rb

post '/validar_cpf', to: 'cpf_validator#validate'

3. Testando a validação de CPF

3.1 Fazendo uma requisição via cURL

curl -X POST "http://localhost:3000/validar_cpf" \
     -H "Content-Type: application/json" \
     -d '{"cpf": "123.456.789-00", "birth_date": "15/06/1990"}'

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

{
  "success": true,
  "data": {
    "name": "João da Silva",
    "status": "Regular",
    "situation": "Ativo",
    "birthDate": "15/06/1990",
    "cpfNumber": "12345678900",
    "registrationDate": "anterior a 10/11/1990",
    "verificationDigit": "03",
    "receipt": {
      "emissionTime": "22:08:26",
      "emissionDate": "13/01/2025",
      "controlCode": "XXXX.XXXX.XXXX.XXXX"
    },
    "validationUrl": "https://servicos.receita.fazenda.gov.br/Servicos/CPF/ca/ResultadoAut.asp?cp=12345678900&cc=XXXXXX&de=13012025&he=220826&dv=03&em=01",
    "validationHtmlUrl": "https://api.cpfhub.io/api/view-proof/12345678900/XXXXXXXXXXXXX"
  }
}

✅ O que essa resposta indica?

• O CPF existe e está regular.

• Os dados do titular foram validados com a Receita Federal.

• Um comprovante oficial foi gerado para a consulta.

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 Receita Federal e LGPD.
✅ Integração simples – Pode ser implementado facilmente em qualquer aplicação Rails.

Conclusão

🚀 Implemente agora mesmo e otimize seu sistema!