Como validar CPF via API usando Ruby on Rails

Introdução

A validação de CPF é um processo essencial para aplicações que lidam com cadastros de usuários, concessão de crédito, prevenção a fraudes e compliance regulatório. Com o Ruby on Rails, é possível integrar facilmente uma API de consulta de CPF para garantir que os dados sejam verificados em tempo real, reduzindo riscos e proporcionando maior confiabilidade no sistema.

Neste guia, vamos demonstrar passo a passo como validar um CPF utilizando a API da CPFHub.io em uma aplicação Ruby on Rails, cobrindo desde a configuração inicial até a implementação de testes e boas práticas de segurança.

Pré-requisitos

Antes de iniciar, certifique-se de que tem o seguinte configurado:

• Ruby on Rails instalado (versão 6 ou superior recomendada).

• Conta na CPFHub.io para obter uma chave de API.

• Biblioteca HTTP (

  faraday

  ) para fazer requisições à API.
• Ferramentas de teste como Postman ou

  cURL

  para validar as requisições.

Passo 1: Adicionar a biblioteca HTTP

Para realizar requisições à API, utilizaremos a gem Faraday, que permite interagir com serviços externos de maneira eficiente. Para adicioná-la ao seu projeto, execute:

bundle add faraday

Gemfile

bundle install

gem 'faraday'

Passo 2: Criar um serviço para validar CPF

No Rails, uma boa prática é criar um service object para lidar com chamadas externas à API, isolando a lógica de integração e facilitando a manutenção do código.

app/services/cpf_validator.rb

require 'faraday'
require 'json'

class CpfValidator
  BASE_URL = 'https://api.cpfhub.io/api/cpf'
  API_KEY = ENV['CPFHUB_API_KEY']

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

    JSON.parse(response.body)
  rescue Faraday::Error => e
    { error: "Erro ao conectar com a API: #{e.message}" }
  rescue JSON::ParserError
    { error: "Erro ao processar resposta da API." }
  end
end

Boas práticas

• Uso de variáveis de ambiente: A chave de API é armazenada no

  ENV['CPFHUB_API_KEY']

  para evitar exposição no código.
• Tratamento de erros: Captura falhas de conexão (

  Faraday::Error

  ) e erros na conversão JSON (

  JSON::ParserError

  ).

Passo 3: Criar um controlador para validar CPF

Agora, vamos criar um controlador para receber um CPF e uma data de nascimento, chamar o serviço e retornar a resposta JSON.

app/controllers/cpf_controller.rb

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

Melhoria na segurança

• Sanitização de entrada: Antes de enviar os dados para a API, recomenda-se remover caracteres especiais do CPF e validar o formato da data.

Passo 4: Configurar a rota

config/routes.rb

Rails.application.routes.draw do
  post '/validate_cpf', to: 'cpf#validate'
end

/validate_cpf

Passo 5: Testar a API

Agora que tudo está configurado, podemos testar nossa API utilizando cURL, Postman ou ferramentas de testes automatizados.

Teste com cURL

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

Teste com Postman

1. Abra o Postman e crie uma nova requisição POST.

2. Insira a URL:

   http://localhost:3000/validate_cpf

3. No Body, selecione JSON e adicione:

   {
     "cpf": "123.456.789-00",
     "birth_date": "15/06/1990"
   }

4. Clique em Send e verifique a resposta.

Se tudo estiver correto, você receberá um JSON semelhante a este:

{
  "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": "10:15:30",
      "emissionDate": "13/03/2025",
      "controlCode": "XXXX.XXXX.XXXX.XXXX"
    },
    "validationUrl": "https://servicos.receita.fazenda.gov.br/Servicos/CPF/ca/ResultadoAut.asp?cp=12345678900&cc=XXXXXX&de=13032025&he=101530&dv=03&em=01",
    "validationHtmlUrl": "https://api.cpfhub.io/api/view-proof/12345678900/XXXXXXXXXXXXX"
  }
}

Conclusão

Integrar a API da CPFHub.io com Ruby on Rails é um processo simples e eficiente para validar CPFs em tempo real. Seguindo os passos acima, sua aplicação poderá garantir que os dados dos usuários sejam verificados corretamente, proporcionando maior segurança, conformidade com a LGPD e evitando fraudes.