العناصر المخصصة: API

واجهة API هي نموذج ترسل Skava قيمه المعبأة بصيغة JSON إلى عنوان تحدده أنت (الخادم الخلفي الخاص بك). بهذه الطريقة تربط Skava بأنظمتك الخاصة بأمان.

إعداد واجهة API

تتكون الواجهة من حقول إدخال (وهي التي تشكل JSON) ومن عنوان الوجهة ومن المصادقة.

1. أنشئ الحقول: كل حقل يحصل على مفتاح JSON. على اليسار ترى مباشرة معاينة JSON التي ترسل بهذا الشكل تماما إلى خادمك الخلفي.
2. العنوان (URL): عنوان https:// الخاص بخادمك الخلفي. لا يسمح إلا بعناوين HTTPS المتاحة للعموم (انظر قسم الأمان أدناه).
3. الطريقة: POST (الافتراضية) أو PUT أو PATCH أو GET. مع GET تضاف القيم إلى العنوان كمعاملات بدلا من إرسالها في جسم الطلب.
4. المصادقة: حدد اسم الترويسة (مثل Authorization) وبادئة القيمة (مثل Bearer )، ثم احفظ الرمز المميز. ويمكنك اختياريا تحديد تاريخ انتهاء صلاحيته.
5. حقول الرد (اختياري): حدد بالمسار أي القيم من رد الخادم الخلفي تعرض، مثل order.id أو items[0].sku.
6. تحقق باستخدام Ping وTest Request، ثم اضغط نشر.

حفظ الرمز المميز بأمان

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

الاختبار: Ping وTest Request

• Ping هو فحص خفيف لإمكانية الوصول. يتحقق فقط مما إذا كان عنوانك يستجيب، ولا يرسل أثناء ذلك لا الرمز المميز ولا بيانات النموذج. يظهر إمكانية الوصول والحالة وزمن الاستجابة. مثالي كخطوة أولى.
• Test Request هو التجربة الحقيقية: يرسل إلى عنوانك بيانات نموذجية مع الرمز المميز ويعرض لك الرد الكامل إضافة إلى حقول الرد المستخرجة.

بصفتك مسؤولا يمكنك تشغيل الاثنين والواجهة ما زالت مسودة، لتتحقق من الربط قبل النشر.

المسودة والنشر

كل واجهة تبدأ مسودة ويمكن تعديلها بحرية. وحين يصبح كل شيء جاهزا تنشرها بزر نشر.

الأمان

كيف يستخدم الفريق واجهة منشورة

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

1. في الدردشة اضغط زر الجمع في الأسفل واختر عنصرا مخصصا.
2. اختر من القائمة القالب أو الواجهة المطلوبة.
3. عبئ النموذج ثم اضغط إرسال.
4. تظهر النتيجة في الدردشة على شكل بطاقة يراها كل من في الدردشة.

دع الذكاء الاصطناعي يبني العنصر

بصفتك مسؤول الشركة لست مضطرا لاستخدام المحرر بنفسك. قل ذلك لمساعد Skava في الدردشة، مثلا: «ابن لي نموذج طلب من كتالوجي مع الكمية وعنوان التسليم». فيصنع من ذلك مسودة، ويمكنه لاحقا تغيير الحقول واحدا واحدا، وهو يعرف كتالوج الأصناف الذي رفعته: فللطلبات يقترح أداة اختيار المنتج بدلا من حقل نصي لرقم الصنف.

وما يجوز له ضبطه أيضا: عنوان الوجهة والطريقة وكذلك دائرة المستخدمين («أعضاء الشركة فقط» أو «وأيضا من هم خارجها في الدردشة نفسها»). أما دائرة المستخدمين فيسأل عنها أولا بدل أن يضبطها من تلقاء نفسه، لأنها تحدد من يجوز له التشغيل من الخارج.

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

من يجوز له تشغيلها

علامة التبويب «Endpoint» تحدد من يجوز له استخدام العنصر. والوضع الافتراضي هو أعضاء شركتك. أما الإعداد الثاني فيفتحه أيضا لمن هم خارج الشركة، لكن فقط في دردشة يحضر فيها أحد من شركتك، أي في الحالة التي وضع من أجلها بالضبط: العميل الذي يطلب منك. وحين تغادر شركتك الدردشة ينتهي الإذن من تلقاء نفسه.

منتجات من كتالوجك الخاص

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

حدد البطاقة بنفسك

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

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v يجب أن يكون العدد الصحيح 1. وبدونه لا يعد الرد بطاقة ويسري عندئذ ربط الرد المضبوط في العنصر.
• state يحدد اللون والأيقونة فقط: ok أو pending أو warn أو error. وكل ما يحمل معنى يوضع في status_text كنص حر.
• fields قائمة من تسمية وقيمة، بحد أقصى 20 مدخلا. والقيم الطويلة جدا تختصر بدل أن ترفض، حتى لا يفشل طلب بسبب تفصيل صغير.

ما أدخله المستخدم ملك للخادم: يبقى كما هو مهما أرسل خادمك الخلفي. فهو السجل في الدردشة لما أرسل فعلا.

الإبلاغ عن الحالة لاحقا

عند تشغيل العنصر ترسل Skava قيمتين إضافيتين: callback_url وcallback_token. أبلغ هناك لاحقا عن حالة جديدة فتظهر بطاقة جديدة في الدردشة، وعلى الهاتف أيضا، بينما ينظر أحدهم. وتبقى السابقة في مكانها، فيمكن قراءة متى أبلغ عن كل حالة. أرسل الكائن card نفسه المذكور أعلاه، عبر POST مع الترويسة Authorization: Bearer <callback_token>. وإلى جانب البطاقة ثلاث قيم اختيارية:

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

يجوز للتفاعل الواحد أن ينشر 50 بطاقة كحد أقصى. والبلاغ نفسه مرتين لا ينتج بطاقة ثانية.

ترد Skava بالرمز 200 وبقائمة hints إذا اختصر شيء أو أسقط، وبالرمز 422 إذا كانت البطاقة غير صالحة للاستخدام. ويقبل التفاعل البلاغات لمدة 90 يوما.

تنشر البطاقات باسم مرسل النظام في Skava، لا باسم الشخص الذي شغل العنصر ولا باسم حساب من شركتك. وصاحب النظام الذي يكتب مذكور في عنوان البطاقة.

يوجد مثال كامل جاهز للنسخ في المستودع ضمن example_order_server/ ويعمل على api.skava.io.

ذات صلة

هل تريد بدلا من ذلك إنشاء قالب مستند قابل للتعبئة؟ انظر العناصر المخصصة: المستندات.

الأسئلة الشائعة