Integrar validação de CPF em Vercel Serverless Functions é simples e seguro: a Serverless Function age como proxy entre o front-end e a API da CPFHub.io, mantendo a chave de API no servidor e expondo apenas o resultado validado ao cliente. Com Node.js 18+ e a API da CPFHub.io — endpoint GET https://api.cpfhub.io/cpf/{CPF}, header x-api-key — é possível validar CPF em tempo real em projetos Next.js e aplicações standalone na Vercel sem gerenciar infraestrutura.
Introdução
A Vercel é uma das plataformas mais populares para deploy de aplicações front-end e serverless, especialmente para projetos que utilizam Next.js, React e outros frameworks JavaScript modernos. Com suas Serverless Functions, é possível criar APIs completas que rodam sob demanda, sem a necessidade de gerenciar infraestrutura.
Para startups e empresas que desenvolvem aplicações web modernas no Brasil, integrar validação de CPF em Serverless Functions da Vercel é uma solução prática e escalável.
1. Pré-requisitos
-
Conta na Vercel -- Plano gratuito (Hobby) suporta Serverless Functions.
-
Node.js 18 ou superior -- Runtime padrão da Vercel.
-
Vercel CLI -- Para desenvolvimento local e deploy.
-
Conta na CPFHub.io -- Cadastre-se em CPFHub.io e gere sua API key gratuitamente, sem cartão de crédito.
Instalando o Vercel CLI
npm install -g vercel
vercel login
2. Serverless Function standalone
Estrutura do projeto
cpf-validation/
├── api/
│ └── cpf/
│ └── [cpf].js
├── vercel.json
└── package.json
Implementação da função
// api/cpf/[cpf].js
export default async function handler(req, res) {
if (req.method !== 'GET') {
return res.status(405).json({ error: 'Método não permitido.' });
}
const { cpf } = req.query;
if (!cpf || !/^\d{11}$/.test(cpf)) {
return res.status(400).json({
error: 'CPF invalido. Informe 11 digitos numericos.',
});
}
const apiKey = process.env.CPFHUB_API_KEY;
if (!apiKey) {
console.error('CPFHUB_API_KEY não configurada.');
return res.status(500).json({ error: 'Erro de configuração do servidor.' });
}
try {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000);
const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
method: 'GET',
headers: {
'x-api-key': apiKey,
'Accept': 'application/json',
},
signal: controller.signal,
});
clearTimeout(timeoutId);
const data = await response.json();
if (response.ok && data.success) {
return res.status(200).json({
success: true,
data: data.data,
});
}
return res.status(response.status).json({
error: 'CPF não encontrado.',
});
} catch (error) {
if (error.name === 'AbortError') {
return res.status(504).json({ error: 'Timeout na consulta.' });
}
console.error('Erro ao consultar CPFHub:', error.message);
return res.status(500).json({ error: 'Erro interno.' });
}
}
3. Next.js App Router (API Route)
Se você utiliza Next.js com App Router, crie uma Route Handler:
// app/api/cpf/[cpf]/route.js
import { NextResponse } from 'next/server';
export async function GET(request, { params }) {
const { cpf } = params;
if (!cpf || !/^\d{11}$/.test(cpf)) {
return NextResponse.json(
{ error: 'CPF invalido. Informe 11 digitos numericos.' },
{ status: 400 }
);
}
const apiKey = process.env.CPFHUB_API_KEY;
try {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000);
const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
method: 'GET',
headers: {
'x-api-key': apiKey,
'Accept': 'application/json',
},
signal: controller.signal,
cache: 'no-store',
});
clearTimeout(timeoutId);
const data = await response.json();
if (response.ok && data.success) {
return NextResponse.json({
success: true,
data: {
cpf: data.data.cpf,
name: data.data.name,
nameUpper: data.data.nameUpper,
gender: data.data.gender,
birthDate: data.data.birthDate,
day: data.data.day,
month: data.data.month,
year: data.data.year,
},
});
}
return NextResponse.json(
{ error: 'CPF nao encontrado.' },
{ status: 404 }
);
} catch (error) {
console.error('Erro ao consultar CPFHub:', error.message);
return NextResponse.json(
{ error: 'Erro interno ao consultar a API.' },
{ status: 500 }
);
}
}
4. Configurando variáveis de ambiente
No dashboard da Vercel ou via CLI:
vercel env add CPFHUB_API_KEY
# Quando solicitado, insira: SUA_CHAVE_DE_API
# Selecione os ambientes: Production, Preview, Development
Para desenvolvimento local, crie um arquivo .env.local:
CPFHUB_API_KEY=SUA_CHAVE_DE_API
5. Exemplo de resposta da API
A API da CPFHub.io retorna um JSON com os dados do CPF:
{
"success": true,
"data": {
"cpf": "12345678900",
"name": "Joao da Silva",
"nameUpper": "JOAO DA SILVA",
"gender": "M",
"birthDate": "15/06/1990",
"day": 15,
"month": 6,
"year": 1990
}
}
- success -- Indica se a consulta foi bem-sucedida.
- name / nameUpper -- Nome completo do titular.
- gender -- Gênero (M ou F).
- birthDate -- Data de nascimento completa.
- day, month, year -- Componentes da data separados.
6. Componente React para consumir a API
Crie um componente React que consome a Serverless Function:
// components/CpfValidator.jsx
'use client';
import { useState } from 'react';
export default function CpfValidator() {
const [cpf, setCpf] = useState('');
const [resultado, setResultado] = useState(null);
const [loading, setLoading] = useState(false);
const [erro, setErro] = useState('');
const handleSubmit = async (e) => {
e.preventDefault();
setLoading(true);
setErro('');
setResultado(null);
const cpfLimpo = cpf.replace(/\D/g, '');
try {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000);
const response = await fetch(`/api/cpf/${cpfLimpo}`, {
signal: controller.signal,
});
clearTimeout(timeoutId);
const data = await response.json();
if (data.success) {
setResultado(data.data);
} else {
setErro(data.error || 'CPF não encontrado.');
}
} catch (error) {
setErro('Erro ao consultar. Tente novamente.');
} finally {
setLoading(false);
}
};
return (
<div>
<form onSubmit={handleSubmit}>
<input
type="text"
value={cpf}
onChange={(e) => setCpf(e.target.value)}
placeholder="Digite o CPF (11 dígitos)"
maxLength={14}
/>
<button type="submit" disabled={loading}>
{loading ? 'Consultando...' : 'Validar CPF'}
</button>
</form>
{erro && <p style={{ color: 'red' }}>{erro}</p>}
{resultado && (
<div>
<p><strong>Nome:</strong> {resultado.name}</p>
<p><strong>Gênero:</strong> {resultado.gender === 'M' ? 'Masculino' : 'Feminino'}</p>
<p><strong>Nascimento:</strong> {resultado.birthDate}</p>
</div>
)}
</div>
);
}
7. Deploy
# Deploy para preview
vercel
# Deploy para produção
vercel --prod
8. Boas práticas
-
Nunca exponha a chave de API no front-end -- A Serverless Function atua como proxy, mantendo a chave segura no servidor.
-
Configure timeout -- O AbortController com 30 segundos evita requisições pendentes.
-
Use cache quando possível -- Para CPFs consultados com frequência, utilize Vercel KV ou Redis para cache.
-
Implemente rate limiting -- Proteja sua Serverless Function contra abuso com middleware de rate limiting. O guia OWASP API Security Top 10 traz recomendações práticas sobre rate limiting e autenticação em APIs.
-
Monitore com Vercel Analytics -- Acompanhe latência e erros no dashboard da Vercel.
-
Entenda o modelo de cobrança -- O plano gratuito da CPFHub.io oferece 50 consultas mensais sem cartão de crédito; ao ultrapassar o limite, cada consulta extra custa R$0,15 sem bloqueio de serviço.
Perguntas frequentes
A Vercel é compatível com a API da CPFHub.io?
Sim. A CPFHub.io aceita requisições de qualquer ambiente com suporte a HTTPS, incluindo Serverless Functions da Vercel e Edge Functions. O runtime Node.js 18+ da Vercel já inclui fetch nativo, então não é necessária nenhuma biblioteca adicional para fazer a chamada.
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
A Vercel oferece uma plataforma moderna e ágil para deploy de Serverless Functions que integram validação de CPF. Seja com funções standalone ou API Routes do Next.js, a integração com a API da CPFHub.io é direta e segura, com conformidade LGPD, tempo de resposta de aproximadamente 900ms e 99,9% de uptime.
Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.
CPFHub.io
Pronto para integrar a API?
50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.
Sobre a redação
Redação CPFHub.io
Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.



