Zapier、Make 和 n8n

集成平台无需编写代码即可把 Sursa 与数百种其他工具连接起来。它们不需要专门的 Sursa 应用：平台通用的 HTTP 请求和 Webhook 步骤可以直接使用 API。本指南介绍三种最常见的做法：

做法	方向	所需条件
把其他工具中的记录作为卡片推送到 Sursa	进入 Sursa	一个自定义数据源及其 `kbsrc_` 密钥
在工作流中向 Sursa 提问	进入 Sursa 并返回	具有 `ask` 权限范围的 API 密钥
Sursa 中发生某件事时启动工作流	从 Sursa 发出	一个指向该平台的 Webhook

无论使用哪个平台，都请把密钥保存在平台的凭据或连接存储中，而不是写在步骤里，以免密钥被复制到每个场景和运行日志中。

把记录作为卡片推送

在 Sursa 中创建一个自定义数据源（Sources → New source → Custom source），然后在数据源页面的 API keys 区块中为它创建密钥。该密钥以 kbsrc_ 开头，只能向这个数据源写入文档，因此适合保存在第三方平台上。

常见的设置是“X 中创建或更新记录时，把它发送到 Sursa”：

设置	值
方法	`POST`
URL	`https://api.example.com/v1/push/sources/42/documents`
请求头 `Authorization`	`Bearer kbsrc_…`
请求头 `Content-Type`	`application/json`
正文	下面的 JSON，字段从触发器映射而来

{
  "external_id": "{{record_id}}",
  "title": "{{record_title}}",
  "content": "{{record_body_html}}",
  "content_type": "html",
  "url": "{{record_link}}",
  "path": "{{record_category}}",
  "updated_at": "{{record_updated_at}}"
}

把记录的稳定 ID 映射到 external_id，绝不要用时间或运行编号。这样再次发送同一条记录时会更新同一张卡片，步骤重试也不会造成影响：响应为 unchanged。
对于“记录已删除”触发器，另建一个工作流，Method 为 DELETE，URL 为 https://api.example.com/v1/push/sources/42/documents/{{record_id}}。
用 GET https://api.example.com/v1/push/sources/42 和同样的 Authorization 头测试连接。它返回数据源的名称及其文档数量。

文档字段与编写代码时相同。

Zapier

使用 Webhooks by Zapier → Custom Request：

Method：POST。
URL：https://api.example.com/v1/push/sources/42/documents。
Data Pass-Through：关闭。Data：上面的 JSON，字段从触发器中插入。
Headers：Authorization = Bearer kbsrc_…，Content-Type = application/json。

Make

使用 HTTP → Make a request 模块：

Method 为 POST，URL 同上，Headers 为 Authorization: Bearer kbsrc_…。
Body type 选 Raw，Content type 选 JSON (application/json)，Request content 填上面的 JSON，并映射各个值。
打开 Parse response，以便在后续模块中使用 result（created、updated、unchanged）。
要发送文件，Body type 选 Multipart/form-data，添加一个 file 字段（来自前面模块的文件）和一个 document 文本字段，其中放不含 content 的 JSON 字段。

n8n

使用 HTTP Request 节点：

Method 为 POST，URL 同上。
Authentication 选 Generic Credential Type → Header Auth，名称为 Authorization，值为 Bearer kbsrc_…。
打开 Send Body，Body Content Type 选 JSON，字段用 {{ $json.id }} 这样的表达式映射。

对于定时的全量导出，串联三个 HTTP Request 节点：打开同步（POST …/syncs，第一次用 {"type": "initial"}，之后用 {"type": "incremental"}），推送各项，然后用 {"status": "complete"} 关闭同步。n8n 对每一项运行一次节点；要减少请求数，用 Aggregate 节点把各项分组，以 {"sync_number": …, "documents": [...]} 的形式发送到 …/documents/batch。

在工作流中提问

工作流可以向 Sursa 提问并使用回答：起草工单回复、补充 CRM 记录的信息、在聊天频道中发布回答。请使用具有 ask 权限范围、且角色能看到相应合集的组织 API 密钥。

设置	值
方法	`POST`
URL	`https://api.example.com/v1/ask`
请求头 `Authorization`	`Bearer kb_…`
正文	`{"query": "{{ticket_subject}}: {{ticket_body}}", "collection": "support"}`

响应的 answer 中是回答（Markdown），sources 中是来源，每个来源都带有 doc_name。知识库中没有与问题相关的内容时，会设置 empty（例如 no_hits）：请添加一个筛选步骤，以免工作流发布空回答。参见构建问答机器人。

回答可能需要几秒钟。如果平台 HTTP 步骤的默认超时较短，请调到至少 60 秒。

由 Sursa 事件启动工作流

每个平台都能接收 Webhook：

平台	触发器
Zapier	Webhooks by Zapier → Catch Raw Hook（选 raw，请求体会保持发送时的原样）
Make	Webhooks → Custom webhook 模块
n8n	Webhook 节点，方法为 `POST`

创建触发器，复制它提供的 HTTPS 地址。
在 Sursa 的 Administration → Integrations → Webhooks and API 中，或者通过 POST /v1/webhooks，用该地址和所需的事件登记 Webhook。
从 Webhook 页面发送一个测试事件，并在后续步骤中映射事件的字段（type、data.card.title……）。

检查签名。触发器地址是公开的：任何知道该地址的人都可以向它发送请求。在根据投递执行操作之前，请先验证其签名，工作流会更改数据时尤其如此：

在 n8n 中，在 Webhook 节点之后添加一个 Code 节点，放入接收 Webhook 中的 Node.js 签名验证代码，并打开 Webhook 节点的原始请求体选项，以便获取确切的字节。
在 Zapier 和 Make 中，原始请求体较难获取，至少要对地址保密、按 type 筛选，并在执行操作之前通过 API 重新读取对象。

与任何接收端一样，平台上也会有重试和重复投递：如果重复运行会造成问题，请按事件的 id 筛选。

提示

遇到 429 时，让平台的自动重试等待 Retry-After 秒数。大批量导出请优先使用批次。
平台会记录每个请求和响应。绝不要把密钥放进 URL；只要工作流只写入文档，就优先使用 kbsrc_ 密钥。
如果某个步骤因 401 sources.push_key_invalid 失败，请检查 URL 中的数据源 ID 是否与密钥匹配。