# Como validar CPF em tempo real em aplicações Rails usando APIs REST > Aprenda a validar CPF em tempo real em aplicações Ruby on Rails usando APIs REST. Guia completo com exemplos de código. **Publicado:** 16/12/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/validar-cpf-rails-api-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**](https://www.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. ```bash bundle add httparty ``` Ou manualmente, edite o `Gemfile` e adicione: ```ruby gem 'httparty' ``` Depois, execute: ```bash bundle install ``` --- ### 2.2 Criando um serviço para consultar CPF Crie um arquivo de serviço para centralizar as requisições à API. ```ruby # 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. ```bash rails generate controller CpfValidator validate ``` Edite o arquivo gerado `app/controllers/cpf_validator_controller.rb`: ```ruby class CpfValidatorController < ApplicationController def validate cpf = params[:cpf] result = CpfValidator.validate(cpf) render json: result end end ``` Adicione a rota no `config/routes.rb`: ```ruby get '/validar_cpf/:cpf', to: 'cpf_validator#validate' ``` --- ## 3. Testando a validação de CPF ### Fazendo uma requisição via cURL ```bash curl -X GET "http://localhost:3000/validar_cpf/12345678900" ``` Se tudo estiver correto, a resposta da API será semelhante a: ```json { "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](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm). * **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](https://www.gov.br/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. ### Leia também - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) --- ## 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**](https://www.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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.