Como validar CPF via API usando Ruby on Rails

Para validar CPF via API usando Ruby on Rails, crie um service object que faz um GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key, processe o JSON retornado e integre o resultado ao seu fluxo de onboarding. A CPFHub.io retorna nome, data de nascimento e gênero do titular em cerca de 900ms, tornando a verificação transparente para o usuário final. O plano gratuito oferece 50 consultas mensais sem cartão de crédito — suficiente para prototipar e testar a integração completa.

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, você aprenderá a integrar 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.

Se ainda não tem uma conta, cadastre-se em CPFHub.io — o processo leva menos de dois minutos e não exige cartão de crédito.

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

Ou inclua no seu Gemfile e execute 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.

Crie o arquivo app/services/cpf_validator.rb:

require 'faraday'
require 'json'

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

    def self.validate(cpf)
    sanitized_cpf = cpf.gsub(/\D/, '')

    response = Faraday.get("#{BASE_URL}/#{sanitized_cpf}", nil, {
    'x-api-key' => API_KEY,
    'Accept' => 'application/json'
    })

    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).

• Sanitização do CPF: Remove caracteres não numéricos antes de enviar para a API.

Passo 3: Criar um controlador para validar CPF

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

Crie o arquivo app/controllers/cpf_controller.rb:

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

Passo 4: Configurar a rota

Adicione a seguinte linha ao seu arquivo config/routes.rb:

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

Isso permitirá que sua aplicação aceite requisições para validar CPFs no endpoint /validate_cpf/: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 GET "http://localhost:3000/validate_cpf/12345678900"

Teste com Postman

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

2. Insira a URL: http://localhost:3000/validate_cpf/12345678900

3. Clique em Send e verifique a resposta.

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

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

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 ~900ms, permitindo a verificação em tempo real durante o cadastro ou transação. Basta uma conta gratuita e a gem Faraday para começar.

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

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.

Vantagens da API CPFHub.io:

• Plano gratuito com 50 consultas mensais, sem cartão de crédito.

• Dados padronizados em JSON e atualizados diariamente.

• Resposta em ~900ms com 99,9% de uptime.

• Conformidade total com a LGPD e documentação completa em 13+ linguagens.

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