# Como consumir API de CPF em Bun com runtime ultra-rápido

> Aprenda a consumir a API de consulta de CPF usando Bun, o runtime JavaScript ultra-rápido, com fetch nativo, servidor HTTP e testes integrados.

**Publicado:** 16/09/2026
**Autor:** Redação CPFHub.io
**URL:** https://www.cpfhub.io/blog/como-consumir-api-cpf-bun-runtime-ultra-rapido

---


Bun é o runtime JavaScript que combina velocidade de startup (~7ms), fetch nativo otimizado e test runner integrado em um único binário. Para consumir a API de CPF da CPFHub.io, o overhead mínimo do Bun garante que o tempo de resposta total seja determinado pela rede, não pelo runtime. **Não publicamos um número de latência** — meça no seu ambiente. A disponibilidade contratada por plano é Grátis 95%, Pro 99% e Corporativo 99,9%; veja [preços](https://www.cpfhub.io/precos).

---

## Consulta básica com fetch nativo

O Bun implementa a Web Fetch API como global, assim como o Deno. A diferença está na performance — o Bun otimiza internamente as conexões HTTP para throughput máximo. Consulte a [documentação oficial do Bun](https://bun.sh/docs/api/fetch) para detalhes sobre as otimizações de rede:

```typescript
// src/cpfhub.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;
}

const API_URL = "https://api.cpfhub.io/cpf";
const API_KEY = Bun.env.CPFHUB_API_KEY ?? "";
const TIMEOUT_MS = 10000;

export async function consultarCPF(cpf: string): Promise<{
 sucesso: boolean;
 dados?: CPFData;
 erro?: string;
}> {
 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: `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 Error && error.name === "AbortError") {
 return { sucesso: false, erro: "Timeout na consulta" };
 }

 return { sucesso: false, erro: String(error) };
 }
}
```

Note o uso de `Bun.env` para acessar variáveis de ambiente — a API específica do Bun, embora `process.env` também funcione por compatibilidade com Node.js.

---

## Servidor HTTP com Bun.serve

O Bun inclui um servidor HTTP integrado que é significativamente mais rápido que o `http` do Node.js. Veja como criar uma API de validação de CPF:

```typescript
// src/server.ts
import { consultarCPF } from "./cpfhub";

const PORT = parseInt(Bun.env.PORT ?? "3000");

function jsonResponse(body: object, status = 200): Response {
 return new Response(JSON.stringify(body), {
 status,
 headers: {
 "Content-Type": "application/json",
 "X-Powered-By": "Bun",
 },
 });
}

const server = Bun.serve({
 port: PORT,

 async fetch(req: Request): Promise<Response> {
 const url = new URL(req.url);
 const inicio = performance.now();

 // Health check
 if (url.pathname === "/health") {
 return jsonResponse({
 status: "ok",
 runtime: "bun",
 version: Bun.version,
 timestamp: new Date().toISOString(),
 });
 }

 // Rota de consulta de CPF
 if (req.method === "GET" && url.pathname.startsWith("/api/cpf/")) {
 const cpf = url.pathname.split("/api/cpf/")[1];

 if (!cpf || cpf.replace(/\D/g, "").length !== 11) {
 return jsonResponse(
 { erro: "CPF invalido. Informe 11 digitos na URL." },
 400
 );
 }

 const resultado = await consultarCPF(cpf);
 const duracao = (performance.now() - inicio).toFixed(2);

 if (!resultado.sucesso) {
 return jsonResponse(
 { erro: resultado.erro, duracaoMs: duracao },
 resultado.erro?.includes("nao encontrado") ? 404 : 500
 );
 }

 return jsonResponse({
 valido: true,
 dados: {
 nome: resultado.dados!.name,
 cpf: resultado.dados!.cpf,
 genero: resultado.dados!.gender,
 dataNascimento: resultado.dados!.birthDate,
 },
 duracaoMs: duracao,
 });
 }

 return jsonResponse({ erro: "Rota nao encontrada" }, 404);
 },

 error(error: Error): Response {
 console.error("Erro no servidor:", error);
 return jsonResponse({ erro: "Erro interno do servidor" }, 500);
 },
});

console.log(`Servidor Bun rodando em http://localhost:${server.port}`);
```

Execute com:

```bash
CPFHUB_API_KEY=sua_chave bun run src/server.ts
```

---

## Testes com bun:test

O Bun inclui um test runner nativo que é até 30x mais rápido que o Jest:

```typescript
// src/cpfhub.test.ts
import { describe, test, expect, mock } from "bun:test";
import { consultarCPF } from "./cpfhub";

describe("consultarCPF", () => {
 test("rejeita CPF com menos de 11 digitos", async () => {
 const resultado = await consultarCPF("12345");
 expect(resultado.sucesso).toBe(false);
 expect(resultado.erro).toBe("CPF deve conter 11 digitos");
 });

 test("remove formatacao do CPF", async () => {
 const resultado = await consultarCPF("123.456.789-01");
 expect(resultado.erro).not.toBe("CPF deve conter 11 digitos");
 });

 test("retorna timeout apos limite", async () => {
 const fetchOriginal = globalThis.fetch;
 globalThis.fetch = mock(() =>
 new Promise((_, reject) => {
 setTimeout(() => reject(new DOMException("Aborted", "AbortError")), 100);
 })
 );

 const resultado = await consultarCPF("12345678901");
 expect(resultado.sucesso).toBe(false);
 expect(resultado.erro).toContain("Timeout");

 globalThis.fetch = fetchOriginal;
 });
});
```

Execute os testes:

```bash
bun test
```

---

## Comparativo de performance entre runtimes

O Bun se destaca em cenários de alta concorrência e baixa latência:

| Métrica | Node.js 20 | Deno 1.38 | Bun 1.1 |
|----------------------|-------------|-----------|-----------|
| Tempo de startup | ~50ms | ~30ms | ~7ms |
| Requisições/s (HTTP) | ~45.000 | ~55.000 | ~105.000 |
| Fetch (latência) | ~2ms | ~1.8ms | ~0.8ms |
| Install de pacotes | ~15s | ~12s | ~3s |

Para uma API de validação de CPF, o overhead mínimo do Bun significa que a maior parte do tempo de resposta é determinada pela rede e pela API, não pelo runtime. Não publicamos um número de latência da CPFHub.io — meça no seu ambiente. A disponibilidade por plano está em [preços](https://www.cpfhub.io/precos).

---

## Configuração para produção

Para deploy em produção, crie um Dockerfile otimizado:

```dockerfile
FROM oven/bun:1.1 AS base
WORKDIR /app

COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production

COPY src ./src

ENV NODE_ENV=production
EXPOSE 3000

CMD ["bun", "run", "src/server.ts"]
```

---

## Perguntas frequentes

### O Bun é compatível com pacotes npm existentes para chamadas HTTP?

Sim. O Bun mantém compatibilidade com o ecossistema npm — pacotes como `axios` e `node-fetch` funcionam sem modificação. Dito isso, o fetch nativo do Bun já é otimizado e não requer bibliotecas externas para a maioria dos casos de uso, incluindo integração com a CPFHub.io.

### Como lidar com o limite de consultas do plano gratuito no Bun?

O plano gratuito da CPFHub.io oferece 50 consultas por mês. Ao atingir esse limite, a API não bloqueia as requisições — cobra R$0,15 por consulta adicional. Para controlar o consumo no Bun, implemente um contador em memória com `Bun.env` e persista o estado em um arquivo JSON usando `Bun.write()` se precisar sobreviver a restarts.

### Como configurar variáveis de ambiente no Bun para a chave de API?

O Bun lê automaticamente arquivos `.env` na raiz do projeto — sem necessidade de bibliotecas como `dotenv`. Use `Bun.env.CPFHUB_API_KEY` para acessar a chave. Em produção, defina a variável diretamente no ambiente de execução (Docker, systemd, etc.) e nunca commite o arquivo `.env` no repositório.

### O Bun suporta TypeScript nativamente para integração com APIs?

Sim. O Bun executa TypeScript sem transpilação prévia — basta rodar `bun run arquivo.ts`. Isso acelera o desenvolvimento e elimina a necessidade de configurar `tsc` ou `ts-node`. Os tipos TypeScript para as respostas da CPFHub.io podem ser definidos diretamente no projeto, como demonstrado nos exemplos acima.

### Leia também

- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Como implementar retry e backoff exponencial em consultas de API de CPF](https://cpfhub.io/blog/como-implementar-retry-backoff-exponencial-consultas-api-cpf)
- [Como implementar cache inteligente em respostas de API de CPF](https://cpfhub.io/blog/como-implementar-cache-inteligente-respostas-api-cpf)
- [SLA de API de CPF: níveis de disponibilidade](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)

---

## Conclusão

O Bun traz uma proposta convincente para integrações com APIs externas: performance excepcional, fetch nativo otimizado, servidor HTTP integrado e testes rápidos — tudo em um único runtime. Para aplicações que precisam validar CPF com overhead mínimo de runtime, a combinação do Bun com a API da [**CPFHub.io**](https://www.cpfhub.io/) é uma escolha sólida. A CPFHub.io não publica um número de latência — meça no seu ambiente — e oferece disponibilidade contratada por plano (Grátis 95%, Pro 99%, Corporativo 99,9%); detalhes em [preços](https://www.cpfhub.io/precos).

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