منصات 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}}"
}

• اربط معرّفًا ثابتًا للسجل بالحقل 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 يحمل حقول 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 (الإدارة ← التكاملات ← خطافات الويب و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، فتحقّق من أن معرّف المصدر في عنوان URL يطابق المفتاح.