Como integrar validação de CPF em Vercel Serverless Functions

Aprenda a integrar validação de CPF em Vercel Serverless Functions usando Node.js e Next.js. Exemplos com API Routes, Edge Functions e deploy.

Redação CPFHub.io
Redação CPFHub.io
··8 min de leitura
Como integrar validação de CPF em Vercel Serverless Functions

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.

Redação CPFHub.io

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.

WhatsAppFale conosco via WhatsApp