دليل تطوير تطبيقات السوق

تطبيقات بليزيوم هي إضافات تضيف قدرات جديدة إلى لوحات الإدارة والمنتجات (CRM، ERP، التجارة الإلكترونية، البريد...) - مثل متجر تطبيقات Shopify أو تطبيقات Slack. ليس التطبيقات المحمولة المركبة على الهاتف.

نموذج العمل

تطبيقك يعمل على نموذج "HTTP عن بعد": لا يتم تحميل الشفرة في Blesium، ويعمل خارج حدود الشبكة على خادمك ويتواصل مع التوقيع، SSRF محمية، محدودة السرعة REST المكالمات. لا توجد إمكانية الوصول المباشر إلى قاعدة البيانات.

• في (بليسيوم) → هوية التطبيق، الفئة، المنتجات المستهدفة، التصاريح المطلوبة، التسعير وتاريخ الإصدار
• لديك واحد → التطبيق نفسه: منطق الأعمال، الوصلة البينية، تجهيز البيانات
• الوصول إلى البيانات → فقط عن طريق API، فقط في حدود التصاريح التي وافق عليها المستأجر

1. حدد تطبيقك

الحقول التي يجب ملؤها عند إنشاء تطبيق جديد من الواجهة:

• الاسم الاسم المبين في المتجر
• ..الحلزون → مرفق العنوان؛ الحروف الصغيرة والأرقام والشفرات فقط
• الفئة إحدى القوائم التالية
• الوصف ماذا يفعل التطبيق
• المنتجات المستهدفة 1 - البريد الإلكتروني
• التصاريح المطلوبة نطاقات التطبيقات التي تحتاج إلى العمل
• التسعير مجاني · دفعة واحدة · اشتراك

ويجب أن تأتي الفئة من القائمة الرسمية؛ أما المفتاح خارج القائمة فسيرفض التقديم.

• التكامل → يربط بليزيوم بنظام خارجي
• تقرير إضافة تقرير/مؤشر إلى لوحة التحكم
• الموضوع الموضوع البصري
• التشغيل الآلي أتمتة تدفق العمل
• sales_قناة قناة المبيعات
• قناة_الرسائل قناة الرسائل
• الشحن )الشحن/النقل(
• العناصر لوحة الأدوات
• قطاع_حزمة مجموعة قطاعية
• اللغة_pack حزمة اللغات
• أخرى مجالات أخرى

2. الإذن

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

3. التوثيق

ويجري توقيع كل طلب إلى برنامج بليزيوم لواجهة البرمجة التطبيقية بمفتاح برنامج لواجهة البرمجية التطبيقية. شكل المفتاح هو blsk_{ortam}_{kimlik}_{gizli}، والجزء السري لا يظهر إلا مرة واحدة في وقت الإنشاء.

curl https://firmaniz.blescript.com/api/v1/me \
  -H "Authorization: Bearer blsk_live_ab12cd34_gizli-anahtariniz"

4. الاستماع للأحداث مع webhook

بدلاً من طرح الأسئلة باستمرار، تواصل معهم عندما يحدث ذلك. ويتضمن كل منجز ثلاثة عناوين:

• x-blesyum الحدث اسم الحدث (أو. فاتورة.مدفوعة)
• x-blesyum التسليم رمز التسليم؛ يستخدم للقضاء على الازدواجية
• التوقيع → HMAC-SHA256 توقيع الجسم الخام (سداسي)

الأحداث التي يمكنك الاشتراك فيها ومتى يتم إشعالها:

• الفاتورة. → استحداث فاتورة جديدة
• الفاتورة.paid سداد الفاتورة
• الفاتورة. أعيدت الفاتورة
• الاشتراك. تم تجديد الاشتراك
• الاشتراك. خطة الاشتراك تغيرت
• الاشتراك. الاشتراك ملغى
• مدعو → مستخدم مدعو إلى الفريق
• user.انضم انضم مستخدم مدعو
• ticket.إنشاء → فتح طلب الدعم
• الرد → طلب دعم تم الرد عليه

التحقق من التوقيع مقارنة بالجسم الخام، باستخدام مقارنة زمنية ثابتة (وليس كما تم تحويله إلى JSON - فالاختلافات في المساحة ستحطم التوقيع):

import crypto from "node:crypto";

export function imzaDogrula(rawBody, header, secret) {
  const beklenen = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(beklenen);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

5. الإصدار

الحقول التي تدخلها عند نشر نسخة:

• القناة → مستقر أو بيتا
• النطاق → فتح تدريجي من صفر-100 في المائة
• الحالة → أُذيع أو سُحب

تدفق المنشورات:

1. Submit Version - أدخل رقم الإصدار، والقناة وملاحظة التغيير.
2. تفكيك العبوة تدريجياً - تطلق شرائح صغيرة أولا بنسبة مئوية معينة.
3. انتظر للمراجعة - عندما يمر التطبيق بالمراجعة، يتم إطلاقه في المتجر.
4. إعادة الوضع إلى ما كان عليه عند الضرورة - إعادة النسخة التي تسببت في المشكلة؛ ولا يحذف السجل، بل تستعاد النسخة السابقة.

أظهر حالة تطبيقك في الواجهة:

6. القائمة المرجعية السابقة للإصدار

• لقد قللت من الإذن المطلوب
• أنت تثبت صحة توقيع الويب هووك، لا تعيد معالجة التسليم المتكرر.
• مفتاح API هو فقط على جانب الخادم؛ تدفق التسرب الاحتياطي جاهز.
• تطبيقك لا يوقف عمل المستأجر في حالة الفشل (الإسقاط الخفيف).
• ويبين الوصف وصور الشاشة ما يفعله التطبيق فعلا.