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.

Redação CPFHub.io
Redação CPFHub.io
··7 min de leitura
Como integrar validação de CPF em Gatsby com funções 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

  • 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 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.


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.

Redação CPFHub.io

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.

WhatsAppFale conosco via WhatsApp