دليل ربط المتجر الإلكتروني

دليل شامل لربط متجرك الإلكتروني مع منصة عبده — يتيح للمتجر عرض أرصدة المستحقين وقبول أكواد الشراء الخاصة بهم

قبل البدء

يجب أن تكون منشأتك مسجلة وموثقة في عبده. ستجد مفاتيح الـ API (Publishable Key و Secret Key) في تبويبة "ربط المتجر" داخل لوحة تحكم المنشأة.

مفاتيح الـ API

يعتمد نظام الربط على مفتاحين لكل متجر، مشابه للأنظمة الاحترافية مثل Stripe و Moyasar:

Publishable Key

abm_pk_...

يُستخدم في الـ SDK (JavaScript) — آمن للعرض في المتصفح

Secret Key

abm_sk_...

يُستخدم في طلبات الـ API الخادمية — يجب إبقاؤه سرياً

ملاحظة: لا يحتاج المطور لمعرفة أو إرسال establishment_id — المنشأة تُستنتج تلقائياً من المفتاح المستخدم.

الطريقة الأولى: JavaScript SDK

حزمة JavaScript خفيفة تتيح دمج شريط عرض الأرصدة المتناوبة مباشرة في تصميم متجرك — بشعار المنشأة، شعار عبده، والأرصدة المتناوبة، بألوان وخطوط متجرك. العنصر بالكامل قابل للنقر، وعند الضغط تُفتح نافذة الدعم، وبعد الدفع يُرجع الـ SDK النتيجة إلى متجرك عبر callbacks دون تحويل المستخدم لصفحة خارجية.

المزايا:

يستخدم Publishable Key فقط — آمن للعرض في المتصفح
المنشأة تُستنتج تلقائياً من المفتاح
شريط عرض الأرصدة المتناوبة مع شعار المنشأة وشعار عبده
العنصر كله قابل للنقر — يفتح نافذة الدعم عند الضغط
قابل للتخصيص بألوان وخطوط متجرك
بعد الدفع: يُغلق الـ SDK النافذة ويُرجع النتيجة (onSuccess / onFailure / onCancel / onClose)
لا حاجة لـ React — JavaScript خالص

الخطوة 1: تحميل الـ SDK

أضف السطر التالي قبل إغلاق وسم body:

<script src="https://abdulmokrem.com/sdk/abdulmokrem.js"></script>

الخطوة 2: إنشاء شريط الدعم

ضع حاوية في HTML ثم استدعِ createWidget مع Publishable Key:

<div id="abm-donate-btn"></div>
<script>
  AbdulMokremSDK.createWidget({
    publishableKey: "abm_pk_YOUR_PUBLISHABLE_KEY",
    container: "#abm-donate-btn",

    // --- تخصيص اختياري ---
    primaryColor: "#2563eb",
    textColor: "#ffffff",
    borderRadius: "10px",
    font: "'Tajawal', sans-serif",
    lang: "ar",
    direction: "rtl",

    // --- Callbacks ---
    onSuccess: function(data) {
      console.log("تم الدفع بنجاح", data);
    },
    onFailure: function(data) {
      console.log("فشل الدفع", data);
    },
    onCancel: function() {
      console.log("ألغى المستخدم");
    },
    onClose: function() {
      console.log("أُغلقت النافذة");
    }
  });
</script>

الإعدادات

الخاصية	مطلوب	الوصف
publishableKey	نعم	المفتاح العام (abm_pk_...)
container	نعم	معرف أو عنصر الحاوية
primaryColor	لا	اللون الأساسي (hex)
textColor	لا	لون النص (hex)
borderRadius	لا	نصف قطر الحواف
font	لا	عائلة الخط
lang	لا	"ar" أو "en"
direction	لا	"rtl" أو "ltr"

الأحداث (Callbacks)

onSuccess(data) — نجح الدفع

onFailure(data) — فشل الدفع

onCancel() — أغلق المستخدم النافذة قبل الدفع

onClose() — أُغلقت النافذة (يُستدعى دائماً)

الطريقة الثانية: API أكواد الشراء (Secret Key)

واجهة برمجية تتيح لمستخدمي عبده استخدام أكوادهم المحجوزة عند الشراء من متجرك. تتطلب Secret Key في ترويسة Authorization. تتكون من خطوتين: التحقق من الكود، ثم تأكيد الخصم بعد الدفع.

تحذير أمني

استخدم الـ Secret Key في الخادم فقط (Server-side) — لا تضعه في كود JavaScript الذي يُعرض في المتصفح.

آلية العمل:

المستخدم يضيف كوده

1. التحقق

يُخصم من الفاتورة

2. تأكيد بعد الدفع

الخطوة 1: التحقق من الكود

أرسل طلب مع الـ Secret Key في ترويسة Authorization. لا ترسل establishment_id — المنشأة تُستنتج من المفتاح.

fetch("https://abdulmokrem.com/functions/ecommerceValidateCode", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer abm_sk_YOUR_SECRET_KEY"
  },
  body: JSON.stringify({
    code: "USER_CODE"
  })
}).then(r => r.json()).then(data => {
  if (data.valid) {
    // الكود صالح
    // data.reserved_amount = المبلغ المتاح للخصم
    // data.category_name = اسم الفئة (يتيم، فقير، إلخ)
    // data.mins_left = الوقت المتبقي قبل انتهاء الصلاحية
  } else {
    // الكود غير صالح
    // data.message = سبب الرفض
  }
});

الاستجابة عند النجاح:

{
  "valid": true,
  "reserved_amount": 500,
  "category_name": "يتيم",
  "mins_left": 25
}

الخطوة 2: تأكيد الخصم

بعد إتمام الدفع بنجاح، أرسل طلب لتأكيد خصم المبلغ.

fetch("https://abdulmokrem.com/functions/ecommerceConfirmPurchase", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer abm_sk_YOUR_SECRET_KEY"
  },
  body: JSON.stringify({
    code: "USER_CODE",           // نفس الكود من الخطوة 1
    purchase_amount: 150,         // المبلغ الفعلي للشراء
    order_id: "ORDER_123"         // رقم طلبك (مهم لمنع التكرار)
  })
}).then(r => r.json()).then(data => {
  if (data.success) {
    // تم الخصم بنجاح
    // data.used_amount = المبلغ المخصوم فعلياً
    // data.remaining_reserved = المتبقي في الكود (إن وجد)
  } else {
    // فشل (الكود منتهي أو مستخدم مسبقاً)
  }
});

الاستجابة عند النجاح:

{
  "success": true,
  "used_amount": 150,
  "remaining_reserved": 350,
  "message": "تم خصم 150 ريال من الرصيد المحجوز، وتبقى 350 ريال في الكود"
}

قواعد مهمة

استخدم الـ Secret Key في الخادم فقط — لا تضعه في كود الواجهة
لا تستدعي تأكيد الخصم إلا بعد نجاح الدفع فعلياً
إذا كان مبلغ الشراء أقل من الرصيد المحجوز: يُخصم مبلغ الشراء فقط
إذا كان مبلغ الشراء أكثر من الرصيد المحجوز: يُخصم كامل الرصيد
كل كود يُستخدم مرة واحدة فقط
يمكنك إعادة إنشاء الـ Secret Key أو تعطيله من لوحة التحكم في أي وقت

روابط الـ API

التحقق من الكود

https://abdulmokrem.com/functions/ecommerceValidateCode

تأكيد الخصم

https://abdulmokrem.com/functions/ecommerceConfirmPurchase

لأي استفسارات حول الربط، يرجى التواصل مع الدعم الفني عبر صفحة التواصل