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
-
O projeto deve estar hospedado em uma plataforma que suporte Gatsby Functions (Gatsby Cloud, Netlify ou similar). Consulte a documentação oficial do Gatsby 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:
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:
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:
gatsby develop
curl -X GET http://localhost:8000/api/cpf/12345678900 \
-H "Accept: application/json"
Resposta esperada:
{
"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:
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 prefixoGATSBY_para manter a chave no servidor. -
Timeout — O
AbortControllercom 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.
Conclusão
O Gatsby com funções serverless permite integrar a API da 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
CPFHub.io
Pronto para integrar a API?
50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à 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.



