API de CPF em Solid.js com createResource

O Solid.js é um framework reativo de alta performance para construção de interfaces. Com createResource, o Solid.js gerencia o ciclo de vida de chamadas assíncronas — incluindo estados de loading e erro — de forma declarativa. Combinado com server functions do SolidStart, a chave de API da CPFHub.io fica no servidor e a consulta retorna nome, gênero e data de nascimento do titular com latência de ~900ms.

1. Pré-requisitos

SolidStart configurado com npm create solid@latest.
Node.js 18+ instalado.
Uma conta na CPFHub.io

2. Configure a variável de ambiente

Crie o arquivo .env na raiz do projeto:

CPFHUB_API_KEY=SUA_CHAVE_DE_API

No SolidStart, variáveis sem prefixo VITE_ ficam acessíveis apenas no servidor.

3. Server function para consulta segura

Crie uma server function que consulta a API da CPFHub.io. Ela roda exclusivamente no servidor, protegendo a chave de API. A documentação do SolidStart detalha o uso de server functions em docs.solidjs.com:

// src/lib/cpfhub.ts
"use server";

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

export interface CpfResponse {
    success: boolean;
    data: CpfData;
}

export async function consultarCpf(cpf: string): Promise<CpfResponse> {
    const cpfLimpo = cpf.replace(/\D/g, '');

    if (cpfLimpo.length !== 11) {
    throw new 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/${cpfLimpo}`, {
    method: 'GET',
    headers: {
    'x-api-key': process.env.CPFHUB_API_KEY || '',
    'Accept': 'application/json'
    },
    signal: controller.signal
    });

    clearTimeout(timeoutId);

    if (!response.ok) {
    if (response.status === 401) throw new Error('Chave de API inválida');
    throw new Error(`Erro HTTP ${response.status}`);
    }

    return await response.json();
    } catch (error) {
    clearTimeout(timeoutId);
    throw error;
    }
}

4. Componente com createResource

O createResource do Solid.js reage a um sinal e executa uma função assíncrona automaticamente:

// src/routes/cpf/[cpf].tsx
import { createResource, Show, Suspense } from 'solid-js';
import { useParams } from '@solidjs/router';
import { consultarCpf } from '~/lib/cpfhub';

export default function CpfPage() {
    const params = useParams();

    const [cpfData] = createResource(
    () => params.cpf,
    async (cpf) => {
    const resultado = await consultarCpf(cpf);
    return resultado;
    }
    );

    return (
    <div>
    <h2>Resultado da Validação</h2>

    <Suspense fallback={<p>Consultando CPF...</p>}>
    <Show when={cpfData()?.success} fallback={<p>CPF não encontrado.</p>}>
    <dl>
    <dt>CPF</dt>
    <dd>{cpfData()?.data.cpf}</dd>
    <dt>Nome</dt>
    <dd>{cpfData()?.data.name}</dd>
    <dt>Gênero</dt>
    <dd>{cpfData()?.data.gender === 'M' ? 'Masculino' : 'Feminino'}</dd>
    <dt>Data de Nascimento</dt>
    <dd>{cpfData()?.data.birthDate}</dd>
    </dl>
    </Show>
    </Suspense>

    <Show when={cpfData.error}>
    <p style="color: red;">Erro: {cpfData.error?.message}</p>
    </Show>
    </div>
    );
}

5. Formulário interativo com createSignal e createResource

Para um formulário de busca reativo:

// src/routes/validar.tsx
import { createSignal, createResource, Show, Suspense } from 'solid-js';
import { consultarCpf } from '~/lib/cpfhub';

export default function ValidarPage() {
    const [cpfInput, setCpfInput] = createSignal('');
    const [cpfBusca, setCpfBusca] = createSignal<string | undefined>(undefined);

    const [resultado] = createResource(cpfBusca, async (cpf) => {
    if (!cpf) return null;
    return await consultarCpf(cpf);
    });

    function handleSubmit(e: Event) {
    e.preventDefault();
    const cpf = cpfInput().replace(/\D/g, '');
    if (cpf.length === 11) {
    setCpfBusca(cpf);
    }
    }

    return (
    <div>
    <h2>Validar CPF</h2>

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

    <Suspense fallback={<p>Carregando...</p>}>
    <Show when={resultado()?.success}>
    <dl>
    <dt>Nome</dt>
    <dd>{resultado()?.data.name}</dd>
    <dt>CPF</dt>
    <dd>{resultado()?.data.cpf}</dd>
    <dt>Data de Nascimento</dt>
    <dd>{resultado()?.data.birthDate}</dd>
    </dl>
    </Show>
    </Suspense>

    <Show when={resultado.error}>
    <p style="color: red;">Erro: {resultado.error?.message}</p>
    </Show>
    </div>
    );
}

6. API route com SolidStart

Para expor um endpoint REST na aplicação SolidStart:

// src/routes/api/cpf/[cpf].ts
import type { APIEvent } from '@solidjs/start/server';
import { consultarCpf } from '~/lib/cpfhub';

export async function GET(event: APIEvent) {
    const cpf = event.params.cpf;

    try {
    const resultado = await consultarCpf(cpf);
    return new Response(JSON.stringify(resultado), {
    headers: { 'Content-Type': 'application/json' }
    });
    } catch (error) {
    return new Response(
    JSON.stringify({ error: error instanceof Error ? error.message : 'Erro' }),
    { status: 502, headers: { 'Content-Type': 'application/json' } }
    );
    }
}

Teste com:

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

7. Exemplo de resposta da API

A API da CPFHub.io retorna um JSON padronizado em todas as consultas:

{
    "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
    }
}

8. Boas práticas

"use server" — Marque funções que acessam a chave de API com a diretiva "use server" para garantir que o código rode exclusivamente no servidor.
Timeout — O AbortController com 5 segundos evita que o createResource fique pendente indefinidamente.
Suspense — Use <Suspense> para mostrar feedback de carregamento enquanto o recurso é resolvido.
Reatividade — O createResource reexecuta automaticamente quando o sinal de entrada muda, evitando chamadas manuais.
Plano gratuito — O plano gratuito inclui 50 consultas/mês. Ao ultrapassar o limite, a API não bloqueia: cobra R$0,15 por consulta adicional. Para produção, o plano Pro (R$149/mês) oferece 1.000 consultas.

Perguntas frequentes

Por que usar createResource em vez de fetch direto no componente Solid.js?

O createResource integra o carregamento assíncrono ao sistema reativo do Solid.js: ele expõe estados de loading e error automaticamente, e reexecuta quando o sinal de entrada muda. Um fetch manual exige que você gerencie esses estados com createSignal e createEffect, aumentando a complexidade do código sem ganho real.

Como a diretiva "use server" protege a chave de API da CPFHub.io?

Funções marcadas com "use server" são excluídas do bundle do cliente pelo SolidStart durante o build. O browser recebe apenas o resultado da chamada — nunca o código que contém process.env.CPFHUB_API_KEY. Sem essa diretiva, a chave poderia aparecer no JavaScript enviado ao navegador.

O que acontece com o createResource se a API demorar mais que o esperado?

A latência média da CPFHub.io é ~900ms. O AbortController configurado com 5 segundos de timeout cancela a requisição caso ela ultrapasse esse limite, e o createResource entra no estado de erro — que pode ser capturado via cpfData.error e exibido ao usuário. Sem timeout, o componente ficaria no estado de loading indefinidamente.

O plano gratuito bloqueia a aplicação ao atingir o limite de consultas?

Não. Quando o limite de 50 consultas mensais é atingido, a API continua funcionando normalmente — cada consulta adicional é cobrada a R$0,15. A ANPD recomenda que dados pessoais sejam consultados apenas quando houver base legal, o que também ajuda a controlar o volume de requisições e os custos.

Conclusão

O Solid.js com createResource e SolidStart oferece uma integração reativa e segura com a API da CPFHub.io. A primitiva createResource cuida dos estados de loading e erro, enquanto as server functions garantem que a chave de API nunca seja exposta ao cliente.

Cadastre-se em cpfhub.io para obter sua chave gratuitamente e começar a validar CPFs em minutos.

CPFHub.io

Pronto para integrar a API?

50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

Começar grátis Ver 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.

Como consumir API de CPF em Solid.js com createResource