Como usar API CPF no Next.js sem expor a chave
Um projeto Next.js pode oferecer interface React e um backend no mesmo repositório. A consulta de CPF deve ocorrer no servidor por uma Route Handler, Server Action ou outro serviço protegido. Colocar a chave numa variável NEXT_PUBLIC_ expõe o segredo ao navegador, então guarde-a como APICPF_KEY no ambiente server-side.
A API documenta GET https://api.apicpf.dev/consulta?cpf= com X-API-KEY. Leia a referência da API CPF para o JSON e os erros.
Exemplo de Route Handler no App Router
Crie app/api/consulta-cpf/route.ts. O trecho abaixo mostra apenas a chamada técnica: adicione autenticação, autorização e proteção contra abuso antes de publicar.
export const runtime = "nodejs";
export async function POST(req: Request) {
// TODO: verificar sessão, permissão e finalidade antes da consulta.
const body = await req.json().catch(() => null);
const cpf = String(body?.cpf ?? "").replace(/\D/g, "");
if (!/^\d{11}$/.test(cpf)) {
return Response.json({ error: "CPF mal formatado" }, { status: 400 });
}
const key = process.env.APICPF_KEY;
if (!key) return Response.json({ error: "Serviço indisponível" }, { status: 503 });
try {
const url = new URL("https://api.apicpf.dev/consulta");
url.searchParams.set("cpf", cpf);
const res = await fetch(url, {
headers: { "X-API-KEY": key, "Accept": "application/json" },
cache: "no-store",
signal: AbortSignal.timeout(8000),
});
if (!res.ok) return Response.json({ error: "Consulta indisponível" }, { status: 502 });
const json = await res.json();
return Response.json({ nome: json?.data?.nome ?? null });
} catch {
return Response.json({ error: "Falha de comunicação" }, { status: 502 });
}
}
O exemplo não faz verificação matemática dos dígitos, nem controle de acesso. Inclua essas etapas e só devolva dados autorizados para a finalidade da operação. Uma rota POST privada não altera o método GET usado entre seu backend e o provedor.
Por que cache e logs merecem atenção
Use cache: "no-store" em requisições que envolvem dados pessoais quando você não implementou política específica de cache. Não registre o URL completo com cpf nem retorne o corpo de erro upstream ao navegador. O backend pode registrar o status, a duração e um identificador interno, sem resposta cadastral.
Como depurar falhas
Trate 401 como problema de chave, 402 como falta de créditos e 429 como limite. Não informe dados internos ao consumidor da rota. Consulte o guia de status HTTP.
Perguntas frequentes
NEXT_PUBLIC_APICPF_KEY é seguro?
Não. Qualquer segredo colocado no bundle do cliente fica acessível ao usuário.
Posso retornar nome, mãe e nascimento direto do handler?
Somente se cada campo for indispensável e seu endpoint tiver autenticação e autorização adequadas. Em geral, devolva o mínimo.
