CPFHub.io

平台集成

与主流自动化和 AI 框架的集成方式。您可以直接调用 CPFHub.io API,也可以通过 MCP Server 使用。CPF 是巴西个人税号。

n8n

在工作流中使用 HTTP Request 节点直接调用 API。

节点配置:

字段值
MethodGET
URLhttps://api.cpfhub.io/cpf/{{ $json.cpf }}
AuthenticationGeneric Credential Type → Header Auth
Header Auth: Namex-api-key
Header Auth: Value您的 API 密钥(保存在凭据中,不要写在工作流里)
Options → Response开启 Include Response Headers and Status 和 Never Error

默认情况下,n8n 遇到任何 4xx 响应都会中断工作流,包括未查到 CPF 时的 404。开启 Never Error 和 Include Response Headers and Status 后,节点会始终继续执行,并返回 statusCode、headers 和 body。

示例工作流:注册时验证 CPF

  1. Trigger:Webhook 接收 { cpf, email, nome }
  2. HTTP Request:调用 GET /cpf/{{ $json.cpf }} 查询
  3. 按 {{ $json.statusCode }} 进行 Switch:
    • 200:将 {{ $json.body.data.name }} 发送到 CRM,或在数据库中创建记录
    • 404:未查到 CPF(不计费)。请用户检查输入是否正确
    • 429:等待 {{ $json.headers["retry-after"] }} 中的秒数(Wait 节点)后重试
    • 其他:通知团队。状态码说明见错误码

Make (Integromat)

在 Make 中,使用 HTTP: Make a Request 模块。

配置:

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

请关闭 Evaluate all states as errors。该选项开启时(默认开启),未查到 CPF 的 404 会被当作错误并中断场景。

典型场景:

  1. Watch Records(Airtable / Google Sheets):检测到含 CPF 的新记录
  2. HTTP: Make a Request:在 CPFHub.io 查询该 CPF
  3. 按 Status code 过滤的 Router:200 继续下一步,404 将记录标记为“未查到 CPF”,其余进入告警路由
  4. Update Record:在原记录中填入姓名和出生日期

Zapier

使用 Webhooks by Zapier 应用创建 Zap 来调用 API:

  1. Trigger:任意事件(表单、CRM、电子表格)
  2. Action:Webhooks by Zapier → GET
    • URL:https://api.cpfhub.io/cpf/{{cpf}}
    • Headers:x-api-key: YOUR_API_KEY
  3. 后续 Action:使用响应中的 data.name 和 data.birthDate 字段

LangChain

Python

需要 langchain>=1.0 和 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:
    """Looks up data for a person from their Brazilian CPF.
    Returns full name, gender and date of birth."""
    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 not found. Ask the user to check what they typed."
    if not r.ok:
        return f"Error {r.status_code} while looking up the CPF."
    data = r.json()["data"]
    return f"Name: {data['name']}, Date of birth: {data['birthDate']}, Gender: {data['gender']}"

agent = create_agent(
    model="openai:gpt-4o",
    tools=[lookup_cpf],
    system_prompt="Use lookup_cpf to validate identities. Never repeat the full CPF.",
)

result = agent.invoke({"messages": [{"role": "user", "content": "Validate 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 not found. Ask the user to check what they typed.'
    if (status !== 200) return `Error ${status} while looking up the CPF.`
    return `Name: ${body.data.name}, Date of birth: ${body.data.birthDate}`
  },
  {
    name: 'lookup_cpf',
    description: 'Looks up data for a person from their Brazilian CPF.',
    schema: z.object({
      cpf: z.string().describe('Brazilian CPF with or without formatting'),
    }),
  }
)

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: 'Looks up data for a person from their Brazilian CPF.',
      inputSchema: z.object({
        cpf: z.string().describe('Brazilian CPF with or without formatting'),
      }),
      execute: async ({ cpf }) => lookupCpf(cpf),
    }),
  },
  stopWhen: stepCountIs(3), // lets the model call the tool and then answer
  prompt: 'Verify the identity for CPF 12345678909',
})

console.log(result.text)

通过 MCP 在 Claude Desktop 中使用

如需在 Claude Desktop 中无代码使用,请在 Settings > Connectors > Add custom connector 中将 MCP Server 添加为连接器,URL 填写 https://api.cpfhub.io/mcp?api_key=YOUR_API_KEY。分步指南以及 Claude Code 和 Cursor 的配置方法见 MCP Server。


更新于 2026 年 10 月 3 日