Validação de CPF em Vercel Edge Functions com SmartCPF

Validar CPF no frontend é insuficiente para cenários que exigem segurança e dados enriquecidos — formulários de cadastro, onboarding financeiro, compliance KYC e prevenção a fraudes precisam de uma fonte autoritativa. A API SmartCPF resolve isso consultando bases oficiais em milissegundos, retornando não apenas a validade do dígito verificador, mas também nome, data de nascimento, e-mails, telefones e status cadastral. O desafio é integrar essa consulta sem adicionar latência perceptível à experiência do usuário.

As Edge Functions do Vercel executam código em locais geograficamente distribuídos, próximos ao usuário final. Diferente de serverless tradicional (região única), o runtime edge roda no V8 Isolates, com cold start near-zero e limites de CPU/memória mais restritos. Isso torna a arquitetura ideal para validações rápidas e stateless, como a consulta de CPF, onde cada milissegundo conta na conversão de um formulário.

Como funcionam as Edge Functions no Vercel

Edge Functions são arquivos TypeScript/JavaScript colocados em app/api/ (App Router) ou pages/api/ (Pages Router) com a exportação export const runtime = 'edge'. Elas não têm acesso ao Node.js completo — APIs como fs, crypto nativo e módulos nativos não funcionam. O fetch global está disponível, assim como Request, Response, Headers e Web Crypto API. O payload de entrada vem do objeto Request e a resposta deve ser um Response padrão. O tamanho máximo do bundle é 1 MB (gzipped) e o tempo de execução é limitado a 50 ms de CPU por invocação no plano gratuito, 300 ms no Pro.

Vantagens de validar CPF na Edge

1. Latência imperceptível
A execução próxima ao usuário elimina o round-trip até um servidor central. A consulta à SmartCPF ocorre no mesmo POP da Edge Function, somando tipicamente 50-120 ms totais.

2. Zero cold start prático
V8 Isolates iniciam em microsegundos. Diferente de Lambdas Node.js, não há inicialização de runtime pesado — a função está pronta para a primeira requisição.

3. Escalabilidade automática sem configuração
O Vercel gerencia réplicas globalmente. Picos de cadastro (black friday, campanhas) não exigem provisionamento prévio.

4. Segurança por design
A API key da SmartCPF fica no servidor (variável de ambiente), nunca exposta no navegador. O CPF trafega apenas no backend, reduzindo superfície de ataque.

5. Custo previsível por requisição
Modelo pay-per-invocation do Vercel alinha-se ao modelo de créditos da SmartCPF — paga-se apenas pelo que consome.

6. Fácil versionamento e rollback
Cada deploy gera uma nova versão imutável. Reverter uma mudança quebrada leva segundos via dashboard ou CLI.

Desafios das Edge Functions

1. Limite de CPU estrito
50 ms (gratuito) ou 300 ms (Pro) de tempo de CPU por invocação. Lógica complexa, parsing pesado ou múltiplas chamadas sequenciais estouram o limite. A consulta à SmartCPF deve ser a única chamada externa.

2. Ausência de Node.js APIs
Bibliotecas que dependem de crypto (createHash, randomBytes), buffer ou stream falham. Use Web Crypto API (crypto.subtle) e TextEncoder/TextDecoder nativos.

3. Tamanho do bundle (1 MB gzipped)
Dependências grandes (ex: zod, date-fns completos) incham o bundle. Prefira validação manual de CPF ou micro-libs (cpf-check tem ~2 KB).

4. Sem filesystem persistente
Cache local não existe entre invocações. Para rate limiting ou deduplicação, use Vercel KV, Upstash Redis ou headers de cache HTTP.

5. Debugging limitado
Logs aparecem no dashboard do Vercel com latência. Não há attach de debugger remoto. Testes locais com vercel dev cobrem 90% dos casos, mas diferenças de runtime (V8 vs Node) ainda surgem em produção.

Como implementar com a SmartCPF

O exemplo abaixo cria uma Edge Function no App Router (app/api/validar-cpf/route.ts) que recebe CPF via POST, consulta a SmartCPF v2 com o pacote individuals e retorna os dados enriquecidos. A autenticação usa o header obrigatório X-API-KEY — nunca use Authorization: Bearer nem query string. Variáveis de ambiente (SMARTCPF_API_KEY) são injetadas pelo Vercel no deploy.

app/api/validar-cpf/route.ts

import { NextRequest, NextResponse } from 'next/server'

// Configuração da API SmartCPF
const SMARTCPF_BASE_URL = 'https://api.smartcpf.com.br/v2'
const PACKAGE = 'individuals' // pacote de consulta de pessoa física

// Validação simples de formato CPF (apenas dígitos, 11 caracteres)
function isValidCpfFormat(cpf: string): boolean {
  const digits = cpf.replace(/\D/g, '')
  if (digits.length !== 11) return false
  // Rejeita sequências repetidas (111.111.111-11, etc.)
  if (/^(\d)\1+$/.test(digits)) return false
  return true
}

// Cálculo do dígito verificador (algoritmo oficial)
function calculateCheckDigit(digits: string, factor: number): number {
  let sum = 0
  for (let i = 0; i < factor - 1; i++) {
    sum += parseInt(digits[i], 10) * (factor - i)
  }
  const remainder = (sum * 10) % 11
  return remainder === 10 ? 0 : remainder
}

function isValidCpfChecksum(cpf: string): boolean {
  const digits = cpf.replace(/\D/g, '')
  const d1 = calculateCheckDigit(digits, 10)
  const d2 = calculateCheckDigit(digits, 11)
  return d1 === parseInt(digits[9], 10) && d2 === parseInt(digits[10], 10)
}

export const runtime = 'edge'

export async function POST(request: NextRequest) {
  try {
    // 1. Lê e valida o body da requisição
    const body = await request.json()
    const rawCpf = body?.cpf

    if (!rawCpf || typeof rawCpf !== 'string') {
      return NextResponse.json(
        { success: false, error: 'CPF é obrigatório' },
        { status: 400 }
      )
    }

    const cpfDigits = rawCpf.replace(/\D/g, '')

    // 2. Validação local rápida (formato + checksum) antes de chamar a API
    if (!isValidCpfFormat(cpfDigits) || !isValidCpfChecksum(cpfDigits)) {
      return NextResponse.json(
        { success: false, error: 'CPF inválido' },
        { status: 400 }
      )
    }

    // 3. Recupera API key do ambiente (configurada no Vercel Dashboard)
    const apiKey = process.env.SMARTCPF_API_KEY
    if (!apiKey) {
      console.error('SMARTCPF_API_KEY não configurada')
      return NextResponse.json(
        { success: false, error: 'Erro de configuração do servidor' },
        { status: 500 }
      )
    }

    // 4. Chama a API SmartCPF v2 com header X-API-KEY obrigatório
    const url = `${SMARTCPF_BASE_URL}/individuals/${cpfDigits}?package=${PACKAGE}`
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'X-API-KEY': apiKey, // Header de autenticação obrigatório
        'Accept': 'application/json',
        'User-Agent': 'smartcpf-vercel-edge/1.0'
      },
      // Timeout defensivo: Edge Functions têm limite de CPU, não de wall-clock
      // AbortController garante que não travamos a function
      signal: AbortSignal.timeout(4000)
    })

    // 5. Trata respostas de erro da SmartCPF
    if (!response.ok) {
      const errorText = await response.text().catch(() => '')
      console.error(`SmartCPF error ${response.status}:`, errorText)

      // Mapeia códigos comuns para respostas amigáveis
      switch (response.status) {
        case 401:
          return NextResponse.json(
            { success: false, error: 'Credenciais inválidas' },
            { status: 500 }
          )
        case 403:
          return NextResponse.json(
            { success: false, error: 'Acesso negado — verifique plano/permissões' },
            { status: 403 }
          )
        case 404:
          return NextResponse.json(
            { success: false, error: 'CPF não encontrado nas bases' },
            { status: 404 }
          )
        case 422:
          return NextResponse.json(
            { success: false, error: 'CPF inválido ou mal formatado' },
            { status: 400 }
          )
        case 429:
          return NextResponse.json(
            { success: false, error: 'Rate limit excedido — tente novamente' },
            { status: 429 }
          )
        default:
          return NextResponse.json(
            { success: false, error: 'Erro ao consultar CPF' },
            { status: 502 }
          )
      }
    }

    // 6. Parse e retorno dos dados enriquecidos
    const data = await response.json()

    // Extrai campos relevantes para o frontend
    const result = {
      success: true,
      data: {
        cpf: data.result?.cpf,
        name: data.result?.name,
        birthDate: data.result?.birthDate,
        age: data.result?.age,
        status: data.result?.status,
        emails: data.result?.emails ?? [],
        phones: data.result?.phones ?? [],
        addresses: data.result?.addresses ?? [],
        // Metadados úteis para auditoria e debugging
        meta: {
          consultId: data.meta?.consultId,
          balance: data.meta?.balance,
          executionTimeMs: data.meta?.executionTimeMs,
          apiVersion: data.meta?.apiVersion,
          date: data.meta?.date
        }
      }
    }

    return NextResponse.json(result, {
      status: 200,
      headers: {
        // Cache curto para consultas repetidas do mesmo CPF na mesma sessão
        'Cache-Control': 'private, max-age=60, stale-while-revalidate=30'
      }
    })

  } catch (error) {
    // 7. Tratamento genérico de exceções (timeout, network, parsing)
    if (error instanceof DOMException && error.name === 'TimeoutError') {
      return NextResponse.json(
        { success: false, error: 'Tempo de consulta excedido' },
        { status: 504 }
      )
    }

    console.error('Erro inesperado na validação de CPF:', error)
    return NextResponse.json(
      { success: false, error: 'Erro interno do servidor' },
      { status: 500 }
    )
  }
}

// Exemplo de uso no frontend (client component)
/*
async function validarCpf(cpf: string) {
  const res = await fetch('/api/validar-cpf', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ cpf })
  })
  const data = await res.json()
  if (!data.success) throw new Error(data.error)
  return data.data
}

// Uso:
// const resultado = await validarCpf('111.111.111-11')
// console.log(resultado.name, resultado.meta.consultId, resultado.meta.balance)
*/

Resposta da API

A resposta abaixo ilustra o payload retornado pela SmartCPF v2 para o pacote individuals. Os campos meta.consultId (rastreabilidade), meta.balance (créditos restantes) e meta.executionTimeMs (latência real) são essenciais para monitoramento e billing.

response.json

{
  "meta": {
    "searchType": "CPF G",
    "consultId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user": "Fulano de Tal",
    "message": "CPF encontrado com sucesso",
    "ip": "127.0.0.1",
    "success": true,
    "apiVersion": "v2",
    "date": "2026-08-17T14:32:10.123Z",
    "executionTimeMs": 74.1,
    "balance": 9.77
  },
  "result": {
    "cpf": "111.111.111-11",
    "name": "João da Silva",
    "birthDate": "10/09/1992",
    "age": 33,
    "motherName": "Maria da Silva",
    "gender": "M",
    "status": "Regular",
    "emails": ["[email protected]"],
    "phones": [
      {
        "number": "(55) 99999-9999",
        "blockedTelemarketing": false,
        "operator": "VIVO",
        "type": "CELULAR",
        "whatsapp": false
      }
    ],
    "addresses": []
  },
  "success": true,
  "errors": []
}

O fluxo demonstrado resolve na prática:

Validação em duas camadas: checksum local (instantâneo) + consulta autoritativa (SmartCPF), evitando chamadas desnecessárias para CPFs obviamente inválidos.
Rastreabilidade total: meta.consultId permite auditar cada consulta nos logs da SmartCPF e correlacionar com eventos do seu sistema.
Controle de custos em tempo real: meta.balance mostra créditos restantes após cada consulta — integre com alertas quando cair abaixo do threshold.
Latência observável: meta.executionTimeMs expõe o tempo real da API, útil para SLA e dashboards de performance.
Dados enriquecidos prontos para uso: nome, idade, status cadastral, e-mails, telefones (com operadora e tipo) e endereços vêm estruturados, sem parsing adicional.

Por que usar a SmartCPF

Resposta consistentemente rápida: médias de 50-120 ms nas bases brasileiras, com SLA de disponibilidade 99,9%.
Integração simples: REST + header X-API-KEY, sem OAuth flows, SDKs obrigatórios ou contratos complexos.
Modelo de créditos transparente: paga-se por consulta bem-sucedida; saldo visível em meta.balance e no dashboard.
Escalabilidade nativa: infraestrutura preparada para picos de milhões de consultas/dia sem degradação.
Cobertura de dados ampla: além do status cadastral, retorna contatos, endereços e dados demográficos quando disponíveis.

Conclusão

Validar CPF na Edge do Vercel com a SmartCPF combina o melhor dos dois mundos: latência de borda para o usuário final e dados autoritativos de uma API especializada. O padrão de validação local + chamada externa protegida por API key no servidor elimina exposição de segredos, reduz chamadas desnecessárias e mantém o custo previsível. Crie sua conta na SmartCPF e faça sua primeira consulta em minutos.