# Como consumir API de CPF em Cloudflare Workers com JavaScript > Aprenda a consumir uma API de consulta de CPF em Cloudflare Workers usando JavaScript. Exemplos com KV cache, Secrets e deploy via Wrangler. **Publicado:** 18/10/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/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**](https://www.cpfhub.io/) para obter sua API key gratuita. ### Instalando o Wrangler ```bash npm install -g wrangler wrangler login ``` --- ## 2. Criando o projeto ```bash wrangler init cpf-validation cd cpf-validation ``` ### Configuração do wrangler.toml ```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 ```javascript // 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): ```bash 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: ```bash # 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: ```json { "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 ```bash wrangler dev ``` Em outro terminal: ```bash curl -X GET "http://localhost:8787/cpf/12345678900" \ --max-time 30 ``` ### Deploy para produção ```bash 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](https://www.gov.br/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. ### 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) - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf) --- ## 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.