# Como validar CPF via API usando Ruby on Rails > Aprenda a validar CPF via API usando Ruby on Rails e a API da CPFHub.io. Guia completo com código, exemplos práticos e testes automatizados. **Publicado:** 20/10/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/validar-cpf-api-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**](https://www.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: ```bash bundle add faraday ``` Ou inclua no seu `Gemfile` e execute `bundle install`: ```ruby 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`: ```ruby 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`: ```ruby 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`: ```ruby 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 ```bash 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: ```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 } } ``` --- ## 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](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 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.