# Como integrar validação de CPF em Gatsby com funções serverless

> Aprenda a integrar a API de consulta de CPF da CPFHub.io em Gatsby usando Gatsby Functions para validação server-side segura.

**Publicado:** 10/05/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-gatsby-com-funcoes-serverless

---


O **Gatsby** é um framework React focado em sites estáticos de alta performance. Com as **Gatsby Functions**, o framework suporta endpoints serverless diretamente no projeto, permitindo consumir a API da CPFHub.io com segurança no backend — sem expor a chave de API ao navegador. A latência da API é de aproximadamente 900ms, por isso configure um timeout adequado na sua função. Veja abaixo como montar essa integração do zero.

---

## 1. Pré-requisitos

* **Gatsby 5+** configurado com `npm init gatsby`.

* Node.js 18+ instalado.

* Uma conta na [**CPFHub.io**](https://www.cpfhub.io/)

* O projeto deve estar hospedado em uma plataforma que suporte Gatsby Functions (Gatsby Cloud, Netlify ou similar). Consulte a [documentação oficial do Gatsby](https://www.gatsbyjs.com/docs/reference/functions/) para detalhes de deploy.

---

## 2. Configure a variável de ambiente

Crie o arquivo `.env.development` (para desenvolvimento) e `.env.production` (para produção):

```
CPFHUB_API_KEY=SUA_CHAVE_DE_API
```

O Gatsby carrega variáveis de `.env.*` automaticamente. Variáveis sem prefixo `GATSBY_` ficam disponíveis apenas no servidor (Gatsby Functions e Node.js), o que é o comportamento desejado para chaves de API.

---

## 3. Crie a Gatsby Function

Crie o arquivo `src/api/cpf/[cpf].ts`:

```typescript
import type { GatsbyFunctionRequest, GatsbyFunctionResponse } from 'gatsby';

export default async function handler(
 req: GatsbyFunctionRequest,
 res: GatsbyFunctionResponse
) {
 if (req.method !== 'GET') {
 return res.status(405).json({ error: 'Método não permitido' });
 }

 const cpf = (req.params.cpf || '').replace(/\D/g, '');

 if (cpf.length !== 11) {
 return res.status(400).json({ error: 'CPF deve conter 11 dígitos' });
 }

 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': process.env.CPFHUB_API_KEY || '',
 'Accept': 'application/json'
 },
 signal: controller.signal
 });

 clearTimeout(timeoutId);

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

 return res.status(response.status).json({
 error: statusMessages[response.status] || `Erro HTTP ${response.status}`
 });
 }

 const data = await response.json();
 return res.status(200).json(data);
 } catch (error) {
 clearTimeout(timeoutId);
 return res.status(502).json({ error: 'Timeout ou falha na conexão com a API' });
 }
}
```

A função fica acessível em `GET /api/cpf/{cpf}`. A chave de API é lida de `process.env` e nunca exposta ao navegador.

---

## 4. Página de consulta com React

Crie a página `src/pages/validar-cpf.tsx`:

```typescript
import React, { useState } from 'react';

interface CpfResult {
 success: boolean;
 data: {
 cpf: string;
 name: string;
 nameUpper: string;
 gender: string;
 birthDate: string;
 day: number;
 month: number;
 year: number;
 };
}

export default function ValidarCpfPage() {
 const [cpfInput, setCpfInput] = useState('');
 const [resultado, setResultado] = useState<CpfResult | null>(null);
 const [erro, setErro] = useState<string | null>(null);
 const [carregando, setCarregando] = useState(false);

 async function handleSubmit(e: React.FormEvent) {
 e.preventDefault();
 setErro(null);
 setResultado(null);

 const cpf = cpfInput.replace(/\D/g, '');

 if (cpf.length !== 11) {
 setErro('CPF deve conter 11 dígitos');
 return;
 }

 setCarregando(true);

 try {
 const response = await fetch(`/api/cpf/${cpf}`);
 const data = await response.json();

 if (response.ok && data.success) {
 setResultado(data);
 } else {
 setErro(data.error || 'Erro na consulta');
 }
 } catch {
 setErro('Falha na conexão');
 } finally {
 setCarregando(false);
 }
 }

 return (
 <main>
 <h1>Validar CPF</h1>

 <form onSubmit={handleSubmit}>
 <label htmlFor="cpf">CPF:</label>
 <input
 type="text"
 id="cpf"
 value={cpfInput}
 onChange={(e) => setCpfInput(e.target.value)}
 placeholder="Digite o CPF"
 maxLength={14}
 required
 />
 <button type="submit" disabled={carregando}>
 {carregando ? 'Consultando...' : 'Validar'}
 </button>
 </form>

 {erro && <p style={{ color: 'red' }}>{erro}</p>}

 {resultado?.success && (
 <div>
 <h2>Resultado</h2>
 <p><strong>Nome:</strong> {resultado.data.name}</p>
 <p><strong>CPF:</strong> {resultado.data.cpf}</p>
 <p><strong>Gênero:</strong> {resultado.data.gender === 'M' ? 'Masculino' : 'Feminino'}</p>
 <p><strong>Data de Nascimento:</strong> {resultado.data.birthDate}</p>
 </div>
 )}
 </main>
 );
}

export const Head = () => <title>Validar CPF</title>;
```

---

## 5. Teste com cURL

Inicie o servidor de desenvolvimento e teste a Gatsby Function:

```bash
gatsby develop
```

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

Resposta esperada:

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

---

## 6. Carregamento via Gatsby Source Plugin (build time)

Se você precisa validar CPFs durante o build (por exemplo, para gerar páginas estáticas com dados validados), crie um source plugin local em `plugins/gatsby-source-cpfhub/gatsby-node.js`:

```javascript
const fetch = require('node-fetch');

exports.sourceNodes = async ({ actions, createNodeId, createContentDigest }) => {
 const { createNode } = actions;
 const cpfs = ['12345678900']; // Lista de CPFs para validar no build

 for (const cpf of cpfs) {
 const controller = new AbortController();
 const timeoutId = setTimeout(() => controller.abort(), 5000);

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

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

 if (data.success) {
 createNode({
 ...data.data,
 id: createNodeId(`cpf-${cpf}`),
 internal: {
 type: 'CpfValidado',
 contentDigest: createContentDigest(data.data)
 }
 });
 }
 } catch (error) {
 clearTimeout(timeoutId);
 console.warn(`Erro ao validar CPF ${cpf}: ${error.message}`);
 }
 }
};
```

---

## 7. Boas práticas

* **Variáveis de ambiente** — Use arquivos `.env.*` sem prefixo `GATSBY_` para manter a chave no servidor.

* **Timeout** — O `AbortController` com 5 segundos evita que a função serverless exceda o tempo limite da plataforma. A API tem latência de ~900ms em condições normais.

* **Tratamento de erros** — Mapeie os códigos HTTP (400, 401, 404) para mensagens específicas.

* **Cobrança por excedente** — O plano Gratuito oferece 50 consultas/mês. Consultas acima do limite não são bloqueadas: geram cobrança de R$0,15 cada. O plano Pro (R$ 149/mês) inclui 1.000 consultas.

* **Cache** — Para CPFs consultados repetidamente, considere adicionar cache no nível da Gatsby Function ou usar o source plugin para build-time caching.

---

## Perguntas frequentes

### Como funciona a autenticação na API CPFHub.io dentro de uma Gatsby Function?

A chave de API deve ser enviada no header `x-api-key` em cada requisição `GET https://api.cpfhub.io/cpf/{CPF}`. Dentro de uma Gatsby Function, você lê a chave de `process.env.CPFHUB_API_KEY`, que fica disponível apenas no servidor — o navegador nunca tem acesso a ela. Isso garante que a credencial não vaze para o client-side.

### Qual é a latência esperada ao chamar a API CPFHub.io a partir de uma função serverless?

A latência da API é de aproximadamente 900ms. Some a isso o cold start da sua função serverless (que pode variar de 100ms a mais de 1 segundo em plataformas como Netlify e Gatsby Cloud). Configure um timeout de pelo menos 5 segundos para evitar falhas em situações de carga ou variação de rede.

### A API CPFHub.io bloqueia requisições quando o limite do plano é atingido?

Não. Quando o volume de consultas ultrapassa o limite do plano (50/mês no gratuito, 1.000/mês no Pro), a API não bloqueia nem retorna erro — ela continua respondendo e cobra R$0,15 por consulta adicional. Monitore seu consumo no painel em `app.cpfhub.io/settings/billing` para evitar cobranças inesperadas.

### Posso usar Gatsby Functions para validação de CPF em produção com alto volume?

Sim, desde que o plano de hospedagem suporte o número de invocações necessárias. A própria CPFHub.io escala automaticamente — para volumes altos, o plano Pro (R$149/mês com 1.000 consultas incluídas) é mais econômico do que o excedente do plano gratuito. Combine cache na função serverless com expiração por tempo para reduzir chamadas repetidas.

### 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)
- [Autenticação em APIs REST: como garantir segurança na consulta de CPF](https://cpfhub.io/blog/autenticacao-apis-rest-seguranca-consulta-cpf)
- [Como consumir API de CPF em TypeScript com tipagem segura](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-typescript-com-tipagem-segura)

---

## Conclusão

O Gatsby com funções serverless permite integrar a API da [**CPFHub.io**](https://www.cpfhub.io/) de forma segura, mantendo a chave de API no servidor e expondo ao frontend apenas os dados necessários.

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