# Como consumir API de CPF em Hono para edge runtime

> Aprenda a consumir a API de consulta de CPF da CPFHub.io em Hono, o framework ultrarrápido para edge runtime como Cloudflare Workers e Deno.

**Publicado:** 17/05/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-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**](https://www.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:

```bash
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:

```bash
npx wrangler secret put CPFHUB_API_KEY
```

Declare o binding no `wrangler.toml`:

```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

```typescript
// 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](https://hono.dev/docs/middleware/builtin/rate-limiter) para opções avançadas de middleware:

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

```bash
npx wrangler dev
```

Para Node.js, adicione o adapter:

```bash
npm install @hono/node-server
```

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

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

---

## 7. Exemplo de resposta da API

A API da [**CPFHub.io**](https://www.cpfhub.io/)

```json
{
 "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

```bash
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:

```typescript
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`.

### 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)
- [Como consumir API de CPF em TypeScript com tipagem segura](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-typescript-com-tipagem-segura)
- [Como consumir API de CPF em NestJS com módulos e providers](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-nestjs-com-modulos-e-providers)

---

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

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