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

> Aprenda a criar Vercel Edge Functions que validam CPF via API CPFHub.io com runtime Edge, middleware e integração com Next.js e frameworks frontend.

**Publicado:** 05/10/2026
**Autor:** Lucas Vieira
**URL:** https://www.cpfhub.io/blog/como-integrar-validacao-cpf-vercel-edge-functions-aplicacoes-serverless

---


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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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:

1. Acesse o projeto na Vercel.
2. Va em **Settings > Environment Variables**.
3. 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:

```typescript
// 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](https://vercel.com/docs/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](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 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.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura)
- [Autenticação em APIs REST: como garantir segurança na consulta de CPF](https://cpfhub.io/blog/autenticacao-apis-rest-seguranca-consulta-cpf)
- [Como implementar validação de CPF em microsserviços com Docker e Kubernetes](https://cpfhub.io/blog/como-implementar-validacao-cpf-microsservicos-docker-kubernetes)

---

## 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**](https://www.cpfhub.io/)

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)