API de CPF em Hono para edge runtime

O Hono é um framework web ultrarrápido e minimalista projetado para rodar em edge runtimes como Cloudflare Workers, Deno Deploy, Vercel Edge Functions e Bun. Para consumir a API de CPF da CPFHub.io com Hono, basta fazer uma requisição GET para https://api.cpfhub.io/cpf/{CPF} usando a Web Fetch API nativa, autenticada pelo header x-api-key. A latência média da API é de ~900ms, por isso configure o AbortController com timeout adequado — 5 segundos é o valor recomendado para edge runtimes. A combinação de Hono com a CPFHub.io permite validar CPFs na borda da rede, próximo ao usuário, sem depender de um servidor centralizado.

1. Pré-requisitos

Hono instalado (npm create hono@latest).
Uma conta na CPFHub.io
Wrangler CLI (para Cloudflare Workers) ou Node.js 18+ (para runtime Node).

2. Projeto Hono com Cloudflare Workers

Crie o projeto e instale as dependências:

npm create hono@latest cpf-validator
cd cpf-validator
npm install

3. Configuração de secrets

Para Cloudflare Workers

Use o Wrangler para definir o secret:

npx wrangler secret put CPFHUB_API_KEY

Declare o binding no wrangler.toml:

name = "cpf-validator"
main = "src/index.ts"
compatibility_date = "2024-01-01"

Para Node.js

Crie o arquivo .env:

CPFHUB_API_KEY=SUA_CHAVE_DE_API

4. Aplicação Hono completa

// src/index.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';

type Bindings = {
    CPFHUB_API_KEY: string;
};

const app = new Hono<{ Bindings: Bindings }>();

// Middleware CORS
app.use('/api/*', cors());

// Middleware de validação de CPF
function validarFormatoCpf(cpf: string): string | null {
    const cpfLimpo = cpf.replace(/\D/g, '');
    if (cpfLimpo.length !== 11) return null;
    return cpfLimpo;
}

// Endpoint de consulta de CPF
app.get('/api/cpf/:cpf', async (c) => {
    const cpfParam = c.req.param('cpf');
    const cpf = validarFormatoCpf(cpfParam);

    if (!cpf) {
    return c.json({ error: 'CPF deve conter 11 dígitos' }, 400);
    }

    const apiKey = c.env.CPFHUB_API_KEY;

    if (!apiKey) {
    return c.json({ error: 'Chave de API não configurada' }, 500);
    }

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

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

    clearTimeout(timeoutId);

    if (!response.ok) {
    const mensagens: Record<number, string> = {
    400: 'CPF com formato inválido',
    401: 'Chave de API inválida',
    404: 'CPF não encontrado'
    };

    return c.json(
    { error: mensagens[response.status] || `Erro HTTP ${response.status}` },
    response.status as 400 | 401 | 404 | 500
    );
    }

    const data = await response.json();
    return c.json(data);
    } catch (error) {
    clearTimeout(timeoutId);
    return c.json({ error: 'Timeout ou falha na conexão' }, 502);
    }
});

// Health check
app.get('/health', (c) => {
    return c.json({ status: 'ok', runtime: 'edge' });
});

export default app;

5. Middleware de rate limiting local

Para proteger seu endpoint de abusos, adicione rate limiting com o middleware do Hono. Consulte a documentação oficial do Hono para opções avançadas de middleware:

import { Hono } from 'hono';

// Rate limiter simples para edge (in-memory)
const requestCounts = new Map<string, { count: number; timestamp: number }>();

app.use('/api/*', async (c, next) => {
    const ip = c.req.header('cf-connecting-ip') || 'unknown';
    const now = Date.now();
    const entry = requestCounts.get(ip);

    if (entry && now - entry.timestamp < 60000) {
    if (entry.count >= 30) {
    return c.json({ error: 'Limite de requisições excedido' }, 429);
    }
    entry.count++;
    } else {
    requestCounts.set(ip, { count: 1, timestamp: now });
    }

    await next();
});

6. Teste local

Para Cloudflare Workers:

npx wrangler dev

Para Node.js, adicione o adapter:

npm install @hono/node-server

// src/serve.ts (apenas para Node.js)
import { serve } from '@hono/node-server';
import app from './index';

serve({ fetch: app.fetch, port: 3000 });
console.log('Servidor rodando em http://localhost:3000');

Teste com cURL:

curl -X GET http://localhost:3000/api/cpf/12345678900 \
    -H "Accept: application/json"

7. Exemplo de resposta da API

A API da CPFHub.io

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

8. Deploy para Cloudflare Workers

npx wrangler deploy

O endpoint estará disponível globalmente na edge da Cloudflare, com latência mínima para usuários em qualquer região.

9. Versão com cache na edge

Para reduzir chamadas à API e melhorar a performance, use o Cache API disponível em Cloudflare Workers:

app.get('/api/cpf/:cpf/cached', async (c) => {
    const cpf = validarFormatoCpf(c.req.param('cpf'));
    if (!cpf) return c.json({ error: 'CPF inválido' }, 400);

    const cacheKey = new Request(`https://cache.internal/cpf/${cpf}`);
    const cache = caches.default;

    // Verificar cache
    const cached = await cache.match(cacheKey);
    if (cached) {
    return new Response(cached.body, cached);
    }

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

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

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

    // Armazenar em cache por 1 hora
    const cacheResponse = new Response(JSON.stringify(data), {
    headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 'max-age=3600'
    }
    });

    c.executionCtx.waitUntil(cache.put(cacheKey, cacheResponse.clone()));
    return cacheResponse;
    } catch (error) {
    clearTimeout(timeoutId);
    return c.json({ error: 'Falha na consulta' }, 502);
    }
});

10. Boas práticas

Secrets -- Use wrangler secret put para Cloudflare Workers. Nunca hardcode chaves no código.
Timeout -- O AbortController com 5 segundos é essencial em edge runtimes, que geralmente têm limites de tempo de execução mais curtos.
Cache -- Implemente cache na edge para reduzir chamadas à API e economizar consultas do plano.
CORS -- Use o middleware cors() do Hono para controlar quais origens podem acessar seu endpoint.
Plano -- O plano Gratuito inclui 50 consultas/mês. Para alto volume na edge, o plano Pro (R$149/mês) oferece 1.000 consultas incluídas, com excedente cobrado a R$0,15/consulta — sem bloqueio.

Perguntas frequentes

Como o Hono se integra com a API de CPF da CPFHub.io?

O Hono usa a Web Fetch API nativa, que está disponível em todos os edge runtimes compatíveis. Basta fazer uma requisição GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key e sua chave de API. O Hono gerencia o contexto de bindings do Cloudflare Workers, tornando o acesso ao secret da API limpo e seguro sem expor a chave no código.

Qual o timeout recomendado para chamadas à API de CPF em edge runtimes?

A API da CPFHub.io opera com latência média de ~900ms. Em edge runtimes como Cloudflare Workers, que têm limites de CPU e tempo de execução, use um AbortController configurado para 5 segundos — tempo suficiente para cobrir picos eventuais de latência sem travar o worker por tempo excessivo.

A CPFHub.io bloqueia requisições quando o limite de consultas é atingido?

Não. Ao atingir o limite do plano, a CPFHub.io não bloqueia nem retorna erro 429. Cada consulta excedente é cobrada automaticamente a R$0,15. O plano gratuito oferece 50 consultas/mês sem cartão de crédito; o plano Pro inclui 1.000 consultas por R$149/mês. Sua integração em Hono não precisa implementar lógica de pausa para rate limit da API — trate apenas erros de rede com timeout e retry.

Como proteger a API key no Cloudflare Workers com Hono?

Use o comando npx wrangler secret put CPFHUB_API_KEY para armazenar a chave como secret criptografado no Cloudflare. No código Hono, acesse via c.env.CPFHUB_API_KEY — o valor nunca aparece em logs ou no bundle deployado. Nunca inclua a chave diretamente no código-fonte ou em variáveis de ambiente públicas do wrangler.toml.

Conclusão

O Hono é uma escolha excelente para criar APIs de validação de CPF na edge, combinando performance, simplicidade e compatibilidade com múltiplos runtimes. Com a API da CPFHub.io

Cadastre-se em cpfhub.io

CPFHub.io

Pronto para integrar a API?

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

Começar grátis Ver documentação

Sobre a redação

Redação CPFHub.io

Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.

Como consumir API de CPF em Hono para edge runtime