Plataformas
Integrações com os principais frameworks de automação e IA. Use a API do CPFHub.io diretamente ou via MCP Server.
n8n
Use o node HTTP Request para chamar a API diretamente em workflows.
Configuração do node:
| Campo | Valor |
|---|---|
| Method | GET |
| URL | https://api.cpfhub.io/cpf/{{ $json.cpf }} |
| Authentication | Generic Credential Type → Header Auth |
| Header Auth: Name | x-api-key |
| Header Auth: Value | sua API Key (fica guardada na credencial, não no workflow) |
| Options → Response | ligue Include Response Headers and Status e Never Error |
Por padrão, o n8n interrompe o workflow em qualquer resposta 4xx, inclusive o 404 de CPF não encontrado. Com Never Error e Include Response Headers and Status ligados, o node sempre segue e devolve statusCode, headers e body.
Exemplo de workflow: validação de CPF no cadastro
- Trigger: Webhook recebe
{ cpf, email, nome } - HTTP Request: consulta
GET /cpf/{{ $json.cpf }} - Switch em
{{ $json.statusCode }}:200: envia{{ $json.body.data.name }}para o CRM ou cria o registro no banco404: CPF não encontrado (sem custo); peça para o usuário conferir a digitação429: espere o número de segundos de{{ $json.headers["retry-after"] }}(node Wait) e repita- outros: avise o time; veja os códigos em Códigos de Erro
Make (Integromat)
No Make, use o módulo HTTP: Make a Request.
Configuração:
URL: https://api.cpfhub.io/cpf/{{cpf}}
Method: GET
Headers:
x-api-key: {{api_key}}
Parse response: Yes
Evaluate all states as errors (except for 2xx and 3xx): NoDesligue Evaluate all states as errors: com a opção ligada (padrão), o 404 de CPF não encontrado vira erro e para o cenário.
Cenário típico:
- Watch Records (Airtable / Google Sheets): detecta novo registro com CPF
- HTTP: Make a Request: consulta o CPFHub.io
- Router com filtros em
Status code:200segue para o próximo passo;404marca o registro como "CPF não encontrado"; os demais vão para uma rota de alerta - Update Record: preenche nome e data de nascimento no registro original
Zapier
Use o Zap com o app Webhooks by Zapier para chamar a API:
- Trigger: qualquer evento (formulário, CRM, planilha)
- Action: Webhooks by Zapier → GET
- URL:
https://api.cpfhub.io/cpf/{{cpf}} - Headers:
x-api-key: SUA_API_KEY
- URL:
- Action seguinte: use os campos
data.name,data.birthDatedo retorno
LangChain
Python
Requer langchain>=1.0 e langchain-openai.
import os
import re
import requests
from langchain.agents import create_agent
from langchain.tools import tool
API_KEY = os.environ["CPFHUB_API_KEY"]
@tool
def lookup_cpf(cpf: str) -> str:
"""Consulta dados de uma pessoa a partir do CPF brasileiro.
Retorna nome completo, gênero e data de nascimento."""
digits = re.sub(r"\D", "", cpf)
r = requests.get(
f"https://api.cpfhub.io/cpf/{digits}",
headers={"x-api-key": API_KEY},
timeout=10,
)
if r.status_code == 404:
return "CPF não encontrado. Peça para o usuário conferir a digitação."
if not r.ok:
return f"Erro {r.status_code} ao consultar o CPF."
data = r.json()["data"]
return f"Nome: {data['name']}, Nascimento: {data['birthDate']}, Gênero: {data['gender']}"
agent = create_agent(
model="openai:gpt-4o",
tools=[lookup_cpf],
system_prompt="Use lookup_cpf para validar identidades. Nunca repita o CPF completo.",
)
result = agent.invoke({"messages": [{"role": "user", "content": "Valide o CPF 123.456.789-09"}]})
print(result["messages"][-1].content)TypeScript / LangChain.js
import { ChatOpenAI } from '@langchain/openai'
import { tool } from '@langchain/core/tools'
import { z } from 'zod'
async function lookupCpf(cpf: string) {
const res = await fetch(`https://api.cpfhub.io/cpf/${cpf.replace(/\D/g, '')}`, {
headers: { 'x-api-key': process.env.CPFHUB_API_KEY! },
})
return { status: res.status, body: await res.json() }
}
const cpfTool = tool(
async ({ cpf }) => {
const { status, body } = await lookupCpf(cpf)
if (status === 404) return 'CPF não encontrado. Peça para o usuário conferir a digitação.'
if (status !== 200) return `Erro ${status} ao consultar o CPF.`
return `Nome: ${body.data.name}, Nascimento: ${body.data.birthDate}`
},
{
name: 'lookup_cpf',
description: 'Consulta dados de uma pessoa a partir do CPF brasileiro.',
schema: z.object({
cpf: z.string().describe('CPF brasileiro com ou sem formatação'),
}),
}
)
const llm = new ChatOpenAI({ model: 'gpt-4o' }).bindTools([cpfTool])Vercel AI SDK
import { openai } from '@ai-sdk/openai'
import { generateText, stepCountIs, tool } from 'ai'
import { z } from 'zod'
async function lookupCpf(cpf: string) {
const res = await fetch(`https://api.cpfhub.io/cpf/${cpf.replace(/\D/g, '')}`, {
headers: { 'x-api-key': process.env.CPFHUB_API_KEY! },
})
if (res.status === 404) return { found: false }
const body = await res.json()
if (!res.ok) return { error: typeof body.error === 'string' ? body.error : body.error?.message }
return { found: true, ...body.data }
}
const result = await generateText({
model: openai('gpt-4o'),
tools: {
lookup_cpf: tool({
description: 'Consulta dados de uma pessoa a partir do CPF brasileiro.',
inputSchema: z.object({
cpf: z.string().describe('CPF brasileiro com ou sem formatação'),
}),
execute: async ({ cpf }) => lookupCpf(cpf),
}),
},
stopWhen: stepCountIs(3), // permite chamar a tool e depois responder
prompt: 'Verifique a identidade do CPF 12345678909',
})
console.log(result.text)Claude Desktop via MCP
Para usar no Claude Desktop sem código, adicione o MCP Server como conector em Configurações > Conectores > Adicionar conector personalizado, com a URL https://api.cpfhub.io/mcp?api_key=SUA_API_KEY. Veja o passo a passo e a configuração do Claude Code e do Cursor em MCP Server.
Atualizado em 3 de outubro de 2026