هذه الصفحة مخصصة للمطورين الذين يربطون الواجهة الخلفية لشركة بـ Skava. كيفية إنشاء وإطلاق عنصر واجهة برمجة التطبيقات (API) موضحة في واجهات برمجة تطبيقات العناصر المخصصة؛ هنا نغطي كل ما يجب أن يحدث في الطرف الآخر من الخط.

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

التدفق على النظرة العامة

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

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

• HTTPS. فقط https://، لا http، لا توجد بيانات اعتماد في العنوان، بحد أقصى 2000 حرف.
• يمكن الوصول إليه علنًا. يجب أن يحل المضيف حصريًا إلى عناوين IP عامة. يتم رفض الخادم المحلي والشبكات الخاصة والشبكات المحلية وبيانات التعريف السحابية، ويتم التحقق من ذلك في كل مكالمة.
• عنوان ثابت. تحل Skava اسم المضيف مرة واحدة وتثبت الاتصال بهذا عنوان IP. لا يؤثر تغيير 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: نص حر لا نقوم بتفسيره. يظهر في أعلى البطاقة وهو أيضًا ما يظهر في قائمة الدردشة وفي إشعار دفع.
• fields: قائمة بـ label و value. بحد أقصى 20 إدخالاً، label 80 حرفًا، value 200، title و status_text 120 لكل منهما. يتم اختصار القيم الطويلة جدًا وليس رفضها: يجب ألا تفشل عملية الطلب بسبب تفصيل.
• icon: انظر أدناه.

ما تفعله Skava بنصوصك قبل وصولها إلى الدردشة: تتم إزالة الأسطر الجديدة وأحرف التحكم (قد يؤدي حرف من اليمين إلى اليسار إلى عكس عرض مبلغ)، ويتم استبدال علامات الباك تيك، وأي شيء يبدأ بـ [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 كيلوبايت ويحتوي على 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": "طلب BST-10001", "state": "pending", "status_text": "تم استلام الطلب", "icon": "package", "fields": [{"label": "رقم الطلب", "value": "BST-10001"}, {"label": "متوقع", "value": "14/08/2026"}]}}

الآن يظهر في الدردشة بطاقة تحتوي على رمز علبة، والحالة، ومدخلات المستخدم.

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

POST <callback_url> إلى {"card": {"v": 1, "title": "طلب BST-10001", "state": "pending", "status_text": "جاري الاستلام", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

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

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

POST <callback_url> إلى {"card": {"v": 1, "title": "طلب BST-10001", "state": "pending", "status_text": "تم الشحن", "icon": "truck", "fields": [{"label": "رقم التتبع", "value": "DPD123456789"}, {"label": "الناقل", "value": "DPD"}]}, "seq": 3}

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

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

POST <callback_url> إلى {"card": {"v": 1, "title": "طلب BST-10001", "state": "ok", "status_text": "تم التسليم", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

مع final يتم إغلاق التفاعل ولا يعمل الرمز المميز بعد ذلك.

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

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

{"card": {"v": 1, "title": "تم التسجيل", "state": "ok", "status_text": "تم التخزين ضمن المشروع 4711", "icon": "clipboard-check", "fields": [{"label": "القضية", "value": "4711"}]}, "final": true}

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

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

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

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

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

الاختبار

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

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

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

ذات صلة

إنشاء وإطلاق: Custom Elements: API interfaces. مستندات قابلة للتعبئة بدلاً من الواجهات: Custom Elements: Documents.