Zapier, Make và n8n

Các nền tảng tích hợp kết nối Sursa với hàng trăm công cụ khác mà không cần viết mã. Chúng không cần một ứng dụng Sursa riêng: các bước yêu cầu HTTP và webhook thông dụng của chúng làm việc trực tiếp với API. Hướng dẫn này trình bày ba công thức phổ biến nhất:

Công thức	Chiều	Bạn cần gì
Đẩy bản ghi từ công cụ khác vào Sursa thành thẻ	Vào Sursa	Một nguồn tùy chỉnh và khóa `kbsrc_` của nó
Đặt câu hỏi cho Sursa trong một quy trình tự động	Vào Sursa và quay lại	Khóa API có phạm vi quyền `ask`
Khởi chạy quy trình tự động khi có điều gì xảy ra trong Sursa	Từ Sursa ra ngoài	Một webhook trỏ tới nền tảng

Dù bạn dùng nền tảng nào, hãy giữ khóa trong kho thông tin xác thực hoặc kho kết nối của nền tảng, không phải trong chính bước đó, để khóa không bị sao chép vào mọi kịch bản và nhật ký chạy.

Đẩy bản ghi thành thẻ

Tạo một nguồn tùy chỉnh trong Sursa (Sources → New source → Custom source, Nguồn → Nguồn mới → Nguồn tùy chỉnh), sau đó tạo khóa cho nguồn trên trang của nó tại API keys (khóa API của nguồn). Khóa bắt đầu bằng kbsrc_ và chỉ có thể ghi tài liệu vào nguồn này, nên đây là khóa phù hợp để lưu trên nền tảng của bên thứ ba.

Thiết lập thường gặp là “khi một bản ghi được tạo hoặc cập nhật trong X, hãy gửi nó tới Sursa”:

Thiết lập	Giá trị
Phương thức	`POST`
URL	`https://api.example.com/v1/push/sources/42/documents`
Header `Authorization`	`Bearer kbsrc_…`
Header `Content-Type`	`application/json`
Phần thân	JSON dưới đây, với các trường được ánh xạ từ trình kích hoạt

{
  "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}}"
}

Ánh xạ một ID ổn định của bản ghi vào external_id, không bao giờ dùng thời gian hay số thứ tự lần chạy. Khi đó, gửi lại cùng bản ghi sẽ cập nhật cùng một thẻ, và bước được thử lại không gây hại: câu trả lời là unchanged.
Với trình kích hoạt “bản ghi bị xóa”, hãy thêm quy trình tự động thứ hai với Method DELETE và URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
Kiểm tra kết nối bằng GET https://api.example.com/v1/push/sources/42 với cùng header Authorization. Yêu cầu này trả về tên của nguồn và số tài liệu của nó.

Các trường của tài liệu giống như khi dùng mã.

Zapier

Dùng Webhooks by Zapier → Custom Request:

Method: POST.
URL: https://api.example.com/v1/push/sources/42/documents.
Data Pass-Through: tắt. Data: JSON ở trên, với các trường được chèn từ trình kích hoạt.
Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Dùng mô-đun HTTP → Make a request:

Method POST, URL như trên, Headers Authorization: Bearer kbsrc_….
Body type Raw, Content type JSON (application/json), Request content: JSON ở trên với các giá trị được ánh xạ.
Bật Parse response để dùng result (created, updated, unchanged) trong các mô-đun sau.
Để gửi tệp, hãy chọn Body type Multipart/form-data với một trường file (tệp từ mô-đun trước) và một trường văn bản document chứa các trường JSON không có content.

n8n

Dùng nút HTTP Request:

Method POST, URL như trên.
Authentication Generic Credential Type → Header Auth, với tên Authorization và giá trị Bearer kbsrc_….
Bật Send Body, Body Content Type JSON, các trường được ánh xạ bằng biểu thức như {{ $json.id }}.

Với lượt xuất toàn bộ theo lịch, hãy nối ba nút HTTP Request: mở một phiên đồng bộ (POST …/syncs với {"type": "initial"} ở lần đầu, {"type": "incremental"} ở các lần sau), đẩy các phần tử, và đóng phiên đồng bộ với {"status": "complete"}. n8n chạy một nút một lần cho mỗi phần tử; để gửi ít yêu cầu hơn, hãy gom các phần tử bằng một nút Aggregate và gửi chúng tới …/documents/batch dưới dạng {"sync_number": …, "documents": [...]}.

Đặt câu hỏi trong quy trình tự động

Một quy trình tự động có thể hỏi Sursa và dùng câu trả lời: soạn bản nháp trả lời phiếu hỗ trợ, bổ sung thông tin cho bản ghi CRM, đăng câu trả lời lên một kênh trò chuyện. Hãy dùng khóa API của tổ chức có phạm vi quyền ask và vai trò nhìn thấy đúng các bộ sưu tập cần thiết.

Thiết lập	Giá trị
Phương thức	`POST`
URL	`https://api.example.com/v1/ask`
Header `Authorization`	`Bearer kb_…`
Phần thân	`{"query": "{{ticket_subject}}: {{ticket_body}}", "collection": "support"}`

Phản hồi chứa câu trả lời trong answer (Markdown) và các nguồn của nó trong sources, mỗi nguồn có doc_name. Khi cơ sở tri thức không có gì về câu hỏi, empty được đặt (ví dụ no_hits): hãy thêm một bước lọc để quy trình tự động không đăng câu trả lời trống. Xem Xây dựng bot hỏi đáp.

Câu trả lời có thể mất vài giây. Nếu bước HTTP của nền tảng có thời gian chờ mặc định ngắn, hãy tăng lên ít nhất 60 giây.

Khởi chạy quy trình tự động từ sự kiện Sursa

Mọi nền tảng đều có thể nhận webhook:

Nền tảng	Trình kích hoạt
Zapier	Webhooks by Zapier → Catch Raw Hook (dạng thô, để phần thân giữ nguyên như khi được gửi)
Make	Mô-đun Webhooks → Custom webhook
n8n	Nút Webhook, phương thức `POST`

Tạo trình kích hoạt và sao chép địa chỉ HTTPS mà nó cung cấp.
Trong Sursa, đăng ký một webhook với địa chỉ đó và các sự kiện bạn muốn, tại Administration → Integrations → Webhooks and API (Quản trị → Tích hợp → Webhook và API) hoặc bằng POST /v1/webhooks.
Gửi một sự kiện thử từ trang webhook, và ánh xạ các trường của sự kiện (type, data.card.title, …) trong các bước tiếp theo.

Kiểm tra chữ ký. Địa chỉ của trình kích hoạt là công khai: bất kỳ ai biết nó đều có thể gửi yêu cầu tới đó. Hãy xác minh chữ ký của từng lần gửi trước khi xử lý, đặc biệt nếu quy trình tự động thay đổi dữ liệu:

Trong n8n, thêm một nút Code sau nút Webhook với đoạn mã xác minh Node.js từ Nhận webhook, và bật tùy chọn phần thân thô của nút Webhook để có được chính xác các byte nhận được.
Trong Zapier và Make, nơi khó lấy phần thân thô hơn, ít nhất hãy giữ bí mật địa chỉ, lọc theo type, và đọc lại đối tượng từ API trước khi xử lý.

Việc thử lại và trùng lặp áp dụng cho các nền tảng như cho mọi máy chủ nhận: hãy lọc theo id của sự kiện nếu một lần chạy trùng lặp có thể gây hại.

Mẹo

Khi gặp 429, hãy để cơ chế tự động thử lại của nền tảng chờ đủ số giây trong Retry-After. Với lượt xuất lớn, hãy ưu tiên gửi theo lô.
Các nền tảng ghi nhật ký mọi yêu cầu và phản hồi. Không bao giờ đặt khóa trong URL, và hãy ưu tiên khóa kbsrc_ ở bất cứ đâu mà quy trình tự động chỉ ghi tài liệu.
Nếu một bước thất bại với 401 sources.push_key_invalid, hãy kiểm tra rằng ID nguồn trong URL khớp với khóa.