زر الشراء

زر الشراء بضعة أسطر من HTML تلصقها على أي صفحة. لا إطار عمل، ولا خطوة تثبيت من جانبك. يُصيَّر الزر عند أول رسم؛ وتُحمَّل قائمة المزودين وحزم SDK مزودي الدفع عند الطلب أول مرة ينقر فيها مشترٍ. ويعمل في أي موقع أو إطار عمل يصيّر HTML، بما فيها منشئو المواقع بلا كود الذين يتيحون لك لصق تضمينات HTML.

مؤكَّد العمل مع: Angular، وHugo، وJekyll، وHTML بسيط، وWebflow (تضمين Custom Code)، وCarrd (عنصر Embed)، وFramer (تضمين HTML)، وSquarespace (Code Block)، وWordPress (كتلة Custom HTML)، وGhost، ومواقع Notion (أدوات تضمين HTML). إن سمح لك موقعك بلصق HTML على صفحة، فإن زر الشراء يعمل هناك.

مرجع الخصائص

الخاصية	مطلوبة	ما تقبله	ملاحظات
`endpoint`	لا	نص URL	احذفها دائماً تقريباً. يكتشف الزر تلقائياً قاعدة واجهته البرمجية: `https://api.coinmoebius.com` في الإنتاج، و`http://localhost:8787` على localhost. اضبطها فقط كتجاوز لإعداد غير معتاد (مثل وكيل ذاتي الاستضافة أمام الواجهة البرمجية).
`project-id`	نعم	نص، بالبادئة `proj_`	من صفحة مشروعك في لوحة التحكم. آمن للكشف علناً، فهو معرّف، لا بيانات اعتماد.
`product-id`	نعم (في الوضع الصارم) / مُوصى به (في الوضع المؤقت)	نص، بأي صيغة تختارها	معرّف منتجك الداخلي. في الوضع الصارم (الافتراضي)، هذه هي الطريقة التي يبحث بها الـ worker عن السعر من فهرسك. وفي الوضع المؤقت، يبقى مُمرَّراً إلى webhooks الخاصة بك في `metadata.productId` لتربط المعاملات بالمخزون. اطّلع على قسم الوضع الصارم مقابل الوضع المؤقت أدناه.
`amount`	في الوضع المؤقت فقط	رقم عشري كنص	السعر بالوحدات الكبرى (مثل الدولارات، لا السنتات). يجب أن يكون موجباً. احذفها في الوضع الصارم. يقرأ الـ worker السعر القانوني من فهرسك ويتجاهل أي قيمة في HTML. مطلوبة فقط حين يكون المشروع في الوضع المؤقت ويكون `product-id` ليس في الفهرس.
`currency`	في الوضع المؤقت فقط	رمز ISO 4217 من ثلاثة أحرف أو اسم وحدتك الخاص	`USD`، و`EUR`، إلخ. للبطاقات / وسائل الدفع بالعملات الرقمية. ويقبل مزود الدفع بالبريد أي نص (مثل `GBK`) لأن التاجر هو من يسوّي المعاملة. والقاعدة نفسها مثل `amount`: احذفها في الوضع الصارم، ومطلوبة في الوضع المؤقت للمنتجات غير الموجودة في الفهرس.
`label`	لا	نص	نص الزر. الافتراضي `Buy`. استخدمها للتمييز بين الأزرار على الصفحة نفسها.
`customer-ref`	لا	نص، بأي صيغة تختارها	معرّف مبهم للمشتري في نظامك الخاص، مثل معرّف مستخدم مسجَّل الدخول. يمرّره الزر إلى الـ worker بصفة `metadata.customerRef`، ويسِم الـ worker المعاملة به. ولاحقاً يمكنك أن تسأل "أي من مستخدميّ دفع؟" باستخدام معرّفك الخاص، دون أن نحتفظ بأي بيانات عميل فعلية. احذفها للدفع المجهول.
`theme`	لا	`dark` أو `light`	يختار نظام الألوان المدمج للزر والنافذة المنبثقة معاً. الافتراضي `dark`. اضبط `theme="light"` للنظام الفاتح. وتتجاوز متغيرات CSS الخاصة بك أياً منهما. اطّلع على دليل التصميم.
`editable-amount`	لا	`true` أو `false`	حين `true`، تُظهر النافذة المنبثقة حقل مبلغ يملؤه المشتري (إكراميات، تبرعات، ادفع ما تشاء). الافتراضي `false`، حيث يكون `amount` الذي تضبطه ثابتاً ولا يظهر أي حقل. وتبقى أزرار الدفع معطَّلة حتى يكون المبلغ رقماً موجباً.

أزرار متعددة على صفحة واحدة

يسجّل السكربت الزر مرة واحدة، ثم يمكن لأي عدد من النسخ أن يُصيَّر على صفحة. وكل نسخة مستقلة. ويستخدم المثال أدناه الوضع الصارم (الافتراضي): بلا amount أو currency في HTML، لأن الـ worker يبحث عن السعر من كل منتج في فهرسك.

<coin-moebius-buy
  project-id="proj_YOUR_ID"
  product-id="t-shirt-medium"
  label="T-shirt (medium)">
</coin-moebius-buy>

<coin-moebius-buy
  project-id="proj_YOUR_ID"
  product-id="mug-blue"
  label="Blue mug">
</coin-moebius-buy>

إن كان مشروعك في الوضع المؤقت (أدوات تبرع، جرار إكراميات)، فإن كل زر يتضمن أيضاً amount وcurrency. اطّلع على الوضع الصارم مقابل الوضع المؤقت للصورة الكاملة.

تنسيق سمة الزر

يُصيَّر زر الشراء داخل Shadow DOM، ما يعني أن أياً من CSS الموجود في صفحتك لا يصل إليه. وهذا متعمَّد: يُبقي الزر يبدو نفسه على كل موقع، ويمنع قاعدة * { box-sizing: ... } شاردة من كسر نافذة القائمة المنبثقة. تصمّمه عبر سطحين من ورقة أنماطك الخاصة: خصائص CSS المخصصة للألوان، والخطوط، والشكل، ومحدِّدات ::part() لكل ما عداها. ولا JavaScript معني.

كل متغير وجزء موثَّق في دليل التصميم، مع أمثلة حية يمكنك النقر عليها ونسخها:

افتح دليل التصميم التفاعلي →

عناوين النجاح والإلغاء

حين تربط Stripe أو NOWPayments في تبويب المزودين بلوحة التحكم، تضبط عنوانين:

عنوان النجاح، حيث يصل المشتري بعد دفعة ناجحة. تضيف Stripe وNOWPayments معامل استعلام (?session_id=... لـ Stripe، و?NP_id=... لـ NOWPayments) لتتمكن صفحة نجاحك من تحديد أي معاملة اكتملت. ومعظم المواقع الثابتة تعرض فقط رسالة عامة "شكراً، دفعتك قيد المعالجة" وتعتمد على لوحة التحكم كمصدر للحقيقة.
عنوان الإلغاء، حيث يصل المشتري إن تراجع قبل الدفع. غالباً ما يكون نفس صفحة سلّتك.

يُهيَّأ العنوانان لكل مزود في لوحة التحكم، فلا يحتاج العنصر إلى معرفتهما.

زر الشراء