Perfex CRM

Perfex CRM REST API — 示例、Postman Collection 与代码片段

🌐 English · 简体中文 · Español · Português (BR) · Italiano · Français · Deutsch · Türkçe · Tiếng Việt · ไทย · العربية

适用于 Perfex CRM 的 REST API 模块的即用型 Postman Collection、代码片段（cURL、PHP、Python、JavaScript）和资源 目录 — 这是将 Perfex CRM 连接到 AI Agent 和第三方应用的最快方式。

Perfex CRM REST API 通过简洁的 HTTP/JSON 接口，让你读取和写入客户、潜在客户、发票、报价、项目、 任务等数据，非常适合 CRM 集成、自动化和自定义应用。v3.0 新增了面向 AI Agent 的 MCP 服务、生产级 Webhooks、开箱即用的 Zapier / Make / n8n 轮询、批量操作，以及更智能的列表端点。本仓库是 Themesic Interactive 的 Perfex CRM REST API 模块的实用配套资源：可直接复制粘贴的示例、可导入的 Postman Collection，以及完整的 端点目录。

• 🧩 获取模块： https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/

• 📖 API 指南 / 在线文档： https://perfexcrm.themesic.com/apiguide/

• 🧾 OpenAPI 3.0 规范： GET https://yourdomain.com/api/openapi（参考副本）

---

🚀 v3.0 新功能

功能	端点	功能说明
🤖 MCP 服务	POST /api/mcp	Model Context Protocol（JSON-RPC 2.0）——向 Claude Desktop、ChatGPT、Cursor、n8n AI Agent 和任何 MCP 客户端提供 148 个经过权限筛选的 CRM 工具
🪝 Webhooks 2.0	/api/webhooks	124 个事件、REST 管理、支持重试的异步交付、SSRF 防护、经过 HMAC 签名的请求
🔌 自动化（轮询）	/api/zapier/*	为 Zapier、Make.com、n8n 和任何基于轮询的工具提供现成的轮询触发器
⚡ 批处理	POST /api/batch	在一个请求中执行最多 50 项操作（工具名称与 MCP 相同）
📚 知识库	/api/knowledge_base	文章和分组的 CRUD 操作
🗒️ 备注	/api/notes	支持跨 12 种实体类型的多态备注
📄 更智能的列表	任意列表端点	可选使用 ?page=&per_page=、?fields=、?sort=、?created_after=&created_before=
🛡️ 安全写入	任意 POST	支持 Idempotency-Key 重放、PUT 忽略未知字段、X-RateLimit-* 响应头
📐 OpenAPI 3.0 规范	GET /api/openapi	将全部接口整理为一份机器可读文档——74 个路径、144 项操作——数秒内即可导入 Postman、Insomnia 或 Stoplight（openapi/ 中的参考副本）

所有功能均为可选启用且向后兼容：不使用新参数的请求会返回与之前完全相同的响应。

---

目录

文件夹	内容
postman/	可导入的 Postman 集合和环境（{{base_url}}、{{authtoken}}）——现已包含 MCP、Webhooks、批处理、自动化、知识库和备注
snippets/curl/	最常用调用的可复制粘贴 curl 命令
snippets/php/	PHP（cURL）示例
snippets/python/	Python（requests）示例
snippets/javascript/	JavaScript / Node（fetch）示例
docs/	身份验证、分页和筛选、webhook、MCP、自动化、自定义表、错误和状态代码

每种代码片段语言都提供客户、发票、潜在客户的示例，以及 v3 功能webhook、mcp、批处理、自动化、knowledge_base 和备注的示例；此外还有一个 list_features 文件，展示分页、字段选择和排序。

---

快速开始

每个 Perfex CRM REST API 请求都通过 Authtoken 请求头进行身份验证。在 Perfex 管理后台的 API → API Management 中创建令牌（需先激活 REST API 模块）， 然后通过 https://yourdomain.com/api/... 调用 API：

curl -H "authtoken: YOUR_API_TOKEN" https://yourdomain.com/api/customers

这会以 JSON 格式返回客户列表。有关请求头与查询参数身份验证的说明，请参阅 docs/authentication.md；PHP、Python 和 JavaScript 中的相同调用示例，请参阅 snippets/。

使用 Postman 集合

1. 打开 Postman → Import → 导入 postman/perfex-rest-api.postman_collection.json。
2. 导入环境 postman/perfex-rest-api.postman_environment.json。
3. 将 base_url 设为 https://yourdomain.com/api，并将 authtoken 设为你的令牌。
4. 选择任意请求并点击 Send。

连接 AI Agent（MCP）

将任意 MCP 客户端（Claude Desktop、Cursor、ChatGPT、n8n AI Agent）指向 POST https://yourdomain.com/api/mcp， 并发送你的 authtoken 请求头。服务端会为你的 CRM 提供经过权限筛选的工具。请参阅 docs/mcp.md 和 snippets/curl/mcp.sh。

与 Claude、ChatGPT 和其他 AI 助手配合使用

只需一个 URL，即可连接任意助手：https://perfex-mcp.themesic.com/mcp。Claude、ChatGPT、 Cursor 和 VS Code 的分步设置指南：docs/connect-ai-assistants.md。

适用于 claude.ai、Cowork 和 Claude Code 的 Claude 插件（连接器 + 技能）位于 claude-plugin/。该插件需要 REST API 模块拥有有效许可证，并启用 MCP 服务。设置、权限和隐私政策请参阅 claude-plugin/README.md。

---

端点目录

所有 CRUD 端点均遵循 RESTful 约定：GET 列表、GET /:id 单条记录、POST 创建、 PUT /:id 更新、DELETE /:id 删除 — 基础路径为 https://yourdomain.com/api。

核心 CRM 资源

资源	基础路径	常见操作
客户	/api/customers	列表、获取、创建、更新、删除
联系人	/api/contacts	列表、获取、创建、更新、删除
潜在客户	/api/leads	列表、获取、创建、更新、删除
发票	/api/invoices	列表、获取、创建、更新、删除
估价单	/api/estimates	列表、获取、创建、更新、删除
贷项通知单	/api/credit_notes	列表、获取、创建、更新
付款	/api/payments	列表、获取、创建
提案	/api/proposals	列表、获取、创建、更新、删除
合同	/api/contracts	列表、获取、创建、更新、删除
项目	/api/projects	列表、获取、创建、更新、删除
任务	/api/tasks	列表、获取、创建、更新、删除
里程碑	/api/milestones	列表、获取、创建、更新、删除
工时表	/api/timesheets	列表、获取、创建、更新、删除
订阅	/api/subscriptions	列表、获取、创建、更新
项目	/api/items	列表、获取、创建、更新、删除
费用	/api/expenses	列表、获取、创建、更新、删除
员工	/api/staffs	列表、获取、创建、更新、删除
日历	/api/calendar	列表、获取、创建、更新、删除
自定义字段	/api/custom_fields	按关联类型列出
通用（查询数据）	/api/common	国家、税费、货币、状态……

v3 平台与额外资源

资源	基础路径	常见操作
MCP 服务	/api/mcp	POST JSON-RPC 2.0：initialize、tools/list、tools/call
批处理	/api/batch	在一个请求中执行多达 50 项操作
Webhook	/api/webhooks	列表、获取、创建、更新、删除、POST /:id/toggle、GET /events、GET /:id/logs
自动化（轮询）	/api/zapier	GET /resources、GET /poll/:resource、GET /test/:resource
知识库	/api/knowledge_base	列表、获取、创建、更新、删除；/groups
备注	/api/notes	按 :rel_type/:rel_id 列表、获取、创建、更新、删除

各资源的确切请求字段详见官方 API 指南。此处的代码片段涵盖最常见的流程。

---

更智能的列表端点（v3）

每个列表端点都接受可选查询参数。添加这些参数后，响应会采用 { data, meta } 封装； 省略这些参数则会返回与旧版完全相同的数组。

# Page 2, 20 per page, only id + company, newest first, created this year
curl -H "authtoken: YOUR_API_TOKEN" \
  "https://yourdomain.com/api/customers?page=2&per_page=20&fields=id,company&sort=-datecreated&created_after=2026-01-01"

参数	示例	效果
page、per_page	?page=2&per_page=20	分页 → { data, meta }
fields	?fields=id,company	仅返回这些列
sort	?sort=-datecreated,company	排序（- = 降序）
created_after、created_before	?created_after=2026-01-01	日期范围筛选

per_page 是用于设置每页大小的参数（1-100，默认值为 25）。只有同时传入 page 时，才会将 limit 作为别名接受；因此，单独使用 ?limit=5 不会进行分页——请使用 ?page=1&per_page=5。

请参阅 docs/pagination-filtering.md 和 snippets/curl/list_features.sh。

---

从 2.x 升级

没有破坏性变更。 所有 v3 列表功能均为可选：

• 不发送上述任何参数，即可获得与 2.x 返回结果相同的纯数组。只有发送 page 或 per_page 时，才会出现 { data, meta } 封装。
• 没有重命名任何端点。 客户端一直位于 /api/customers。
• PUT 中的未知字段会被忽略，而不会返回错误。
• POST 请求可以选择携带 Idempotency-Key 标头；重试相同的请求时会重放已存储的响应，而不是创建重复项。

采用 v3 时，有两点值得注意：

• 自定义表已在 3.0.2 中移至允许列表中，详见 docs/custom-tables.md。
• 在相应端点响应请求、相关 MCP 工具出现在 tools/list 中之前，必须先为现有令牌勾选新增的权限行（Webhooks、Notes、Knowledge Base）。

---

常见集成与使用场景

Perfex CRM REST API 常用于将 Perfex CRM 与 AI Agent 和第三方应用连接：

• AI 助手（MCP） — 让 Claude、ChatGPT 或 Cursor 通过 /api/mcp 读取和更新 CRM。
• Zapier / Make / n8n — 通过现成的轮询触发器（/api/zapier/*）实现无代码自动化。
• Webhooks — 将 Perfex 事件（新建发票、新线索，共 124 种事件）推送到 Slack、Discord 或你自己的后端，并使用 HMAC 签名。
• Google Sheets / Power Automate — 将客户、发票或付款同步到电子表格和仪表板。
• 自定义应用和门户 — 基于 Perfex 数据构建移动应用或客户门户。
• 会计与电子商务 — 将发票和商品与外部账单或商城平台同步。

以上功能均由 Perfex CRM 的 REST API 模块提供支持。

---

身份验证（摘要）

方法	方式
标头（推荐）	Authtoken: YOUR_API_TOKEN
查询参数	?authtoken=YOUR_API_TOKEN（适用于快速测试 / Webhooks）

令牌可在 API → API Management 中创建并设置作用范围（按资源设置权限）。完整详情请见 docs/authentication.md。

---

常见问题

Perfex CRM 有 REST API 吗？ 有。Perfex CRM 的 REST API 模块提供完整的 RESTful HTTP/JSON API，可用于客户、线索、发票、估价单、项目、任务等， 以及 v3 的 MCP 服务、Webhooks、批处理和自动化端点。

我可以将 Perfex CRM 与 AI Agent / ChatGPT / Claude 配合使用吗？ 可以 — v3 提供位于 POST /api/mcp 的 MCP 服务，可向任何模型上下文协议客户端公开经过权限筛选的 CRM 工具。详见 docs/mcp.md。

如何通过 Perfex CRM API 进行身份验证？ 在 Authtoken HTTP 标头中发送令牌（或将其作为 ?authtoken= 查询参数发送）。详见 docs/authentication.md。

Perfex CRM API 的基础 URL 是什么？ https://yourdomain.com/api — 例如 https://yourdomain.com/api/customers。

我可以将 Perfex CRM 连接到 Zapier、Make 或 n8n 吗？ 可以 — v3 在 /api/zapier/* 下提供现成的轮询触发器，并支持 Webhooks。请参阅 常见集成 和 docs/automation.md。

Perfex CRM 有 Postman 集合吗？ 有 — 导入 postman/perfex-rest-api.postman_collection.json 和随附的环境，设置 base_url 和 authtoken，即可开始发送请求。

如何通过 Perfex CRM API 创建发票？ 向 https://yourdomain.com/api/invoices 发送 POST 请求，并提供发票字段和 items[] 数组 — v3 会自动计算 subtotal/total。详见 snippets/curl/invoices.sh。

---

关于 / 支持

此仓库是以下商业模块的示例配套项目：

Perfex CRM 的 REST API — 将您的 Perfex CRM 与第三方应用连接 作者：Themesic Interactive。

• 🛒 购买 / 了解更多： https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/
• 📖 文档： https://perfexcrm.themesic.com/apiguide/
• 💬 支持： https://themesic.com/support

欢迎贡献更多示例 — 请参阅 CONTRIBUTING.md。

许可证

此仓库中的示例代码基于 MIT License 发布。“Perfex”是其各自所有者的商标；REST API 模块是 Themesic Interactive 的商业产品。