ربط العناصر المخصّصة للمطوّرين

هذه الصفحة مخصّصة للمطوّرين الذين يربطون نظام الشركة الخلفي بـ Skava. يتم شرح كيفية إنشاء عنصر واجهة برمجة التطبيقات ونشره في صفحة العناصر المخصّصة: واجهات برمجة التطبيقات، بينما نغطي هنا كل ما يجب حدوثه في الطرف الآخر من الاتصال.

الفكرة في جملة واحدة: Skava لا تعرف نطاق عملك. هي تعرف تنسيقاً واحداً فقط، وهو البطاقة. أنت تقرر ما تحتويه، ونحن نتحقق فقط من الشكل والحجم والسلامة. طلب مواد بناء هو مثال واحد؛ الشركة التالية تجمع ملاحظات المستخدمين، والشركة التي تليها ترفع صورة لموقع العمل في سجلاتها الخاصة.

نظرة عامة على سير العمل

1. ينشئ مسؤول الشركة عنصراً لواجهة برمجة التطبيقات في Skava: نموذج بالإضافة إلى عنوان نظامك الخلفي، والطريقة، والرمز المميز.
2. يملأ أحد الأشخاص في الدردشة النموذج ويرسله.
3. تستدعي Skava واجهة الخلفية الخاصة بك وترسل القيم المُدخلة بصيغة JSON.
4. تصبح إجابتك بطاقة في الدردشة.
5. اختياريًا، يمكنك الإبلاغ عن حالات جديدة لاحقًا عبر الاستدعاء العكسي. يصبح كل تقرير بطاقة أخرى، وتبقى البطاقة السابقة كما هي.

المتطلبات الخاصة بواجهة الخلفية

• HTTPS. يُقبل https:// فقط، دون http، ودون بيانات اعتماد في العنوان، وبحد أقصى 2000 حرف.
• قابل للوصول العام. يجب أن يُحلّ المضيف إلى عناوين IP عامة حصرياً. تُرفض localhost والشبكات الخاصة والعناوين المحلية وبيانات السحابة، ويُتحقق من ذلك في كل استدعاء.
• عنوان ثابت. تحلّ Skava المضيف مرة واحدة وتثبّت الاتصال على ذلك العنوان. لا يؤثر تغيير DNS أثناء الاتصال.
• بدون إعادة توجيه. يُعدّ التوجيه 301 إلى العنوان "الصحيح" فشلاً. أدخل العنوان النهائي مباشرة.
• زمن الاستجابة. يمكن ضبط مهلة الانتظار لكل عنصر، بحد أقصى صارم 30 ثانية. إذا احتجت وقتاً أطول، أجب فوراً وأبلغ عن النتيجة لاحقاً عبر الاستدعاء العكسي.
• حجم الاستجابة. تقرأ Skava ما يصل إلى 256 كيبايت كحد أقصى.
• نوع المحتوى. يتم تحليل الجسم فقط إذا كان application/json.

الطلب الذي يصل إليك

الطريقة هي GET أو POST أو PUT أو PATCH، وذلك حسب العنصر. مع POST وPUT وPATCH تصل القيم كجسم JSON، ومع GET تصل كمتغيرات استعلام.

المصادقة هي رأس واحد يُحدد اسمه وبداية قيمته في إعدادات العنصر، وعادةً ما يكون Authorization مع بادئة Bearer . يتم تخزين الرمز المشفر لدينا. لا يمكن تعيين الرؤوس host وcontent-length وcontent-type وcookie وaccept-encoding.

الجسم هو كائن مسطّح. يختار من بنى العنصر المفاتيح، ولا يظهر التداخل إلا حيث أضافوا جدولاً أو منتقي منتجات:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

ثلاثة مفاتيح تأتي دائماً منّا، لذا لا تستخدمها بنفسك:

• locale: رمز لغة المستخدم. أجب بهذه اللغة؛ نحن لا نترجم نصوصك.
• callback_url وcallback_token: الاستدعاء لهذا التفاعل الواحد، راجع أدناه. لا تكون موجودة إلا عندما يأتي الطلب من محادثة.

تُملأ حقول السياق مثل الاسم والشركة والمهمة والمحادثة الفرعية من الخادم نفسه، مستمدة من القناة التي تم تشغيل العنصر فيها. لا يمكن لعميل مُعدّل أن يدّعي اسم مهمة مختلف هناك.

الاستجابة: تنسيق البطاقة

أجب باستخدام 2xx وكائن card. هذا بالضبط ما يظهر كبطاقة في الدردشة:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

• v (إلزامي): العدد الصحيح 1. إذا كُتب كنص ("1") فسيُرفض. وبدونه، لا تُحتسب الإجابة كبطاقة، وتُطبَّق خريطة الاستجابة المُهيأة في العنصر.
• title: عنوان البطاقة.
• state: اللون وأيقونة النغمة فقط، واحدة من ok، pending، warn، error. القيمة غير المعروفة تعود إلى ok وستحصل على تلميح.
• status_text: نص حر لا نقوم بتفسيره. يظهر في أعلى البطاقة، كما يظهر في قائمة الدردشات وفي إشعارات الدفع.
• الحقول: قائمة من label وvalue. بحد أقصى 20 عنصراً، label 80 حرفاً، value 200 حرفاً، وtitle وstatus_text 120 حرفاً لكل منهما. القيم الطويلة جداً تُختصر ولا تُرفض: يجب ألا يفشل الطلب بسبب تفصيل بسيط.
• icon: راجع ما يلي.

ما تفعله Skava بنصوصك قبل وصولها إلى الدردشة: يتم حذف الأسطر الفارغة والرموز الضابطة (لأن حرفًا من اليمين إلى اليسار قد يقلب عرض المبلغ)، واستبدال علامات الـ backticks، وتعطيل أي نص يبدأ بـ [SKAVA:. يمنع هذا الأخير قراءة قيمة بطاقة كعنصر دردشة مختلف، مثل طلب دفع.

لا يمكن تعيين الروابط في الحقول أو في HTML أو في الصور. الدردشة بيئة موثوقة، وعنوان قابل للنقر من خادم خلفي خارجي سيكون دعوة لإعادة بناء صفحة تسجيل الدخول.

مدخلات المستخدم تخص الخادم: تظهر في البطاقة الأولى ولا يمكنك تجاوزها. في الدردشة، تُعدّ سجلاً لما تم إرساله فعلياً.

الأيقونات

باستخدام icon تحصل البطاقة على علامتها الخاصة في الترويسة. طريقتان:

اسم من المجموعة المدمجة: package، package-check، package-open، box، boxes، truck، forklift، warehouse، settings، cog، gauge، wrench، hammer، drill، hard-hat، ruler، paint-roller، construction، clipboard-check، receipt، file-text، camera، clock، calendar-clock، circle-check، circle-alert، triangle-alert، send، mail-check، shopping-cart، credit-card، map-pin.

أو SVG خاص بك كنص. من هذا النص تأخذ Skava الهندسة فقط (path، circle، ellipse، rect، line، polyline، polygon مع سماتها الرقمية) وتبني صورتها الخاصة. تُستبعد السكربتات والأنماط والمراجع الخارجية وforeignObject وسمات الأحداث؛ يؤدي وجود نوع مستند أو كيان إلى الرفض؛ قد يصل حجم الملف إلى 8 KiB كحد أقصى ويحتوي على 16 شكلاً كحد أقصى. اللون وسماكة الخط والحجم يحددها Skava، لذا لا يمكن للأيقونة أن تتخفى كعنصر تحكم. اعمل على شبكة 24 في 24.

بدون icon يبقى العلام الافتراضي.

الدالة الاستدعائية: الإبلاغ عن حالات لاحقة

تحتوي الاستدعاء على callback_url وcallback_token. استخدمهما للإبلاغ عن حالات جديدة لاحقاً:

POST <callback_url> مع Authorization: Bearer <callback_token> وContent-Type: application/json، بحجم جسم لا يتجاوز 32 كيبايت:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

بالإضافة إلى البطاقة، هناك ثلاثة قيم اختيارية:

• seq: عدّاد خاص بك. يتم تجاهل التقرير الذي يحمل قيمة أصغر أو مساوية، حتى لا يتجاوز تقريران بعضهما. في حال عدم وجود seq، يكون التقرير الأخير الوارد هو المعتمد.
• final: يُغلق التفاعل. يصبح الرمز غير صالح ولا تظهر بطاقات إضافية. يُسمح به أيضاً في الإجابة الأولى، للتدفقات التي لا تتضمن متابعة.
• notify: اضبطه على false لنشر البطاقة بهدوء، دون عدّاد غير مقروء ودون إشعار. مناسب للخطوات الوسيطة التي لا ينبغي أن توقظ أحداً. بدونه، تكون البطاقة رسالة عادية تماماً.

كل تقرير يصبح بطاقته المستقلة في الدردشة، وتبقى البطاقة السابقة. هذا يجعل من السهل قراءة الحالة المُبلَّغ عنها. ومن هنا نوصي بإرسال ما تغيّر فقط. البطاقة التي تكرر رقم الطلب والبنود والمجموع للمرة الرابعة هي مجرد ضجيج للقارئ.

حدّان: إرسال التقرير نفسه مرتين لا ينتج بطاقة ثانية، ولا يمكن للتفاعل نشر أكثر من 50 بطاقة. يقبل التفاعل التقارير لمدة 90 يوماً.

الردود التي يجب أن تستجيب لها

• 200 مع {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. اقرأ التلميحات: فهي توضح ما تم اختصاره أو حذفه.
• 401: رمز غير صحيح أو معرف تفاعل خاطئ. لا تعيد المحاولة.
• 410: التفاعل مغلق أو منتهي الصلاحية. لا تعيد المحاولة.
• 422: البطاقة غير قابلة للاستخدام، مع hints كسبب. أصلحها أولاً.
• 400 JSON تالف، 413 حجم كبير جداً، 429 عدد كبير من الطلبات (أعد المحاولة مع تأخير تدريجي)، 500 خطأ من جانبنا، أعد المحاولة لاحقاً.

مثال 1: طلب مع سجل حالة

الخطوة 1، الطلب إلى خادمك الخلفي:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

الخطوة 2، ردك الفوري:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

يعرض الدردشة الآن بطاقة بأيقونة حزمة، والحالة، ومدخلات المستخدم.

الخطوة 3، لاحقًا أثناء الاختيار:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

بطاقة ثانية هادئة بدون حقول: تغيّر الحالة فقط.

الخطوة 4، عند الشحن:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

قد توقظ هذه البطاقة شخصًا ما، لذا لا يوجد notify: false.

الخطوة 5، عند التسليم:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

عند استخدام final تُغلق التفاعل ولا يعمل الرمز بعد الآن.

مثال 2: إجراء بدون متابعة

ليس كل تدفق له سجل. العنصر الذي يحتوي على حقل واحد فقط ويُسلم شيئًا إلى نظامك يحتاج إلى إجابة واحدة فقط:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

final: true مهم هنا: وإلا سيبقى التفاعل مفتوحًا لمدة 90 يومًا برمز صالح حتى لو لم تعد ترفع أي تقارير بعد الآن.

منتقي المنتجات من الكتالوج

بعد أن تقوم الشركة برفع كتالوج منتجاتها، يمكن أن يحتوي العنصر على كتلة منتقي المنتجات. يقوم المستخدم بتجميع سلة مشتريات منها، وتصلك القائمة تحت المفتاح الذي اختاره من بنى العنصر:

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

بما أن المفتاح حر، ابحث عن أول قائمة بهذا الشكل بدلاً من البحث عن اسم ثابت. قبل الإرسال، تتحقق Skava من أن كل رقم موجود فعلياً في كتالوج تلك الشركة، بحد أقصى 50 عنصراً. تظهر العناصر في البطاقة كقائمة تحتوي على صورة المنتج واسمه وكميته.

الاختبار

• أرسل Ping في محرر العنصر يرسل طلب HEAD بسيطاً بدون رمز وبدون بيانات. رد بأي شيء؛ أي رد HTTP يُعدّ العنصر متاحاً.
• طلب الاختبار يطلق استدعاءً حقيقياً بقيم تجريبية، حتى لو كان العنصر مسودة، ويعرض الطلب والاستجابة ورسائل مُتحقق البطاقة.
• معاينة في التبويب المجاور: الصق استجابة JSON الخاصة بك، وتحقق منها، وستظهر لك البطاقة النهائية مع التلميحات. يتم التحقق منها على الخادم باستخدام نفس الكود المستخدم في بيئة الإنتاج.
• خادم مثال: يعمل مزوّد مثال كامل على api.skava.io ويستخدم كل ما تم وصفه أعلاه. يقع مصدره في المستودع تحت example_order_server/، ويضم حوالي 600 سطر من مكتبة القياسية البحتة، وهو مصمم ليتم نسخه.

ما الذي يجب أن تعرفه أيضاً

• البطاقة هي رسالة دردشة عادية تماماً. تظهر في البحث، ويمكن اقتباسها وتبقى في السجل.
• تُرسل من قبل المرسل النظامي، وليس من حساب تابع لشركتك. ومع ذلك، تظهر على جانب الشخص الذي نفّذ العنصر، ويذكر العنوان من هو النظام الذي يكتب.
• يُحدَّد من يمكنه تشغيل العنصر على العنصر نفسه: أعضاء الشركة فقط، أو أيضًا أشخاص خارجيون يشاركون في محادثة معه. عند مغادرة شركتك للمحادثة، تنتهي الإذن تلقائيًا.
• عنصر واجهة برمجية (API) برمز وصول منتهي الصلاحية يكون خاملًا: التطبيقات الحالية تخفيه من القائمة، وأي استدعاء يُرسل على أي حال يُرفض من جانب الخادم. يخزّن المسؤول رمز وصول جديدًا له، ويعمل ذلك أيضًا على واجهة منشورة.

عناصر ذات صلة

الإنشاء والنشر: العناصر المخصصة: واجهات API. مستندات قابلة للتعبئة بدلًا من الواجهات: العناصر المخصصة: المستندات.