Validação de CPF em Vercel Edge Functions

Para integrar validação de CPF em Vercel Edge Functions, crie uma API Route com export const runtime = "edge" no Next.js e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. As Edge Functions executam na rede edge da Vercel em mais de 30 regiões ao redor do mundo, com cold starts praticamente zero, tornando-as ideais para APIs de validação que exigem baixa latência de infraestrutura. A latência total da consulta fica em torno de ~150 ms, dominada pelo tempo de resposta da API CPFHub.io, e pode ser reduzida a menos de 50ms com cache via Vercel KV.

Edge Functions vs. Serverless Functions

Antes de implementar, e importante entender a diferença:

Aspecto	Edge Functions	Serverless Functions
Runtime	Edge Runtime (V8 lite)	Node.js completo
Cold start	< 1ms	50-500ms
Regioes	30+ globalmente	Regiao específica
APIs disponíveis	Web APIs (fetch, etc.)	Node.js completo
Timeout máximo	30 segundos	60 segundos (Pro)
Tamanho max	1 MB	50 MB

Para chamadas a API de CPF, as Edge Functions são ideais: o fetch e nativo, o payload e pequeno e a resposta e rápida.

Edge Function como API Route (Next.js)

Com Next.js 13+ e App Router, crie uma Edge Function como API Route:

// app/api/cpf/[numero]/route.ts
import { NextRequest, NextResponse } from "next/server";

export const runtime = "edge";

const CPFHUB_API_KEY = process.env.CPFHUB_API_KEY!;
const API_URL = "https://api.cpfhub.io/cpf";
const TIMEOUT_MS = 10000;

interface CPFApiResponse {
    success: boolean;
    data?: {
    cpf: string;
    name: string;
    nameUpper: string;
    gender: string;
    birthDate: string;
    day: number;
    month: number;
    year: number;
    };
}

function limparCPF(cpf: string): string {
    return cpf.replace(/\D/g, "");
}

function validarFormato(cpf: string): string | null {
    if (cpf.length !== 11) return "CPF deve conter 11 digitos";
    if (/^(\d)\1+$/.test(cpf)) return "CPF invalido";
    return null;
}

export async function GET(
    request: NextRequest,
    { params }: { params: { numero: string } }
) {
    const cpf = limparCPF(params.numero);
    const erroFormato = validarFormato(cpf);

    if (erroFormato) {
    return NextResponse.json({ erro: erroFormato }, { status: 400 });
    }

    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);

    try {
    const response = await fetch(`${API_URL}/${cpf}`, {
    method: "GET",
    headers: {
    "x-api-key": CPFHUB_API_KEY,
    "Accept": "application/json",
    },
    signal: controller.signal,
    });

    clearTimeout(timeoutId);

    if (!response.ok) {
    return NextResponse.json(
    { erro: `Erro na API: ${response.status}` },
    { status: response.status }
    );
    }

    const resultado: CPFApiResponse = await response.json();

    if (!resultado.success || !resultado.data) {
    return NextResponse.json(
    { erro: "CPF nao encontrado" },
    { status: 404 }
    );
    }

    return NextResponse.json({
    valido: true,
    dados: {
    nome: resultado.data.name,
    cpf: resultado.data.cpf,
    genero: resultado.data.gender,
    dataNascimento: resultado.data.birthDate,
    },
    });
    } catch (error) {
    clearTimeout(timeoutId);

    if (error instanceof DOMException && error.name === "AbortError") {
    return NextResponse.json(
    { erro: "Timeout na consulta" },
    { status: 504 }
    );
    }

    return NextResponse.json(
    { erro: "Erro interno" },
    { status: 500 }
    );
    }
}

A diretiva export const runtime = "edge" instrui a Vercel a executar essa rota como Edge Function. A variavel CPFHUB_API_KEY e lida de process.env, que no Edge Runtime acessa as variaveis de ambiente configuradas no dashboard da Vercel.

Middleware para validação no edge

O middleware da Vercel executa antes de qualquer rota, ideal para validar CPF em requisições:

// middleware.ts
import { NextRequest, NextResponse } from "next/server";

export const config = {
    matcher: "/api/cpf/:numero*",
};

export function middleware(request: NextRequest) {
    // Rate limiting simples por IP
    const ip = request.ip ?? request.headers.get("x-forwarded-for") ?? "unknown";
    const rateLimitKey = `ratelimit:${ip}`;

    // Validar formato basico do CPF na URL
    const pathname = request.nextUrl.pathname;
    const cpfMatch = pathname.match(/\/api\/cpf\/(\d+)/);

    if (!cpfMatch) {
    return NextResponse.json(
    { erro: "CPF deve conter apenas digitos" },
    { status: 400 }
    );
    }

    const cpf = cpfMatch[1];

    if (cpf.length !== 11) {
    return NextResponse.json(
    { erro: "CPF deve conter exatamente 11 digitos" },
    { status: 400 }
    );
    }

    // Adicionar headers de seguranca
    const response = NextResponse.next();
    response.headers.set("X-Content-Type-Options", "nosniff");
    response.headers.set("X-Frame-Options", "DENY");

    return response;
}

Edge Function com Vercel KV para cache

Utilize o Vercel KV (baseado em Redis) para cachear resultados:

// app/api/cpf/[numero]/route.ts (com cache)
import { NextRequest, NextResponse } from "next/server";
import { kv } from "@vercel/kv";

export const runtime = "edge";

const CPFHUB_API_KEY = process.env.CPFHUB_API_KEY!;
const CACHE_TTL_SECONDS = 86400; // 24 horas

export async function GET(
    request: NextRequest,
    { params }: { params: { numero: string } }
) {
    const cpf = params.numero.replace(/\D/g, "");

    if (cpf.length !== 11) {
    return NextResponse.json(
    { erro: "CPF deve conter 11 digitos" },
    { status: 400 }
    );
    }

    // Verificar cache
    const cached = await kv.get(`cpf:${cpf}`);

    if (cached) {
    return NextResponse.json({
    valido: true,
    dados: cached,
    fonte: "cache",
    });
    }

    // Consultar API
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

    try {
    const response = await fetch(
    `https://api.cpfhub.io/cpf/${cpf}`,
    {
    method: "GET",
    headers: {
    "x-api-key": CPFHUB_API_KEY,
    "Accept": "application/json",
    },
    signal: controller.signal,
    }
    );

    clearTimeout(timeoutId);
    const resultado = await response.json();

    if (!resultado.success || !resultado.data) {
    return NextResponse.json(
    { erro: "CPF nao encontrado" },
    { status: 404 }
    );
    }

    const dados = {
    nome: resultado.data.name,
    cpf: resultado.data.cpf,
    genero: resultado.data.gender,
    dataNascimento: resultado.data.birthDate,
    };

    // Salvar no cache
    await kv.set(`cpf:${cpf}`, dados, { ex: CACHE_TTL_SECONDS });

    return NextResponse.json({
    valido: true,
    dados,
    fonte: "api",
    });
    } catch (error) {
    clearTimeout(timeoutId);
    return NextResponse.json(
    { erro: "Falha na consulta" },
    { status: 500 }
    );
    }
}

Configuração de variaveis de ambiente

No dashboard da Vercel, configure as variaveis:

Acesse o projeto na Vercel.
Va em Settings > Environment Variables.
Adicione:

CPFHUB_API_KEY = sua chave de API
Marque como Sensitive para criptografia adicional.
Selecione os ambientes: Production, Preview, Development.

Para desenvolvimento local, crie um arquivo .env.local:

CPFHUB_API_KEY=sua_chave_aqui

Server Actions do Next.js (alternativa)

Se preferir usar Server Actions em vez de API Routes:

// app/actions/cpf.ts
"use server";

const CPFHUB_API_KEY = process.env.CPFHUB_API_KEY!;

export async function validarCPFAction(cpf: string) {
    const cpfLimpo = cpf.replace(/\D/g, "");

    if (cpfLimpo.length !== 11) {
    return { erro: "CPF deve conter 11 digitos" };
    }

    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

    try {
    const response = await fetch(
    `https://api.cpfhub.io/cpf/${cpfLimpo}`,
    {
    method: "GET",
    headers: {
    "x-api-key": CPFHUB_API_KEY,
    "Accept": "application/json",
    },
    signal: controller.signal,
    }
    );

    clearTimeout(timeoutId);
    const resultado = await response.json();

    if (!resultado.success) {
    return { erro: "CPF nao encontrado" };
    }

    return {
    valido: true,
    nome: resultado.data.name,
    genero: resultado.data.gender,
    dataNascimento: resultado.data.birthDate,
    };
    } catch {
    clearTimeout(timeoutId);
    return { erro: "Falha na consulta" };
    }
}

Performance na edge da Vercel

Metricas tipicas para validação de CPF via Edge Functions na Vercel:

Cold start -- Menor que 1ms (praticamente inexistente).
Tempo total (sem cache) -- ~910ms (dominado pela latência da API CPFHub.io de ~150 ms).
Tempo total (com cache KV) -- ~10-50ms.
Disponibilidade -- A Vercel oferece 99,99% de SLA na infraestrutura Edge. Consulte a documentação oficial das Vercel Edge Functions para detalhes sobre limites e configurações.

Perguntas frequentes

O que é necessário para implementar validação de CPF em Vercel Edge Functions?

A validação de CPF em Edge Functions exige uma API Route com export const runtime = "edge" e uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em ~150 ms, e o resultado pode ser cacheado no Vercel KV para reduzir a latência nas consultas repetidas.

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 em um projeto Next.js?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel, crie a API Route com runtime edge e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. Para produção, adicione o Vercel KV para cache e configure as variáveis de ambiente no dashboard.

Conclusão

Vercel Edge Functions combinam a simplicidade de deploy da Vercel com a performance do Edge Runtime, criando uma plataforma ideal para APIs de validação de CPF. A integração com Next.js e nativa, o Vercel KV oferece cache distribuido e as variaveis de ambiente mantem a chave de API da CPFHub.io

Cadastre-se em cpfhub.io

CPFHub.io

Pronto para integrar a API?

50 créditos gratuitos para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

Começar grátis Ver documentação

Como integrar validação de CPF em Vercel Edge Functions para aplicações serverless