عناصر مخصّصة: واجهة برمجة التطبيقات

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

إعداد واجهة برمجة التطبيقات

تتكون الواجهة من حقول إدخال (تشكّل 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، ثم Release.

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

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

الاختبار: Ping وطلب اختبار

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

بصفتك مسؤولاً، يمكنك تشغيل كلا الخيارين أثناء وضع المسودة للتحقق من التكامل قبل الإطلاق.

مسودة وإصدار

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

الأمان

كيف يستخدم الفريق واجهة مُصدَرة

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

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

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

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

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

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

من يمكنه تشغيله

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

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

بمجرد رفع كتالوج المقالات الخاص بك، يقدّم المُنشئ كتلة منتقي المنتجات. لا توجد خيارات تحتاج إلى صيانة: القائمة هي كتالوجك. يبحث الشخص الذي يطلب فيها، ويرى الصورة والاسم ورقم المقال، ويستقبل نظامك الخلفي رقم المقال. ترفض 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.

عناصر ذات صلة

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

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