التطبيقات وتكامل الدفع

استخدم einvoice كواجهة خلفية للفوترة لمنتجات SaaS الخاصة بك. أنشئ تطبيقاً، وحدد خطط الأسعار، وادمج أداة الدفع، واستقبل إشعارات موقّعة عند كل معاملة.

نظرة عامة

تتيح لك ميزة التطبيقات:

• إنشاء تطبيقات تمثّل منتجات SaaS الخاصة بك
• تحديد خطط الأسعار (اشتراكات متكررة أو مدفوعات لمرة واحدة)
• توليد مفاتيح API لتأمين الاتصال بين الخوادم
• إعداد الويب هوك لتلقّي إشعار بكل عملية دفع
• دمج SDK الدفع مباشرة في صفحات موقعك
• مراقبة تسليمات الويب هوك الفاشلة لتصحيح الأخطاء

ما هو التطبيق؟

التطبيق (أو “app”) يمثّل أحد منتجات SaaS الخاصة بك داخل einvoice. عندما يدفع أحد عملائك عبر صفحة الدفع، يقوم einvoice بما يلي:

1. إنشاء جلسة الدفع باسم تطبيقك
2. معالجة الدفع عبر بوابة الدفع الخاصة بك (Berexia)
3. إصدار فاتورة لعميلك (B2C أو B2B)
4. إرسال ويب هوك موقّع إلى رابطك لتفعيل الوصول

إنشاء تطبيق

1. انتقل إلى الشركة ← الإعدادات ← التطبيقات
2. انقر على “إنشاء تطبيق”
3. أكمل النموذج:
   • الاسم: الاسم الظاهر لمنتج SaaS الخاص بك (مثال: «تطبيقي»)
   • المعرّف (Slug): معرّف قصير وفريد (مثال: my-app) — يُستخدم في بادئات مفاتيح API
   • رابط الويب هوك: رابط خادمك لاستقبال إشعارات الدفع
   • رابط النجاح: الصفحة التي يُعاد توجيه المستخدم إليها بعد الدفع الناجح (اختياري)
   • رابط الإلغاء: صفحة العودة عند التخلّي عن الدفع (اختياري)
4. انقر على “إنشاء”

مهم — انسخ سرّ الويب هوك فوراً. بعد الإنشاء، يُعرض سرّ الويب هوك مرة واحدة فقط. انسخه واحفظه في مكان آمن (متغير بيئي). لن يكون متاحاً بعد ذلك.

فهم مفاتيح API

تؤمّن مفاتيح API الاتصال بين خادمك وواجهة برمجة einvoice. يوجد نوعان:

مفتاح التطبيق (ek_)

• البادئة: ek_{slug}_
• النطاق مقتصر على تطبيق واحد فقط
• يُستخدم من جانب الخادم لإنشاء جلسات الدفع
• موصى به لتكامل تطبيق محدد

مفتاح الشركة (ck_)

• البادئة: ck_{slug}_
• وصول كامل إلى جميع بيانات حسابك
• يُستخدم للتكاملات العامة (مثل أدوات الإدارة الداخلية)
• استخدمه بحذر — نطاق وصول أوسع

قواعد الأمان الأساسية

• يُعرض مفتاح API مرة واحدة فقط عند الإنشاء — انسخه فوراً
• لا تُدرج مفتاح API أبداً في كود الواجهة الأمامية أو SDK جانب العميل
• احفظ المفاتيح في متغيرات البيئة جانب الخادم
• قم بتدوير مفاتيحك بانتظام

توليد مفتاح API

1. في قائمة التطبيقات، انقر على “عرض المفاتيح” للتطبيق المعني
2. انقر على “إنشاء مفتاح”
3. أعطِ المفتاح اسماً وصفياً (مثال: «الإنتاج»، «خادم Node.js»)
4. انقر على “إنشاء”
5. انسخ المفتاح المعروض فوراً — لن يكون مرئياً بعد الإغلاق

تدوير مفتاح API

يولّد التدوير مفتاحاً جديداً ويُبقي القديم نشطاً لمدة 24 ساعة (فترة السماح)، مما يتيح لك وقتاً لنشر المفتاح الجديد.

1. على سطر المفتاح المعني، انقر على “تدوير”
2. أكّد العملية
3. استرجع المفتاح الجديد من مربّع العرض
4. حدّث متغير البيئة الخاص بك
5. سيُلغى المفتاح القديم تلقائياً بعد 24 ساعة

إلغاء مفتاح API

الإلغاء فوري ولا يمكن التراجع عنه. سيُرفض أي طلب يستخدم هذا المفتاح.

1. على سطر المفتاح المعني، انقر على “إلغاء”
2. أكّد في مربع الحوار
3. يُعطَّل المفتاح على الفور

استخدم التدوير (لا الإلغاء) إذا أردت استبدال مفتاح دون انقطاع في الخدمة.

سرّ الويب هوك

يُستخدم سرّ الويب هوك للتحقق من أصالة الإشعارات التي يُرسلها einvoice إلى خادمك. يُولَّد تلقائياً عند إنشاء التطبيق.

إعادة توليد سرّ الويب هوك

إذا تعرّض سرّك للاختراق، أعد توليده:

1. في عرض التطبيق، انقر على “إعادة توليد السرّ”
2. أكّد العملية
3. انسخ السرّ الجديد فوراً من مربّع العرض
4. حدّث متغير البيئة الخاص بك

تُلغي إعادة التوليد السرَّ القديم فوراً. ستُرفض الويب هوك التي لا يمكن التحقق منها من قِبَل خادمك.

التحقق من ويب هوك مُستلَم

يجب أن يتحقق خادمك من توقيع كل ويب هوك لرفض الطلبات الاحتيالية.

الترويسات التي يُرسلها einvoice:

• X-Einvoice-Event: اسم الحدث (subscription.activated أو payment.succeeded أو subscription.renewed)
• X-Einvoice-Signature: توقيع HMAC-SHA256 لجسم الطلب

مثال التحقق (Node.js):

const sig = req.headers['x-einvoice-signature'];
const expected = crypto.createHmac('sha256', process.env.EINVOICE_WEBHOOK_SECRET)
  .update(JSON.stringify(req.body)).digest('hex');
if (sig !== expected) return res.status(401).send('توقيع غير صالح');

تسليمات الويب هوك الفاشلة

في أسفل صفحة التطبيقات، يسرد قسم “التسليمات الفاشلة” الويب هوك التي لم يمكن تسليمها بعد 5 محاولات (التأخيرات: فوري ← دقيقة واحدة ← 5 دقائق ← 30 دقيقة ← ساعتان).

لكل تسليم فاشل، ستجد:

• الحدث المعني
• رقم المحاولة
• تاريخ الحدوث
• المرجع الخارجي المرتبط (معرّف مستخدمك)

تأكد من أن رابط الويب هوك الخاص بك متاح للعموم ويُعيد HTTP 200 لكل حدث.

دمج SDK الدفع

لعرض خطط تطبيقك على موقعك، أضف سكريبت einvoice:

عرض الخطط فقط:

<script src="https://app.einvoice.ma/paywall.js"
  data-app="معرّف_تطبيقك" data-target="#pricing">
</script>

الدفع مع جلسة خادم: ينشئ خادمك أولاً جلسة دفع عبر واجهة API، ثم يُمرّر المعرّف إلى SDK:

<script src="https://app.einvoice.ma/paywall.js"></script>
<script>
  const paywall = new EinvoicePaywall({ app: 'معرّف_تطبيقك' });
  paywall.checkout(sessionId, '#pricing');
  paywall.on('success', (data) => {
    // data.subscription_id, data.plan_slug, data.external_ref
    window.location.href = '/مرحباً';
  });
</script>

يجب ألّا يُدرَج مفتاح API أبداً في كود الواجهة الأمامية. تُحدَّد هوية المشتري حصراً من جانب الخادم عند إنشاء الجلسة.

موارد للمطوّرين

شارك هذه الموارد مع الفريق التقني الذي سيتولّى تكامل einvoice:

• دليل التكامل — التدفق الكامل من الخادم إلى الواجهة: developers.einvoice.ma/integration
• مرجع SDK — واجهة EinvoicePaywall، خصائص data-*، الأحداث: developers.einvoice.ma/sdk
• التحقق من الويب هوك — توقيع HMAC، الأحداث، إعادة المحاولة: developers.einvoice.ma/webhooks/verification

نصائح وأفضل الممارسات

• سمِّ المفاتيح حسب البيئة: «الإنتاج»، «الاختبار»، «CI» لسهولة التدوير
• دوّر المفاتيح بانتظام (كل 90 يوماً موصى به)
• اختبر الويب هوك بأداة مثل Webhook.site قبل الإطلاق
• راقب التسليمات الفاشلة بعد كل نشر لخادمك
• استجب بسرعة (HTTP 200) للويب هوك — ينتظر einvoice أقل من 10 ثوانٍ

حل المشاكل

مفتاح API مرفوض (401)

• تحقق من أنك ترسل ترويسة X-API-Key: ek_... في الطلب
• أكّد أن المفتاح نشط (غير ملغى) في قائمة المفاتيح
• مفتاح في فترة التدوير قد يعمل لـ 24 ساعة — تحقق من تاريخ الانتهاء

الويب هوك لا يصل

• تحقق من أن رابط الويب هوك متاح من الإنترنت (ليس localhost)
• تأكد من أن خادمك يُعيد HTTP 200 — أي كود آخر يُشغّل إعادة المحاولة
• راجع قسم “التسليمات الفاشلة” لتحديد الخطأ

سرّ الويب هوك غير صحيح

• تأكد من أنك تستخدم جسم الطلب الخام (لا الكائن المُحلَّل)
• في Node.js: استخدم express.raw() أو express.json() قبل middleware التوقيع
• إذا تغيّر السرّ (أُعيد توليده)، حدّث متغير البيئة

SDK لا يحمّل الخطط

• تحقق من أن data-app يطابق معرّف تطبيقك تماماً
• نقطة /rpc/get_app_plans عامة، لا يلزم مفتاح API من جانب العميل
• راجع وحدة تحكم المتصفح للأخطاء المتعلقة بـ CORS أو الشبكة

---

تحتاج مساعدة؟ اتصل بالدعم التقني.