CPFHub.io

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:

CampoValor
MethodGET
URLhttps://api.cpfhub.io/cpf/{{ $json.cpf }}
AuthenticationGeneric Credential Type → Header Auth
Header Auth: Namex-api-key
Header Auth: Valuesua API Key (fica guardada na credencial, não no workflow)
Options → Responseligue 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

  1. Trigger: Webhook recebe { cpf, email, nome }
  2. HTTP Request: consulta GET /cpf/{{ $json.cpf }}
  3. Switch em {{ $json.statusCode }}:
    • 200: envia {{ $json.body.data.name }} para o CRM ou cria o registro no banco
    • 404: CPF não encontrado (sem custo); peça para o usuário conferir a digitação
    • 429: 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): No

Desligue 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:

  1. Watch Records (Airtable / Google Sheets): detecta novo registro com CPF
  2. HTTP: Make a Request: consulta o CPFHub.io
  3. Router com filtros em Status code: 200 segue para o próximo passo; 404 marca o registro como "CPF não encontrado"; os demais vão para uma rota de alerta
  4. 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:

  1. Trigger: qualquer evento (formulário, CRM, planilha)
  2. Action: Webhooks by Zapier → GET
    • URL: https://api.cpfhub.io/cpf/{{cpf}}
    • Headers: x-api-key: SUA_API_KEY
  3. Action seguinte: use os campos data.name, data.birthDate do retorno

LangChain

Python

Requer langchain>=1.0 e langchain-openai.

Python
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

TypeScript
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

TypeScript
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