# Como integrar validação de CPF em Deno com fetch nativo e Oak framework

> Aprenda a integrar a API de consulta de CPF em Deno usando fetch nativo e o framework Oak para criar endpoints seguros de validação.

**Publicado:** 14/09/2026
**Autor:** Redação CPFHub.io
**URL:** https://www.cpfhub.io/blog/como-integrar-validacao-cpf-deno-fetch-nativo-oak-framework

---


Deno é um runtime JavaScript e TypeScript criado por Ryan Dahl — o mesmo criador do Node.js — com foco em segurança, simplicidade e compatibilidade com padrões web. Diferente do Node.js, o Deno suporta TypeScript nativamente, possui fetch como API global e utiliza um modelo de permissões granular que impede acesso não autorizado a rede, sistema de arquivos e variáveis de ambiente. Para integrar a API da [**CPFHub.io**](https://www.cpfhub.io/) em Deno, você não precisa de nenhuma dependência adicional para o cliente HTTP — o fetch nativo e o framework Oak são suficientes para criar um endpoint de validação de CPF seguro e testável.

## Consulta de CPF com fetch nativo do Deno

O Deno implementa a [Fetch API](https://developer.mozilla.org/pt-BR/docs/Web/API/Fetch_API) do navegador como função global, sem necessidade de imports. Veja como consultar a API da CPFHub.io:

```typescript
// cpfhub_service.ts

interface CPFData {
 cpf: string;
 name: string;
 nameUpper: string;
 gender: string;
 birthDate: string;
 day: number;
 month: number;
 year: number;
}

interface CPFApiResponse {
 success: boolean;
 data?: CPFData;
}

interface ConsultaResultado {
 sucesso: boolean;
 dados?: CPFData;
 erro?: string;
}

const API_URL = "https://api.cpfhub.io/cpf";
const API_KEY = Deno.env.get("CPFHUB_API_KEY") ?? "";
const TIMEOUT_MS = 10000;

export async function consultarCPF(cpf: string): Promise<ConsultaResultado> {
 const cpfLimpo = cpf.replace(/\D/g, "");

 if (cpfLimpo.length !== 11) {
 return { sucesso: false, erro: "CPF deve conter 11 digitos" };
 }

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

 try {
 const response = await fetch(`${API_URL}/${cpfLimpo}`, {
 method: "GET",
 headers: {
 "x-api-key": API_KEY,
 "Accept": "application/json",
 },
 signal: controller.signal,
 });

 clearTimeout(timeoutId);

 if (!response.ok) {
 return {
 sucesso: false,
 erro: `API retornou status ${response.status}`,
 };
 }

 const resultado: CPFApiResponse = await response.json();

 if (!resultado.success || !resultado.data) {
 return { sucesso: false, erro: "CPF nao encontrado" };
 }

 return { sucesso: true, dados: resultado.data };
 } catch (error) {
 clearTimeout(timeoutId);

 if (error instanceof DOMException && error.name === "AbortError") {
 return { sucesso: false, erro: "Timeout na consulta de CPF" };
 }

 return {
 sucesso: false,
 erro: `Erro na requisicao: ${(error as Error).message}`,
 };
 }
}
```

Para executar, o Deno exige permissões explícitas:

```bash
deno run --allow-net=api.cpfhub.io --allow-env=CPFHUB_API_KEY cpfhub_service.ts
```

A flag `--allow-net=api.cpfhub.io` restringe o acesso de rede exclusivamente ao domínio da API. Isso garante que, mesmo que o código seja comprometido, ele não pode se comunicar com outros servidores.

---

## Criando uma API REST com Oak

Oak é o framework HTTP mais utilizado no Deno, inspirado no Koa do Node.js. Consulte a [documentação oficial do Oak](https://jsr.io/@oak/oak) para detalhes sobre middlewares e roteamento. Veja como criar um endpoint de validação de CPF:

```typescript
// server.ts
import { Application, Router, Context } from "https://deno.land/x/oak@v12.6.1/mod.ts";
import { consultarCPF } from "./cpfhub_service.ts";

const router = new Router();

router.get("/api/validar-cpf/:cpf", async (ctx: Context) => {
 const cpf = ctx.params.cpf;

 if (!cpf) {
 ctx.response.status = 400;
 ctx.response.body = { erro: "CPF e obrigatorio" };
 return;
 }

 const resultado = await consultarCPF(cpf);

 if (!resultado.sucesso) {
 ctx.response.status = resultado.erro?.includes("nao encontrado") ? 404 : 500;
 ctx.response.body = { erro: resultado.erro };
 return;
 }

 ctx.response.body = {
 valido: true,
 dados: {
 nome: resultado.dados!.name,
 genero: resultado.dados!.gender,
 dataNascimento: resultado.dados!.birthDate,
 },
 };
});

router.get("/health", (ctx: Context) => {
 ctx.response.body = { status: "ok", timestamp: new Date().toISOString() };
});

const app = new Application();

// Middleware de log
app.use(async (ctx, next) => {
 const inicio = Date.now();
 await next();
 const duracao = Date.now() - inicio;
 console.log(
 `${ctx.request.method} ${ctx.request.url.pathname} - ${ctx.response.status} (${duracao}ms)`
 );
});

// Middleware de tratamento de erros
app.use(async (ctx, next) => {
 try {
 await next();
 } catch (error) {
 console.error("Erro nao tratado:", error);
 ctx.response.status = 500;
 ctx.response.body = { erro: "Erro interno do servidor" };
 }
});

app.use(router.routes());
app.use(router.allowedMethods());

const PORT = parseInt(Deno.env.get("PORT") ?? "8000");
console.log(`Servidor Oak rodando em http://localhost:${PORT}`);
await app.listen({ port: PORT });
```

Execute com as permissões necessárias:

```bash
deno run \
 --allow-net=api.cpfhub.io,0.0.0.0:8000 \
 --allow-env=CPFHUB_API_KEY,PORT \
 server.ts
```

---

## Middleware de rate limiting com Oak

Para proteger a API contra abusos, implemente um middleware de rate limiting:

```typescript
// middleware/rate_limiter.ts
import { Context, Next } from "https://deno.land/x/oak@v12.6.1/mod.ts";

interface RateLimitEntry {
 count: number;
 resetAt: number;
}

const limites = new Map<string, RateLimitEntry>();
const MAX_REQUESTS = 10;
const WINDOW_MS = 60000; // 1 minuto

export async function rateLimiter(ctx: Context, next: Next) {
 const ip = ctx.request.ip;
 const agora = Date.now();
 const entry = limites.get(ip);

 if (!entry || entry.resetAt < agora) {
 limites.set(ip, { count: 1, resetAt: agora + WINDOW_MS });
 await next();
 return;
 }

 if (entry.count >= MAX_REQUESTS) {
 ctx.response.status = 429;
 ctx.response.body = {
 erro: "Limite de requisicoes excedido. Tente novamente em 1 minuto.",
 };
 return;
 }

 entry.count++;
 await next();
}
```

Adicione ao servidor antes das rotas:

```typescript
app.use(rateLimiter);
app.use(router.routes());
```

---

## Testes com Deno.test

O Deno inclui um framework de testes nativo. Veja como testar o serviço de CPF:

```typescript
// cpfhub_service_test.ts
import { assertEquals } from "https://deno.land/std@0.208.0/assert/mod.ts";
import { consultarCPF } from "./cpfhub_service.ts";

Deno.test("CPF com menos de 11 digitos retorna erro", async () => {
 const resultado = await consultarCPF("1234");
 assertEquals(resultado.sucesso, false);
 assertEquals(resultado.erro, "CPF deve conter 11 digitos");
});

Deno.test("CPF formatado e limpo corretamente", async () => {
 const resultado = await consultarCPF("123.456.789-00");
 assertEquals(resultado.sucesso, false);
});
```

Execute os testes:

```bash
deno test --allow-net=api.cpfhub.io --allow-env=CPFHUB_API_KEY
```

---

## Modelo de permissões do Deno para segurança

O modelo de permissões do Deno é particularmente valioso quando se trabalha com APIs que usam chaves secretas:

| Permissão | Flag | Uso na integração |
|------------------------|-------------------------------|------------------------------------|
| Rede | `--allow-net=api.cpfhub.io` | Restringir acesso ao domínio da API|
| Variáveis de ambiente | `--allow-env=CPFHUB_API_KEY` | Acesso apenas à chave necessária |
| Leitura de arquivos | `--allow-read=.env` | Ler arquivo de configuração |

Essa granularidade impede que vulnerabilidades no código acessem recursos não autorizados — uma vantagem significativa sobre o Node.js para aplicações que lidam com dados sensíveis como CPF.

---

## Deploy com Deno Deploy

Para colocar a aplicação em produção, o Deno Deploy é a opção mais simples. No Deno Deploy, as variáveis de ambiente são configuradas no dashboard do projeto, mantendo a chave de API segura. A integração com GitHub permite deploy automático a cada push.

---

## Perguntas frequentes

### Qual a vantagem de usar o Deno para integrar uma API de CPF?

O Deno elimina a necessidade de configurar bibliotecas de HTTP externas, já que o fetch é uma API global nativa compatível com o padrão web. O modelo de permissões granular impede que o código acesse rede ou variáveis de ambiente além do estritamente declarado, reduzindo a superfície de ataque em integrações que lidam com dados pessoais como CPF.

### Como o Deno gerencia o timeout na chamada à API de CPF?

O Deno usa a `AbortController` nativa do navegador para cancelar requisições. Basta criar um controller, passar o `signal` para o fetch e acionar `controller.abort()` após o tempo desejado com `setTimeout`. A latência típica da API da CPFHub.io é de ~900ms, então um timeout de 10 a 30 segundos é suficiente para cobrir variações de rede sem bloquear a aplicação indefinidamente.

### O Oak framework é adequado para produção com validação de CPF?

Sim. O Oak é o framework HTTP mais usado no ecossistema Deno e oferece middleware, roteamento, tratamento de erros e suporte a HTTPS. Para validação de CPF em produção, combine o Oak com rate limiting no middleware para proteger seu endpoint contra abusos, e configure variáveis de ambiente pelo Deno Deploy para manter a chave de API segura fora do código.

### O que acontece se o limite de consultas da CPFHub.io for atingido?

A API da CPFHub.io não bloqueia as requisições ao atingir o limite do plano. O serviço continua respondendo normalmente e as consultas excedentes são cobradas a R$0,15 cada. O plano gratuito inclui 50 consultas/mês; o Pro oferece 1.000 por R$149/mês. No Deno, monitore o consumo registrando cada chamada em log estruturado para identificar picos antes que impactem o orçamento.

## 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 integrar validação de CPF em Vercel Edge Functions](https://cpfhub.io/blog/como-integrar-validacao-cpf-vercel-edge-functions-aplicacoes-serverless)
- [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

Deno oferece uma base sólida para integrações com APIs de CPF: fetch nativo, TypeScript sem configuração, modelo de permissões granular e testes integrados. Combinado com o Oak framework, é possível criar APIs REST seguras e performáticas para validação de CPF em poucos arquivos.

A API da [**CPFHub.io**](https://www.cpfhub.io/) responde em ~900ms com autenticação por header `x-api-key`. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) e comece com 50 consultas gratuitas por mês.