Plataformas

Integraciones con los principales frameworks de automatización e IA. Usa la API de CPFHub.io directamente o mediante el MCP Server. El CPF es el número de identificación fiscal de personas físicas en Brasil.

n8n

Usa el node HTTP Request para llamar a la API directamente en los workflows.

Configuración del 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	tu clave de API (queda guardada en la credencial, no en el workflow)
Options → Response	activa Include Response Headers and Status y Never Error

Por defecto, n8n detiene el workflow ante cualquier respuesta 4xx, incluido el 404 de CPF no encontrado. Con Never Error e Include Response Headers and Status activados, el node siempre continúa y devuelve statusCode, headers y body.

Ejemplo de workflow: validación de CPF en el registro

Trigger: Webhook recibe { cpf, email, nome }
HTTP Request: consulta GET /cpf/{{ $json.cpf }}
Switch sobre {{ $json.statusCode }}:
- 200: envía {{ $json.body.data.name }} al CRM o crea el registro en la base de datos
- 404: CPF no encontrado (sin costo). Pide al usuario que revise lo que escribió
- 429: espera la cantidad de segundos de {{ $json.headers["retry-after"] }} (node Wait) y reintenta
- otros: avisa al equipo. Consulta los códigos en Códigos de Error

Make (Integromat)

En Make, usa el módulo HTTP: Make a Request.

Configuración:

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

Desactiva Evaluate all states as errors. Con la opción activada (el valor por defecto), el 404 de CPF no encontrado se convierte en error y detiene el escenario.

Escenario típico:

Watch Records (Airtable / Google Sheets): detecta un nuevo registro con CPF
HTTP: Make a Request: consulta el CPF en CPFHub.io
Router con filtros sobre Status code: 200 sigue al siguiente paso, 404 marca el registro como "CPF no encontrado" y los demás van a una ruta de alerta
Update Record: completa nombre y fecha de nacimiento en el registro original

Zapier

Usa el Zap con la app Webhooks by Zapier para llamar a la API:

Trigger: cualquier evento (formulario, CRM, hoja de cálculo)
Action: Webhooks by Zapier → GET
- URL: https://api.cpfhub.io/cpf/{{cpf}}
- Headers: x-api-key: TU_API_KEY
Siguiente action: usa los campos data.name y data.birthDate de la respuesta

LangChain

Python

Requiere langchain>=1.0 y 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 los datos de una persona a partir del CPF brasileño.
    Devuelve nombre completo, género y fecha de nacimiento."""
    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 no encontrado. Pide al usuario que revise lo que escribió."
    if not r.ok:
        return f"Error {r.status_code} al consultar el CPF."
    data = r.json()["data"]
    return f"Nombre: {data['name']}, Nacimiento: {data['birthDate']}, Género: {data['gender']}"

agent = create_agent(
    model="openai:gpt-4o",
    tools=[lookup_cpf],
    system_prompt="Usa lookup_cpf para validar identidades. Nunca repitas el CPF completo.",
)

result = agent.invoke({"messages": [{"role": "user", "content": "Valida el 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 no encontrado. Pide al usuario que revise lo que escribió.'
    if (status !== 200) return `Error ${status} al consultar el CPF.`
    return `Nombre: ${body.data.name}, Nacimiento: ${body.data.birthDate}`
  },
  {
    name: 'lookup_cpf',
    description: 'Consulta los datos de una persona a partir del CPF brasileño.',
    schema: z.object({
      cpf: z.string().describe('CPF brasileño con o sin formato'),
    }),
  }
)

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 los datos de una persona a partir del CPF brasileño.',
      inputSchema: z.object({
        cpf: z.string().describe('CPF brasileño con o sin formato'),
      }),
      execute: async ({ cpf }) => lookupCpf(cpf),
    }),
  },
  stopWhen: stepCountIs(3), // permite llamar a la tool y luego responder
  prompt: 'Verifica la identidad del CPF 12345678909',
})

console.log(result.text)

Claude Desktop mediante MCP

Para usarlo en Claude Desktop sin código, agrega el MCP Server como conector en Configuración > Conectores > Agregar conector personalizado, con la URL https://api.cpfhub.io/mcp?api_key=TU_API_KEY. Consulta el paso a paso y la configuración de Claude Code y Cursor en MCP Server.

Actualizado el 3 de octubre de 2026