Zapier Make และ n8n

แพลตฟอร์มเชื่อมต่อระบบเชื่อม Sursa เข้ากับเครื่องมืออื่นนับร้อยได้โดยไม่ต้องเขียนโค้ด โดยไม่ต้องมีแอปเฉพาะของ Sursa เพราะขั้นตอนคำขอ HTTP และเว็บฮุกทั่วไปของแพลตฟอร์มเหล่านี้ทำงานกับ API ได้โดยตรง คู่มือนี้ครอบคลุมสูตรที่ใช้บ่อยที่สุดสามแบบ:

ไม่ว่าจะใช้แพลตฟอร์มใด ให้เก็บคีย์ไว้ในที่เก็บข้อมูลรับรองหรือการเชื่อมต่อของแพลตฟอร์ม ไม่ใช่ในตัวขั้นตอน เพื่อไม่ให้คีย์ถูกคัดลอกไปอยู่ในทุกสถานการณ์และทุกล็อกการรัน

ส่งรายการเป็นการ์ด

สร้างแหล่งข้อมูลแบบกำหนดเองใน Sursa (Sources → New source → Custom source (แหล่งข้อมูล → แหล่งข้อมูลใหม่ → แหล่งข้อมูลแบบกำหนดเอง)) แล้วสร้างคีย์ของแหล่งข้อมูลนั้นในหน้าแหล่งข้อมูลที่ส่วน API keys (คีย์ API) คีย์ขึ้นต้นด้วย kbsrc_ และเขียนเอกสารได้เฉพาะในแหล่งข้อมูลนี้ จึงเป็นคีย์ที่เหมาะสำหรับเก็บไว้บนแพลตฟอร์มของบุคคลภายนอก

การตั้งค่าที่พบบ่อยคือ “เมื่อมีการสร้างหรืออัปเดตรายการใน X ให้ส่งรายการนั้นไปยัง Sursa”:

{
  "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
• สำหรับทริกเกอร์ “ลบรายการแล้ว” ให้เพิ่มเวิร์กโฟลว์ที่สองที่ใช้เมธอด 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 ที่มีฟิลด์ JSON ทั้งหมดยกเว้น content

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 แล้วส่งไปยัง …/documents/batch ในรูป {"sync_number": …, "documents": [...]}

ถามคำถามในเวิร์กโฟลว์

เวิร์กโฟลว์ถาม Sursa และนำคำตอบไปใช้ได้ เช่น ร่างคำตอบให้ทิกเก็ตของฝ่ายสนับสนุน เพิ่มข้อมูลให้รายการใน CRM หรือโพสต์คำตอบในช่องแชต ให้ใช้คีย์ API ขององค์กรที่มีขอบเขตสิทธิ์ ask และบทบาทที่มองเห็นคอลเลกชันที่ถูกต้อง

การตอบกลับมีคำตอบอยู่ใน answer (Markdown) และแหล่งที่มาอยู่ใน sources แต่ละรายการมี doc_name เมื่อฐานความรู้ไม่มีข้อมูลเกี่ยวกับคำถามนั้น ระบบจะตั้งค่า empty (เช่น no_hits) ให้เพิ่มขั้นตอนตัวกรองเพื่อไม่ให้เวิร์กโฟลว์โพสต์คำตอบว่าง ดู สร้างบอตถาม-ตอบ

คำตอบอาจใช้เวลาหลายวินาที หากขั้นตอน HTTP ของแพลตฟอร์มมีค่าหมดเวลาเริ่มต้นที่สั้น ให้เพิ่มเป็นอย่างน้อย 60 วินาที

เริ่มเวิร์กโฟลว์จากอีเวนต์ของ Sursa

ทุกแพลตฟอร์มรับเว็บฮุกได้:

1. สร้างทริกเกอร์และคัดลอกที่อยู่ HTTPS ที่ได้รับ
2. ใน Sursa ให้ลงทะเบียนเว็บฮุกด้วยที่อยู่นั้นและอีเวนต์ที่ต้องการ ที่ Administration → Integrations → Webhooks and API (การดูแลระบบ → การเชื่อมต่อระบบ → เว็บฮุก) หรือด้วย POST /v1/webhooks
3. ส่งอีเวนต์ทดสอบจากหน้าเว็บฮุก แล้วจับคู่ฟิลด์ของอีเวนต์ (type data.card.title …) ในขั้นตอนถัดไป

ตรวจลายเซ็น ที่อยู่ของทริกเกอร์เป็นที่อยู่สาธารณะ ใครก็ตามที่รู้ที่อยู่นี้ส่งคำขอมาได้ ให้ตรวจลายเซ็นของการส่งแต่ละครั้งก่อนดำเนินการ โดยเฉพาะเมื่อเวิร์กโฟลว์เปลี่ยนแปลงข้อมูล:

• ใน n8n ให้เพิ่มโหนด Code ต่อจากโหนด Webhook พร้อมโค้ดตรวจลายเซ็นสำหรับ Node.js จาก รับเว็บฮุก และเปิดตัวเลือกเนื้อหาแบบดิบของโหนด Webhook เพื่อให้ได้ไบต์ตรงตามที่ส่งมา
• ใน Zapier และ Make ซึ่งเข้าถึงเนื้อหาแบบดิบได้ยากกว่า อย่างน้อยให้เก็บที่อยู่เป็นความลับ กรองตาม type และอ่านออบเจ็กต์ใหม่จาก API ก่อนดำเนินการ

การลองใหม่และการส่งซ้ำมีผลกับแพลตฟอร์มเช่นเดียวกับเซิร์ฟเวอร์ผู้รับทั่วไป ให้กรองตาม id ของอีเวนต์หากการรันซ้ำจะก่อความเสียหาย

เคล็ดลับ

• เมื่อได้ 429 ให้ระบบลองใหม่อัตโนมัติของแพลตฟอร์มรอตามจำนวนวินาทีใน Retry-After สำหรับการส่งออกขนาดใหญ่ ให้ใช้แบบชุด
• แพลตฟอร์มบันทึกทุกคำขอและการตอบกลับไว้ในล็อก ห้ามใส่คีย์ใน URL และใช้คีย์ kbsrc_ ทุกครั้งที่เวิร์กโฟลว์มีหน้าที่เพียงเขียนเอกสาร
• หากขั้นตอนล้มเหลวด้วย 401 sources.push_key_invalid ให้ตรวจว่า ID ของแหล่งข้อมูลใน URL ตรงกับคีย์