平台集成
与主流自动化和 AI 框架的集成方式。您可以直接调用 CPFHub.io API,也可以通过 MCP Server 使用。CPF 是巴西个人税号。
n8n
在工作流中使用 HTTP Request 节点直接调用 API。
节点配置:
| 字段 | 值 |
|---|---|
| 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 | 您的 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
- Trigger:Webhook 接收
{ cpf, email, nome } - HTTP Request:调用
GET /cpf/{{ $json.cpf }}查询 - 按
{{ $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 会被当作错误并中断场景。
典型场景:
- Watch Records(Airtable / Google Sheets):检测到含 CPF 的新记录
- HTTP: Make a Request:在 CPFHub.io 查询该 CPF
- 按
Status code过滤的 Router:200继续下一步,404将记录标记为“未查到 CPF”,其余进入告警路由 - Update Record:在原记录中填入姓名和出生日期
Zapier
使用 Webhooks by Zapier 应用创建 Zap 来调用 API:
- Trigger:任意事件(表单、CRM、电子表格)
- Action:Webhooks by Zapier → GET
- URL:
https://api.cpfhub.io/cpf/{{cpf}} - Headers:
x-api-key: YOUR_API_KEY
- URL:
- 后续 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 日