استخدام الواجهة البرمجية

استخدامه دون زر الشراء

زر الشراء طبقة راحة. في الأساس، Coin Moebius هو webhook مستأجَر إضافة إلى بضع نقاط نهاية JSON. إن فضّلت بناء واجهتك الخاصة، أو تشغيل تدفّق دفعك الخاص، أو توصيل Coin Moebius بشيء لا يستطيع الزر التعامل معه (اشتراكات Square أو Authorize.Net، أو نموذج دفع مخصص، أو سكربت من جانب الخادم، أو تطبيق هاتف)، فكل نقطة نهاية يستخدمها الزر قابلة للاستدعاء من أي شيء أيضاً. ولا تغييرات كود من جانبنا.

مصادقة نداءات الخادم الخلفي

يمكن للنداءات التي تجريها من خادمك الخاص أن تحمل مفتاح واجهة مشروعك البرمجية كرمز bearer. أنشئ مفتاحاً في لوحة التحكم، تحت مفاتيح واجهة مشروعك البرمجية (يبدأ بـ cmk_)، وأرسله في ترويسة Authorization:

Authorization: Bearer cmk_live_xxxxxxxxxxxxxxxxxxxxxxxx

المفتاح مرتبط بمشروع واحد، وتحصل النداءات المصادَق عليها على حد معدّل أعلى من المجهولة. وزر الشراء نفسه عام ولا يحتاج مفتاحاً. أبقِ مفتاحك على خادمك. ولا تضعه أبداً في كود المتصفح أو كود آخر من جانب العميل.

تعيش كل نقاط النهاية هذه تحت عنوان مشروعك. وفي الإنتاج تكون تلك القاعدة https://api.coinmoebius.com. ويُعرَض العنوان الكامل لكل منها أدناه (استبدل أجزاء {…} بقيمك الخاصة).

نقطة النهاية	ما تفعله
`POST https://api.coinmoebius.com/api/checkout/{provider}/{projectId}`	بدء عملية دفع. POST لـ `{ productId, metadata }`؛ استلم ما يحتاجه المزود (عنوان إعادة توجيه لـ Stripe، أو عنوان موافقة لـ PayPal، أو رمز لـ Authorize.Net Accept Hosted). صيّره كما تشاء.
`POST https://api.coinmoebius.com/webhook/{provider}/{projectId}`	ينشر المزود هنا. نتحقق من التوقيع، ونوحّد الحدث، ونخزّنه، ونحتسب الحصة. وجّه webhook المزود إلى هذا العنوان سواء أتت عملية الدفع الأصلية من زرنا أو من تكاملك الخاص.
`GET https://api.coinmoebius.com/status/{projectId}/{txId}`	استطلع الحالة الراهنة لدفعة أو اشتراك. يعيد الشكل الموحَّد نفسه الذي يحصل عليه زر الشراء.
`POST https://api.coinmoebius.com/api/subscriptions/{projectId}/{subscriptionId}/portal-url`	ولّد عنوان بوابة مستضافة من المزود ليدير المشتري اشتراكه. يعمل لأي مزود له بوابة.

تعرّف على المشتري في نظامك الخاص بتمرير metadata.customerRef في نداء الدفع. يمرّ عبر المزود وعودة على كل حدث webhook، فيمكنك ربط سجلات Coin Moebius بقاعدة بيانات مستخدميك الخاصة دون أن نخزّن أي شيء عن المشتري.

لماذا يستخدم أحدهم هذا المسار: منشئ موقع ثابت يريد كتابة زره الخاص ليطابق تصميم موقعه ويحتاج فقط إلى التعامل مع الـ webhook. مطوّر يريد تخطّي الزر تماماً واستدعاء الواجهة البرمجية من خادمه الخاص. تاجر يريد تشغيل اشتراكات Square أو Authorize.Net ولا يمانع في ربط جمع البطاقة بنفسه. الزر نقطة بداية. والواجهة البرمجية هي المنتج الفعلي.

الإنصات لأحداث المشتري

يُطلِق العنصر ثلاثة أحداث متصفح. أنصت بـ addEventListener على العنصر (أو على document، فالأحداث تنتقل صعوداً). كل الأحداث قابلة للإلغاء، واستدعاء event.preventDefault() يوقف التدفّق الافتراضي.

الحدث	متى يُطلَق	حمولة التفاصيل
`cm-load-providers`	نافذة القائمة المنبثقة على وشك أن تطلب من الواجهة البرمجية قائمة المزودين المهيَّئين على هذا المشروع.	فارغة.
`cm-checkout-started`	اختار المشتري مزوداً وCoin Moebius على وشك إنشاء جلسة دفع (Stripe / NOWPayments) أو توليد رمز مرجعي (يدوي).	`{ provider: 'stripe' \| 'nowpayments' \| 'manual', ... }`
`cm-error`	فشل شيء ما: خطأ شبكة، أو فشل توقيع، أو لا مزود مهيَّأ.	`{ error: Error }`

document.addEventListener('cm-error', (event) => {
  console.error('Coin Moebius:', event.detail.error);
  // Show your own error UI, send to your analytics, etc.
});

لا يوجد حدث cm-success في متصفح المشتري. فبحلول اكتمال الدفعة فعلاً، يكون المشتري قد أُعيد توجيهه إلى صفحة الدفع المستضافة لمزود الدفع (Stripe Checkout، أو صفحة فاتورة NOWPayments). ويعودون إلى موقعك عبر success_url الذي ضبطته (انظر القسم التالي)، ويعرف خادمك بالدفعة عبر لوحة التحكم أو باستطلاع نقطة نهاية /status.

الاستطلاع من خادمك الخلفي

لمصدر حقيقة من جانب الخادم، استطلع GET /status/:projectId/:txId من خادمك الخلفي. وشكل الاستجابة:

{
  "status": "succeeded",
  "amount": 29.99,
  "currency": "USD",
  "isTest": false,
  "createdAt": "2026-05-14T01:04:21.000Z",
  "updatedAt": "2026-05-14T01:04:21.000Z"
}

تتبع قيم الحالة النوع المعدَّد نفسه مثل لوحة التحكم (انظر حالات المعاملات). ونقطة النهاية غير مصادَق عليها لكنها محدودة المعدّل بـ 60 طلباً / دقيقة لكل IP. ومعرّف المعاملة الذي تمرّره هو ما أعاده الـ SDK في حدث cm-checkout-started أو ما يُعرَض في عمود المرجع بلوحة التحكم.

نمط نموذجي: حين تُحمَّل صفحة success_url الخاصة بك، ابدأ مهمة خادم خلفي تستطلع /status/:projectId/:txId كل 15 ثانية حتى ترى succeeded (أو failed / مهلة)، ثم نفّذ الطلب.