Como consumir API de CPF em Cloudflare Workers com JavaScript

Cloudflare Workers permite executar JavaScript no edge, em mais de 300 data centers ao redor do mundo, tornando-o ideal para validação de CPF com latência mínima. Integrado à API da CPFHub.io, o Worker responde consultas com alta disponibilidade e pode usar KV Storage para cachear resultados e economizar consultas do plano gratuito.

Introdução

O Cloudflare Workers é uma plataforma de edge computing que executa código JavaScript em mais de 300 data centers ao redor do mundo, oferecendo latência extremamente baixa para usuários em qualquer localização. Para aplicações que precisam validar CPFs com alta performance e disponibilidade, os Workers representam uma alternativa poderosa às plataformas serverless tradicionais.

1. Pré-requisitos

• Conta na Cloudflare -- Plano gratuito do Workers (100.000 requisições/dia).

• Wrangler CLI -- Ferramenta oficial para desenvolvimento e deploy de Workers.

• Node.js 18+ -- Para executar o Wrangler localmente.

• Conta na CPFHub.io -- Cadastre-se em CPFHub.io para obter sua API key gratuita.

Instalando o Wrangler

npm install -g wrangler
wrangler login

2. Criando o projeto

wrangler init cpf-validation
cd cpf-validation

Configuração do wrangler.toml

name = "cpf-validation"
main = "src/index.js"
compatibility_date = "2024-01-01"

[vars]
CPFHUB_BASE_URL = "https://api.cpfhub.io/cpf"

# KV Namespace para cache (criar com: wrangler kv:namespace create CPF_CACHE)
# [[kv_namespaces]]
# binding = "CPF_CACHE"
# id = "seu-namespace-id"

3. Implementação do Worker

// src/index.js

export default {
    async fetch(request, env) {
    const url = new URL(request.url);
    const path = url.pathname;

    // CORS preflight
    if (request.method === 'OPTIONS') {
    return new Response(null, {
    status: 204,
    headers: {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Methods': 'GET',
    'Access-Control-Allow-Headers': 'Content-Type',
    },
    });
    }

    // Rota: GET /cpf/:cpf
    const match = path.match(/^\/cpf\/(\d{11})$/);

    if (!match) {
    return jsonResponse(
    { error: 'Rota invalida. Use GET /cpf/{cpf} com 11 digitos.' },
    400
    );
    }

    const cpf = match[1];

    // Verificar cache (se KV estiver configurado)
    if (env.CPF_CACHE) {
    const cached = await env.CPF_CACHE.get(cpf, 'json');
    if (cached) {
    return jsonResponse({ success: true, data: cached, cache: true });
    }
    }

    // Consultar a API da CPFHub.io
    try {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 30000);

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

    clearTimeout(timeoutId);

    const data = await response.json();

    if (response.ok && data.success) {
    // Armazenar no cache por 24 horas
    if (env.CPF_CACHE) {
    await env.CPF_CACHE.put(cpf, JSON.stringify(data.data), {
    expirationTtl: 86400,
    });
    }

    return jsonResponse({ success: true, data: data.data });
    }

    return jsonResponse(
    { error: 'CPF nao encontrado.', status: response.status },
    response.status
    );
    } catch (error) {
    if (error.name === 'AbortError') {
    return jsonResponse({ error: 'Timeout na consulta.' }, 504);
    }

    return jsonResponse(
    { error: 'Erro interno ao consultar a API.' },
    500
    );
    }
    },
};

function jsonResponse(body, status = 200) {
    return new Response(JSON.stringify(body), {
    status,
    headers: {
    'Content-Type': 'application/json',
    'Access-Control-Allow-Origin': '*',
    },
    });
}

4. Configurando Secrets

Armazene a chave de API como Secret (nunca em variáveis de ambiente públicas):

wrangler secret put CPFHUB_API_KEY
# Quando solicitado, insira: SUA_CHAVE_DE_API

5. Configurando KV cache

O KV Storage da Cloudflare permite armazenar resultados de consultas para reduzir chamadas à API:

# Criar namespace KV
wrangler kv:namespace create CPF_CACHE

# Adicionar ao wrangler.toml
# [[kv_namespaces]]
# binding = "CPF_CACHE"
# id = "o-id-retornado-pelo-comando"

Com cache de 24 horas, consultas repetidas ao mesmo CPF são respondidas diretamente pelo edge, sem chamar a API.

6. Exemplo de resposta da API

A API da CPFHub.io retorna um JSON estruturado com os dados cadastrais do titular, incluindo nome, data de nascimento e gênero:

{
    "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.

7. Testando e deploy

Teste local

wrangler dev

Em outro terminal:

curl -X GET "http://localhost:8787/cpf/12345678900" \
    --max-time 30

Deploy para produção

wrangler deploy

Após o deploy, o Worker estará disponível em https://cpf-validation.seu-usuario.workers.dev/cpf/12345678900.

8. Vantagens do edge computing para validação de CPF

• Latência mínima -- O código é executado no data center mais próximo do usuário, reduzindo o tempo total de resposta.

• Escalabilidade automática -- Sem preocupações com provisionamento de servidores ou balanceamento de carga.

• Cache global -- O KV Storage replica dados em todos os data centers, garantindo acesso rápido em qualquer região.

• Alta disponibilidade -- A rede da Cloudflare oferece redundância global, complementando o 99,9% de uptime da CPFHub.io.

9. Boas práticas

• Use Secrets para chaves de API -- Nunca exponha a chave em variáveis de ambiente ou no código.

• Configure timeout -- O AbortController com 30 segundos evita que o Worker fique preso em requisições lentas.

• Implemente cache com KV -- Reduz o consumo de consultas e melhora a performance, especialmente no plano gratuito (50 consultas/mês).

• Monitore com Workers Analytics -- Acompanhe requisições, erros e tempo de execução pelo dashboard da Cloudflare.

• Gerencie o volume de consultas -- O plano gratuito da CPFHub.io oferece 50 consultas/mês sem bloqueio; consultas extras são cobradas a R$0,15 cada. O plano Pro (R$149/mês) inclui 1.000 consultas mensais. O KV cache é a estratégia mais eficaz para economizar quota.

Perguntas frequentes

O que é necessário para implementar validação de CPF em Cloudflare Workers?

Você precisa de uma conta na Cloudflare, do Wrangler CLI instalado e de uma API key da CPFHub.io. Com esses três elementos, o deploy básico leva menos de 30 minutos, conforme demonstrado nos exemplos deste artigo.

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.

O KV cache da Cloudflare é compatível com os requisitos da LGPD?

O KV cache armazena dados no edge global da Cloudflare. Para conformidade com a LGPD, configure o TTL de forma adequada (ex.: 24 horas), não armazene dados sensíveis além do necessário e considere usar cache apenas para respostas de CPF não encontrado, evitando persistir dados pessoais no edge.

Conclusão

Cloudflare Workers com JavaScript oferecem uma plataforma de edge computing ideal para validação de CPF com alta performance e disponibilidade global. A integração com a API da CPFHub.io é direta: configure o Secret com a API key, implante o Worker e use o KV Storage para cachear resultados e economizar quota. A latência de ~900ms da CPFHub.io, combinada com a rede global da Cloudflare, resulta em validação de CPF com tempo de resposta mínimo para usuários em qualquer região do Brasil.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.