> For the complete documentation index, see [llms.txt](https://docs.mavibot.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mavibot.ai/doc/ar/integrations/payment/prodamus-blr/prodamus.md).

# Prodamus (KZ)

## **كيفية ربط بروداموس**

لربط Prodamus ستحتاج إلى عنوان URL لنموذج الدفع والمفتاح السري.

يتم إصدار عنوان URL لنموذج الدفع بعد التسجيل، ومثاله: `demo.payform.ru`.

يمكن الحصول على المفتاح السري من الحساب الشخصي، وهناك أيضًا يجب تحديد عنوان URL الذي ستُرسل إليه الإشعارات (notification).

<div data-with-frame="true"><figure><img src="/files/173d30e2e46283b820e87b1a8935052a4667cebd" alt=""><figcaption><p>المفتاح السري في إعدادات نموذج الدفع داخل الحساب الشخصي لنظام الدفع «بروداموس»</p></figcaption></figure></div>

[**دليل مفصل حول كيفية القيام بذلك**](https://help.prodamus.ru/payform.ru-onlain-oplaty/prochee/url-dlya-uvedomlenii-i-sekretnyi-klyuch)

عنوان الإشعارات:\
<https://chatter.mavibot.ai/prodamus\\_callback/result>

يجب تحديد هذا العنوان في الإعدادات في مكانين.

في الصفحة الرئيسية للإعدادات يمكنك اختيار وضع عمل نموذج الدفع: وضع تجريبي بدون دفع أو وضع استقبال المدفوعات.

<div data-with-frame="true"><figure><img src="/files/688ea0b38c5ba4f323f31ddd538aa10f63298c67" alt=""><figcaption></figcaption></figure></div>

يجب تحديد عنوان الإشعارات في إعدادات نظام الدفع في مكانين: **«إعداد النموذج»** في اللسان — للمدفوعات مرة واحدة (الاعتيادية) و **«الاشتراكات»** في اللسان — لمدفوعات الاشتراك.

<div data-with-frame="true"><figure><img src="/files/c06f24fa1f64beed5c186b8239ee8e0f73befceb" alt=""><figcaption></figcaption></figure></div>

**عنوان الإشعارات:**\
<https://chatter.mavibot.ai/prodamus\\_callback/result>

لإعداد العمل مع مدفوعات الاشتراك **«الاشتراكات»** انتقل إلى اللسان وحدد عنوان الإشعارات:

<https://chatter.mavibot.ai/prodamus\\_callback/result>

<div data-with-frame="true"><figure><img src="/files/1fc6a8ef6715ec8cb2a45bd8b856c191f2c0ad67" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}
**انتباه!** بعد إدخال عنوان URL تأكد من **«حفظ»** الضغط على الزر.
{% endhint %}

لربط Prodamus **«التحصيل»** يجب الانتقال إلى القسم.

<div data-with-frame="true"><figure><img src="/files/48009d06d57496dc2db24148f2b85d0204f62d3a" alt=""><figcaption></figcaption></figure></div>

بعد ذلك يكفي إدخال البيانات المذكورة أعلاه في النموذج:

<div data-with-frame="true"><figure><img src="/files/4fe4d27877df9599855b08a07bde400f0e48816f" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="warning" %}
**مهم!** عند تحديد عنوان URL لنموذج الدفع **https\://** لا تضف.
{% endhint %}

وهكذا اكتمل الربط. الآن لنرَ كيف نستخدم هذه الميزة.

## كيفية إنشاء رابط للدفع

### زر بوظيفة «دفع»

**يمكن إنشاء رابط للدفع في زر يحمل وظيفة «دفع».**

{% hint style="info" %}
[تم شرح كيفية إنشاء مثل هذا الزر في هذه المقالة.](/doc/ar/chatbot/builder/alazrar/zr-aldfa.md)
{% endhint %}

والآن لنستعرض جميع المعلمات الممكنة لهذا الزر.

### المعلمات الإلزامية لزر «دفع» في Prodamus

**لإنشاء رابط للدفع يجب تحديد المعلمات الإلزامية في إعدادات الزر:**\
«المبلغ»، «اسم المنتج»، وكذلك معلمة «المحتوى المدفوع» — إذا لم تكن لديك آلة تسجيل نقدي إلكترونية خاصة بك وتريد الحصول على إيصال من Prodamus.

عند الانتقال إلى صفحة إتمام الطلب، تظهر مسبقًا معلومات المنتج وسعره، بينما يُدخل العميل بيانات الاتصال الخاصة به فقط.

إذا تم تحديد Email و/أو هاتف المستخدم في إعدادات الزر، فستظهر في صفحة إتمام الطلب بيانات اتصال الدافع، وكذلك معلومات المنتج وسعره.

<div data-with-frame="true"><figure><img src="/files/57e5b407ecdb536702613a6a91b1437ddab83b91" alt="" width="563"><figcaption><p>نافذة إعدادات الزر</p></figcaption></figure></div>

**حقل «النص»** — سيظهر هذا النص في الرسالة على الزر الذي يحتوي على رابط الدفع.

**حقل «الوظيفة»** — لإنشاء زر يوفّر رابطًا للدفع نختار وظيفة «دفع».

**حقل «نظام الدفع»** — ستظهر في القائمة أنظمة الدفع المتصلة بالمشروع.\
إذا لم يكن أي نظام دفع متصلًا بالمشروع، فسيكون هذا النوع من الأزرار غير متاح.

**حقل «اسم المنتج» (إلزامي)** — يجب تحديد الاسم الدقيق للمنتج. على سبيل المثال، ليس «هاتف» بل «هاتف Xiaomi، الطراز …».\
ملاحظة: لا يمكن استخدام علامات اقتباس مزدوجة في اسم المنتج؛ احذفها أو استبدلها بعلامات اقتباس مفردة.

**حقل «المبلغ» (إلزامي)** — نحدد سعر المنتج.

**قائمة «معلومات إضافية»** — عند الضغط على هذا الزر ستُفتح حقول إضافية لإنشاء الرابط:

* وصف الطلب
* الخصم بالروبل
* متغير Email للمشتري
* متغير رقم هاتف المشتري
* مدة صلاحية الرابط
* معرّف المنتج للاشتراك (لإنشاء دفع تلقائي)
* المحتوى المدفوع

**خانة «الإشعار بالنقرة»** — يمكن تفعيلها لمراقبة الانتقال إلى رابط الدفع. في هذه الحالة، عند الضغط على الزر ستصل إلى محادثة العميل في سيلبوت رسالة تفيد بأنه تم الانتقال إلى الرابط.

<div data-with-frame="true"><figure><img src="/files/4f9dc5460d77d3439070080d4f13cc321f072ab2" alt="" width="431"><figcaption></figcaption></figure></div>

يمكن عبر هذه الرسالة ضبط منطق العمل اللاحق للروبوت.\
تدعم العديد من أنظمة الدفع صناديق النقد الإلكترونية السحابية، وهي مطلوبة وفقًا للقانون 54-FZ.

اطّلع على خصوصيات إصدار الإيصالات على موقع نظام الدفع المختار حتى لا تقع في مشكلة مع مصلحة الضرائب.

هكذا تبدو صفحة الدفع التي ستفتح عند الانتقال عبر الرابط الموجود في زر «دفع»:

<div data-with-frame="true"><figure><img src="/files/16c621bf00aca2e6caba6e0b11fd7e791ab406c9" alt="" width="375"><figcaption><p>صفحة الدفع: تم ملء المعلمات الأساسية فقط في الزر</p></figcaption></figure></div>

### إعدادات إضافية لإنشاء رابط الدفع

<div data-with-frame="true"><figure><img src="/files/2dba53d2d6276abd4a2b8b3c7ea093e81b2a4725" alt="" width="563"><figcaption></figcaption></figure></div>

**حقل «وصف الطلب»** — ستظهر المعلومات المدخلة في هذا الحقل في صفحة الدفع **البيانات الإضافية** حقل.

**حقل «الخصم»** — هنا يمكنك تحديد مقدار الخصم بالروبل أو بالروبل والكوبيك. وللتحديد بالكوبيك استخدم النقطة كفاصل: 50.99\
في صفحة الدفع سيظهر في حقل **المبلغ المطلوب دفعه** المبلغ مع احتساب الخصم، بينما سيُشطب السعر الأساسي للمنتج.

**حقل «متغير Email للمشتري»** (اختياري، إذا تم تحديد رقم الهاتف) — هنا يُذكر Email المستخدم (العميل). ويمكن أيضًا استخدام متغير Email محفوظ، مثل: `#{email}`

**حقل «متغير رقم هاتف المشتري»** (اختياري، إذا تم تحديد Email) — هنا يمكن استخدام متغير يحتوي على رقم هاتف المشتري المحدد، بالصيغة: 79000000000، مثل: `#{phone}`\
يجب أن يكون Email و/أو الهاتف مذكورًا.

**حقل «مدة صلاحية الرابط»** — التاريخ `dd.mm.yyyy hh:mm` يمكن تحديده بالصيغة (مثلًا، 25.01.2021 11:00) أو ضبط مدة صلاحية الرابط عبر متغير. مثلًا: `#{link_expired}`

**حقل «معرّف المنتج للاشتراك»** — لإنشاء دفع تلقائي حدّد قيمة معرّف المنتج. لإنشاء اشتراك يجب إنشاء منتج اشتراك.\
دليل مفصل: [إنشاء وإعداد اشتراكات Prodamus](https://help.prodamus.ru/payform/rekurrent-i-kluby/kak-sozdat-i-nastroit-podpiski)\
إذا تم تحديد معرّف المنتج للاشتراك، فلن يؤخذ مبلغ الدفع بعين الاعتبار. تؤخذ معلومات المنتج من بطاقة المنتج في حساب Prodamus.\
رقم الهاتف المحدد في الدفع سيكون مطلوبًا لإدارة الاشتراك.\
إذا تم تحديد معرّف المنتج للاشتراك، فسيُمرَّر في الكولباك عند نجاح الدفع معرّف هذا المنتج.

**حقل «المحتوى المدفوع»** (إلزامي بشكل مشروط) — هذه البيانات مطلوبة لإضفاء الطابع الضريبي على الدفع عبر Prodamus إذا لم تكن لديك آلة تسجيل نقدي إلكترونية خاصة بك. في هذا الحقل يُذكر وصف الشراء والسعر ورابط المحتوى.\
مثلًا: دورة «ضفر الشعر»، السعر 3000 روبل، رابط صفحة الدورة: `https://nbu.su/krasota/master-po-pleteniyu-kos/?yclid=13602995275739430911`

### زر بوظيفة «دفع»

إذا حدّدت مدة صلاحية الرابط، فسيحدث ما يلي:\
إذا طلب المستخدم رابط الدفع أثناء فترة صلاحيته (أي بينما لم تنتهِ مدة الرابط بعد) وكان داخل المحادثة، فلن يمكن تنفيذ الدفع، وسيظهر له الرسالة التالية:

<div data-with-frame="true"><figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcA1KJHoyMF5WmLMZiJPJrQEGJs79zxoXK5U3E9k4mVus-Fg0tI-djr6QTagp5ulwposSxmJ-aq8trUQOslQyE0UeaREuM6-T5Ongn-E5tACdVmypFXBtgOJDmVvHRgOdATChhnBQ?key=OB7qKicH0kn-_i_EzQLdRA" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="warning" %}
يجب أن تكون مدة صلاحية الرابط لاحقة للتاريخ الحالي، وإلا فلن يتمكن العميل من الدفع عبر هذا الرابط.
{% endhint %}

**2. عندما يطلب المستخدم الرابط، إذا لم يكن نشطًا حاليًا**\
في هذه الحالة لن يظهر الزر ببساطة. في متغيرات العميل `"error_payment_button"` سيظهر متغير ستكون قيمته كما يلي:\
\&#xNAN;**"خطأ: يجب أن تكون مدة صلاحية الرابط لاحقة للتاريخ الحالي"**.

{% hint style="success" %}
حتى يتمكن المستخدم من إتمام الدفع بشكل صحيح، يُنصح بمعالجة هذه الحالة بشكل إضافي.
{% endhint %}

أنشئ كتلة شرطية كهذه:\
إذا وصلت الرسالة التالية:\
`error_payment_button == "خطأ: يجب أن تكون مدة صلاحية الرابط لاحقة للتاريخ الحالي"`

فأظهر النص التالي:\
\&#xNAN;**"عذرًا، لم تتمكن من إتمام الدفع في الوقت المناسب، وكان رابط الدفع غير صالح"**.

<div data-with-frame="true"><figure><img src="/files/5b044be53054691dd9f70c55f2f985a3d9646693" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/4b5faf42df1d2e9eb94304a3c5c57d7251419915" alt=""><figcaption></figcaption></figure></div>

### المتغيرات العميلية التي تُنشأ تلقائيًا عند استخدام الزر بوظيفة «دفع»

عند حصول المستخدم على كتلة تحتوي على زر «دفع»، تُنشأ للعميل متغيرات تلقائيًا:

**متغير عميل خدمي `__payments`** — هذا المتغير يخزن المبلغ ومعرّف الرابط المُنشأ ويُستخدم لتحديد الويب هوك القادم من نظام الدفع.

{% hint style="danger" %}
متغير عميل خدمي `__payments`لا يمكن حذف -ты أو تغييره!
{% endhint %}

**`error_payment_button` متغير عميل** يُنشأ تلقائيًا إذا حدث خطأ عند إنشاء الزر.\
ويُسجَّل في هذا المتغير نص الخطأ أو رد الخطأ القادم من نظام الدفع.

{% hint style="warning" %}
تكون قيم المتغيرات سارية عند الانتقال إلى الكتلة التالية.
{% endhint %}

## كيفية معالجة النتيجة

**دفع ناجح**\
بعد الدفع الناجح إلى الروبوت **يصل كولباك تلقائيًا** والذي يتكون من أول 10 أحرف من المفتاح السري لنظام الدفع، `_success` وكلمة الدفع ومبلغ الدفع.\
وللاستخدام في إعداد المخطط يكفي فقط نسخه.

مثلًا: `ovg58keefc_success 44`، حيث:

* `ovg58keefc` — أول 10 أحرف من المفتاح السري لنظام الدفع
* `_success` — نتيجة معالجة الطلب (دفع ناجح)
* `44` — مبلغ الدفع

{% hint style="info" %}
المستخدم لا يرى الكولباكات من نظام الدفع **. فهي تُعرض فقط**في لسان «العملاء» **«العملاء»** ويستطيع المشغل رؤيتها.
{% endhint %}

**مثال على الاستخدام:**\
**الخطوة 1.** نضيف أزرارًا بوظيفة «دفع» إلى كتلة «يوجد زر دفع».\
**الخطوة 2.** نحدد الكولباك في حقل **شرط الربط** للانتقال من هذه الكتلة إلى كتلة «دفع ناجح».\
وبالمثل، إذا تم تحديد كولباك الدفع الناجح في شرط كتلة «الشرط الأولي»، فسيعمل الأمر بالطريقة نفسها.

{% hint style="warning" %}
**مهم:** قم باختيار «تطابق كامل» أو «بحسب وجود الكلمات المفتاحية».
{% endhint %}

❗️إذا قررت التحقق من الدفع في السهم المحدد حسب الشرط الدقيق، ففكّر جيدًا في منطق مخططك. إذا غادر العميل الكتلة التي تمر عبر الشرط مع الكولباك، فلن يحدث الانتقال إلى الكتلة. يُفضَّل استخدام طريقة التحقق هذه فقط إذا لم يغيّر العميل موضعه في القمع.

في المخططات التي يتحرك فيها العميل بين الكتل، يكون من الأنسب استخدام الكولباك **«الشرط الأولي»** في الكتلة.<br>

<div data-with-frame="true"><figure><img src="/files/0137303648f71fb82fd2ed277312d41e55211c9d" alt=""><figcaption><p>كولباك عن الدفع الناجح في حقل شرط البلوك.</p></figcaption></figure></div>

### دفع ناجح للمنتجات ذات الاشتراك التلقائي

بعد الدفع الناجح إلى الروبوت **يصل كولباك تلقائيًا** والذي يتكون من أول 10 أحرف من المفتاح السري لنظام الدفع، `_success` وكلمة ومعرّف منتج الاشتراك.

مثلًا: `214009eefc_success 618117`، حيث:

* `009eefc` — أول 10 أحرف من المفتاح السري لنظام الدفع
* `_success` — نتيجة معالجة الطلب (دفع ناجح)
* `618117` — معرّف منتج الاشتراك

<div data-with-frame="true"><figure><img src="/files/cbb104314e3d53a0971346c8181b25a4e0fab55b" alt=""><figcaption><p>مثال على كولباك من Prodamus للمنتجات ذات الاشتراك التلقائي</p></figcaption></figure></div>

**خطأ في الدفع**\
عند حدوث خطأ أثناء تنفيذ الدفع إلى الروبوت **يصل كولباك تلقائيًا** والذي يتكون من أول 10 أحرف من المفتاح السري لنظام الدفع، `_fail` وكلمة ومبلغ الدفع.

مثلًا: `ovg58keefc_fail 44`، حيث:

* `ovg58keefc` — أول 10 أحرف من المفتاح السري لنظام الدفع
* `_fail` — نتيجة معالجة الطلب (لم يتم الدفع أو حدث خطأ)
* `44` — مبلغ الدفع

{% hint style="warning" %}
ذلك يعتمد على نظام الدفع. ليست كل أنظمة الدفع ترسل كولباك عن فشل الدفع.
{% endhint %}

إذا كان المبلغ المحدد في إعدادات الزر يختلف عن المبلغ الذي دفعه العميل، فإلى البوت **يصل كولباك تلقائيًا** سيصل. وهو يتكون من أول 10 أحرف من المفتاح السري لنظام الدفع، `_different_amounts` وكلمة ومعرّف الدفع الفريد.

مثلًا: `ovg58keefc_different_amounts 123456`، حيث:

* `ovg58keefc` — أول 10 أحرف من المفتاح السري لنظام الدفع
* `_different_amounts` — نتيجة معالجة الطلب (مبلغ الدفع يختلف عن المبلغ في الرابط)
* `123456` — معرّف الدفع الفريد

## في الآلة الحاسبة `get_prodamus_payment_url` دالة

لإنشاء رابط للدفع **في كتلة الآلة الحاسبة `get_prodamus_payment_url` الدالة** يمكن استخدامها.\
**في حقل الآلة الحاسبة** نُسنِد للمتغير قيمة هذه الدالة: `get_prodamus_payment_url`.&#x20;

{% hint style="info" %}
اسم المتغير تختاره بنفسك. وتعرض لقطات الشاشة أمثلة على تسمية المتغيرات.
{% endhint %}

سيُكتب في هذا المتغير رابط الدفع. ويمكن عرض المتغير في الرسالة كرابط أو وضعه على زر يحمل النص «دفع».

**مثال على رابط الدفع:** [https://payform.kz/7p3JR8/](https://payform.ru/7p3JR8/)

{% tabs %}
{% tab title="الآلة الحاسبة" %}
مثال 1:

<figure><img src="/files/f5273515cd0eb1cbc43a9867a42dce6b2b5c979d" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="وصف المعلمات" %}
&#x20;`your_variable =`` `**`get_prodamus_payment_url(amount, product_name, expired, customer_phone, customer_email, discount, description, extra_params, products_for_receipt)`**

معلمات الدالة:

<table><thead><tr><th width="253">المعلمة</th><th>قيمة المعلمة</th></tr></thead><tbody><tr><td><strong><code>amount</code></strong></td><td><strong>مبلغ الدفع</strong> — يمكن تمريره كعدد صحيح أو كعدد باستخدام النقطة. مثلًا: <code>25</code> أو <code>52.5</code>. (معلمة إلزامية)</td></tr><tr><td><strong><code>product_name</code></strong></td><td><strong>اسم المنتج</strong> (معلمة إلزامية)</td></tr><tr><td><strong><code>expired</code></strong></td><td><p><strong>مدة صلاحية رابط الدفع</strong> — <code>dd.mm.yyyy</code> بالصيغة (مثلًا، 25.01.2021).<br>كما يمكن أيضًا، <strong>الآلة الحاسبة</strong> في حقل expired تحديد:<br><code>expired = current_date + 2</code> (سيكون الرابط صالحًا لمدة يومين حتى 00:00).</p><p>كما يمكن تحديد وقت دقيق: <code>dd.mm.yyyy hh:mm</code> (مثلًا، 25.01.2021 12:23).</p><p>يمكن أيضًا استخدام المتغيرات القياسية، مثلًا ضبط صلاحية الرابط لمدة 30 دقيقة:</p><pre class="language-python"><code class="lang-python">time = current_time + 30
expired = "#{current_date} #{time}"
</code></pre><p>إذا أردت تخطي هذه المعلمة، فيمكنك بدلًا منها تمرير علامة اقتباس مفردة أو علامات اقتباس مزدوجة أو <code>None</code> قيمة.</p></td></tr><tr><td><strong><code>customer_phone</code></strong></td><td><strong>رقم هاتف المشتري</strong> — اختياري، إذا كانت <code>customer_email</code> المعلمة مذكورة.<br>إذا أردت تخطي هذه المعلمة، فيمكنك بدلًا منها تمرير علامة اقتباس مفردة أو علامات اقتباس مزدوجة.</td></tr><tr><td><strong><code>customer_email</code></strong></td><td><strong>عنوان Email للمشتري</strong> — اختياري، إذا كانت <code>customer_phone</code> المعلمة مذكورة.<br>إذا أردت تخطي هذه المعلمة، فيمكنك بدلًا منها تمرير علامة اقتباس مفردة أو علامات اقتباس مزدوجة.</td></tr><tr><td><strong><code>discount</code></strong></td><td><strong>مقدار الخصم</strong> — يمكن تمرير المعلمة كعدد صحيح أو كعدد مع نقطة: <code>25</code> أو <code>63.5</code>.<br>إذا أردت تخطي هذه المعلمة، فيمكنك بدلًا منها تمرير علامة اقتباس مفردة أو علامات اقتباس مزدوجة.</td></tr><tr><td><strong><code>description</code></strong></td><td><strong>وصف المنتج</strong> (إذا لم يُذكر، فسيتم تلقائيًا <code>'دفع الفاتورة order_id'</code> تعبئته).<br>إذا أردت تخطي هذه المعلمة، فيمكنك بدلًا منها تمرير علامة اقتباس مفردة أو علامات اقتباس مزدوجة.</td></tr><tr><td><strong><code>extra_params</code></strong></td><td><p><strong>معلمات إضافية</strong>، وهي المعلمات غير الموجودة في هذه الدالة.<br>يمكن الاطلاع على المعلمات الإضافية المتاحة في توثيق العمل مع API نظام الدفع: <a href="https://help.prodamus.ru/payform/integracii/rest-api/instrukcii-dlya-samostoyatelnaya-integracii-servisov">Prodamus REST API</a></p><p>مثلًا:</p><pre class="language-python"><code class="lang-python">extra_params = {"payments_limit": "3", "payment_method": "vsegdada_installment_0_0_6"}
</code></pre><p>إذا أردت تخطي هذه المعلمة، فيمكنك بدلًا منها تمرير علامة اقتباس مفردة/مزدوجة أو <code>None</code> قيمة.</p></td></tr><tr><td><strong><code>products_for_receipt</code></strong> </td><td><p><strong>سلسلة من 50 إلى 4000 حرف</strong> بالصيغة <code>"وصف الطلب - السعر - رابط المورد الذي يتم شراؤه"</code>.<br>مثلًا:<br><code>“دورة «صيد البريَم»، السعر 4999 روبل، رابط صفحة الدورة: https://www.lovilescha.ru/courses/poimai_kilogram/"</code></p><p>هذه المعلمة إلزامية إذا لم تكن لديك آلة تسجيل نقدي إلكترونية خاصة بك، وهي مطلوبة لإضفاء الطابع الضريبي على الدفع عبر Prodamus.</p></td></tr></tbody></table>
{% endtab %}

{% tab title="مثال" %}
extra\_params = {"payments\_limit": "3"}&#x20;

products\_for\_receipt = "دورة «صيد البريَم»، السعر 4999 تنغي، رابط صفحة الدورة: <https://www.lovilescha.ru/courses/poimai\\_kilogram/"&#x20>;

link\_prodamus\_url = get\_prodamus\_payment\_url( 4999, 'دورة «صيد البريَم»', '27.03.2023 17:00', '79167777771', '<mail@mail.com>', 20, 'أفضل دورة في السوق', extra\_params, products\_for\_receipt

في هذا المثال:

* `extra_params` — معلمات إضافية (مثل حدّ المدفوعات).
* `products_for_receipt` — معلومات عن المنتج التي ستظهر في الإيصال.
* `get_prodamus_payment_url` يتم إنشاء رابط الدفع باستخدام الدالة.
  {% endtab %}
  {% endtabs %}

{% hint style="warning" %}
إذا كانت هناك عدة دوال للحصول على الرابط في الكتلة وحدث خطأ، فتُكتب قيمة الخطأ **`error_payment_func`** في المتغير.

يُسجَّل الخطأ في الآلة الحاسبة وفق الدالة الأخيرة.
{% endhint %}

## `payment_sum` إنشاء الرابط عبر المتغير والمعلمات الإضافية

{% hint style="info" %}
**انتبه:** `payment_sum` تُمرَّر القيمة إلى المتغير من المتغير الأخير، أي بعد المتغيرات الاختيارية: `payment_description`, `product_name` إلخ.
{% endhint %}

لإنشاء رابط للدفع **في حقل الآلة الحاسبة `payment_sum` يكفي فقط تعيين قيمة المتغير**.\
بعد ذلك تلقائيًا **`prodamus_pay_url`** سيظهر المتغير.

**مثال على رابط الدفع:** `https://payform.ru/7p3JR8/`

يمكن عرض هذا المتغير في الرسالة كرابط أو وضعه على زر يحمل النص «دفع».

`payment_sum` قبل التصريح بالمتغير يمكن تحديد المتغيرات الاختيارية التالية:

| معلمات الدالة              | وصف المعلمة                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **product\_name**          | **اسم المنتج** (إذا لم يُذكر، فسيُملأ تلقائيًا بـ "دفع الفاتورة order\_id") — يوضّح المخطط أدناه أين يظهر ذلك.                                                                                                                                                                                                                                                                      |
| **payment\_description**   | **وصف المنتج** (إذا لم يُذكر، فسيتم تلقائيًا `'دفع الفاتورة order_id'` يُملأ) — يوضّح المخطط أدناه أين يظهر ذلك.                                                                                                                                                                                                                                                                    |
| **discount\_value**        | **مقدار الخصم** (مثلًا، `discount_value = 25` أو `discount_value = 50.25`)                                                                                                                                                                                                                                                                                                          |
| **customer\_phone**        | **رقم هاتف المشتري** — اختياري، إذا كانت معلمة أخرى مذكورة.                                                                                                                                                                                                                                                                                                                         |
| **customer\_email**        | عنوان Email للمشتري                                                                                                                                                                                                                                                                                                                                                                 |
| **link\_expired**          | <p><strong>مدة صلاحية رابط الدفع</strong> — <code>dd.mm.yyyy</code> بالصيغة (مثلًا، 25.01.2021).<br>كما يمكن أيضًا، <strong>الآلة الحاسبة</strong> في حقل expired تحديد:<br><code>link\_expired = current\_date + 2</code> (سيكون الرابط صالحًا لمدة يومين حتى 00:00).</p>                                                                                                          |
| **link\_expired**          | <p>كما يمكن تحديد وقت دقيق، الصيغة: <code>dd.mm.yyyy hh:mm</code> (مثلًا، <code>25.01.2021 12:23</code>).<br>كما يمكن استخدام المتغيرات القياسية، مثلًا ضبط مدة صلاحية الرابط لمدة 30 دقيقة:<br>time = current\_time + 30 link\_expired = "#{current\_date} #{time}"</p>                                                                                                            |
| **currency**               | <p><strong>عملة الدفع</strong>، افتراضيًا <code>"rub"</code>.<br>القائمة الكاملة للوسائط:</p><ul><li><code>rub</code></li><li><code>usd</code></li><li><code>eur</code></li><li><code>kzt</code></li></ul><p>يجب تمرير هذه المعلمة بحروف صغيرة.</p>                                                                                                                                 |
| **payment\_title**         | <p><strong>عنوان الدفع</strong> (حتى 127 حرفًا). إذا لم يُذكر، فسيُملأ تلقائيًا بالنص التالي:<br>“<strong>دفع الفاتورة payment\_id</strong>” (<code>payment\_id</code> — معرّف الطلب في MaviBot).</p>                                                                                                                                                                               |
| **payment\_description**   | **وصف موجز للدفع** (حتى 127 حرفًا)                                                                                                                                                                                                                                                                                                                                                  |
| **locale**                 | <p><strong>لغة صفحة الدفع</strong> — <code>en-US</code>, <code>fr-XC</code> ويُعرض بصيغة وما إلى ذلك. القيمة الافتراضية هي <code>ru-RU</code>.<br>يمكن الاطلاع على القائمة الكاملة عبر الرابط التالي</p>                                                                                                                                                                            |
| **products\_for\_receipt** | <p><strong>سلسلة من 50 إلى 4000 حرف</strong> بالصيغة <code>"وصف الطلب - السعر - رابط المورد الذي يتم شراؤه"</code>.<br>مثلًا:<br><code>“دورة ‘اصطياد البِليَش’، السعر 4999 تينغي، رابط صفحة الدورة: <https://www.lovilescha.ru/courses/poimai_kilogram/>"</code></p><p>هذا معامل إلزامي، وهو مطلوب لتمكين فَسْقلة الدفع عبر Prodamus إذا لم يكن لديك صندوق دفع إلكتروني خاص بك.</p> |
| **payment\_sum**           | (إلزامي) مبلغ الدفع                                                                                                                                                                                                                                                                                                                                                                 |

<div data-with-frame="true"><img src="https://lh3.googleusercontent.com/3FazAmQkph5i0_iKy4G_HNerzVQP9Bg3_PRB_5rHZQ6vAZB_1Hxv1imi3gJCl7pU_GY7eAiiwZExJA-i4Ps5PgSJt7OXKbSL-GT27gWca_u7rFM8YEsNJ7Z-VVXTAR-jSw_-p2I0" alt="" width="563"></div>

{% hint style="success" %}
`discount_value`, `customer_phone`, `customer_email` و `link_expired` تكون المتغيرات ذات صلة أيضًا بالاشتراكات.
{% endhint %}

<div data-with-frame="true"><figure><img src="/files/48c9356f05b9d6906e114bf03db7e6a0d2d16e38" alt="" width="524"><figcaption></figcaption></figure></div>

**مثال على التنفيذ.**\
في الكتلة الأولى نحدد مبلغ الدفع:

<div data-with-frame="true"><figure><img src="/files/abf1c61263732aeb237e5555110360e6f60b5e28" alt=""><figcaption></figcaption></figure></div>

في الخطوة التالية، عند الحاجة، **`prodamus_pay_url`** نُخرج رابط

<div data-with-frame="true"><figure><img src="/files/4f064e0fcf671d84f1515f71aacb406cec7e031c" alt=""><figcaption></figcaption></figure></div>

**`prodamus_available_payment_methods`** المتغير **`payment_sum`** يُحدَّد قبل النشر.\
القيم الممكنة:

<table><thead><tr><th width="323"></th><th></th></tr></thead><tbody><tr><td><strong>AC</strong></td><td>الدفع باستخدام بطاقة صادرة في روسيا</td></tr><tr><td><strong>ACkz</strong> </td><td>الدفع عبر بطاقة كازاخستان</td></tr><tr><td><strong>ACf</strong></td><td>الدفع عبر بطاقات دول رابطة الدول المستقلة، باستثناء روسيا</td></tr><tr><td><strong>ACEURNMBX</strong></td><td>الدفع عبر بطاقات EUR من جميع الدول، باستثناء روسيا وبيلاروس</td></tr><tr><td><strong>SBP</strong></td><td>دفع سريع دون إدخال بيانات البطاقة. لبطاقات روسيا</td></tr><tr><td><strong>QW</strong> </td><td>محفظة Qiwi </td></tr><tr><td><strong>PC</strong></td><td>ЮMoney</td></tr><tr><td><strong>GP</strong></td><td>محطة دفع</td></tr><tr><td><strong>sbol</strong></td><td>سبيربنك أونلاين </td></tr><tr><td><strong>invoice</strong> </td><td>الدفع عبر الفاتورة</td></tr><tr><td><strong>installment</strong> </td><td>تقسيط عبر Prodamus</td></tr><tr><td><strong>installment_5_21</strong></td><td>تقسيط لمدة 3 أشهر عبر Prodamus</td></tr><tr><td><strong>installment_6_28</strong></td><td>تقسيط لمدة 6 أشهر عبر Prodamus</td></tr><tr><td><strong>installment_10_28</strong></td><td>تقسيط لمدة 10 أشهر عبر Prodamus</td></tr><tr><td><strong>installment_12_28</strong> </td><td>تقسيط لمدة 12 شهرًا عبر Prodamus</td></tr><tr><td><strong>installment_0_0_3</strong></td><td>تقسيط لمدة 3 أشهر عبر Tinkoff</td></tr><tr><td><strong>installment_0_0_4</strong> </td><td>تقسيط لمدة 4 أشهر عبر Tinkoff</td></tr><tr><td><strong>installment_0_0_6</strong></td><td>تقسيط لمدة 6 أشهر عبر Tinkoff</td></tr><tr><td><strong>installment_0_0_10</strong></td><td>تقسيط لمدة 10 أشهر عبر Tinkoff</td></tr><tr><td><strong>installment_0_0_12</strong></td><td>تقسيط لمدة 12 شهرًا عبر Tinkoff</td></tr><tr><td><strong>installment_0_0_24</strong> </td><td>تقسيط لمدة 24 شهرًا عبر Tinkoff</td></tr><tr><td><strong>installment_0_0_36</strong></td><td>تقسيط لمدة 36 شهرًا عبر Tinkoff</td></tr><tr><td><strong>credit</strong> </td><td>قرض عبر Tinkoff</td></tr><tr><td><strong>vsegdada_installment_0_0_4</strong></td><td><strong>تقسيط لمدة 4 أشهر عبر “ВсегдаДа”</strong> (لا يعمل مع available_payment_methods)</td></tr><tr><td>vs<strong>egdada_installment_0_0_6</strong></td><td><strong>تقسيط لمدة 6 أشهر عبر “ВсегдаДа”</strong> </td></tr><tr><td><strong>vsegdada_installment_0_0_10</strong></td><td><strong>تقسيط لمدة 10 أشهر عبر “ВсегдаДа”</strong> </td></tr><tr><td><strong>vsegdada_installment_0_0_12</strong></td><td><strong>تقسيط لمدة 12 شهرًا عبر “ВсегдаДа”</strong> </td></tr><tr><td>vs<strong>egdada_installment_0_0_24</strong></td><td><strong>تقسيط لمدة 24 شهرًا عبر “ВсегдаДа”</strong> </td></tr><tr><td><strong>vsegdada_installment_0_0_36</strong> </td><td><strong>تقسيط لمدة 36 شهرًا عبر “ВсегдаДа”</strong> </td></tr><tr><td><strong>sbrf_installment_0_0_6</strong></td><td>تقسيط لمدة 6 أشهر عبر سبيربنك</td></tr><tr><td><strong>sbrf_installment_0_0_10</strong></td><td>تقسيط لمدة 10 أشهر عبر سبيربنك</td></tr><tr><td><strong>sbrf_installment_0_0_12</strong></td><td>تقسيط لمدة 12 شهرًا عبر سبيربنك</td></tr><tr><td><strong>sbrf_installment_0_0_24</strong></td><td>تقسيط لمدة 24 شهرًا عبر سبيربنك</td></tr><tr><td><strong>sbrf_installment_0_0_36</strong> </td><td>تقسيط لمدة 36 شهرًا عبر سبيربنك</td></tr><tr><td><strong>otp_installment_0_0_6</strong></td><td>تقسيط لمدة 6 أشهر عبر بنك OTP</td></tr><tr><td><strong>otp_installment_0_0_10</strong></td><td>تقسيط لمدة 10 أشهر عبر بنك OTP</td></tr><tr><td><strong>otp_installment_0_0_12</strong> </td><td>تقسيط لمدة 12 شهرًا عبر بنك OTP</td></tr><tr><td><strong>otp_installment_0_0_24</strong></td><td>تقسيط لمدة 24 شهرًا عبر بنك OTP</td></tr><tr><td><strong>otp_installment_0_0_36</strong></td><td>تقسيط لمدة 36 شهرًا عبر بنك OTP</td></tr><tr><td><strong>mts_installment_0_0_6</strong></td><td>تقسيط لمدة 6 أشهر عبر بنك MTS</td></tr><tr><td><strong>mts_installment_0_0_10</strong> </td><td>تقسيط لمدة 10 أشهر عبر بنك MTS</td></tr><tr><td><strong>mts_installment_0_0_12</strong> </td><td>تقسيط لمدة 12 شهرًا عبر بنك MTS</td></tr><tr><td><strong>mts_installment_0_0_24</strong></td><td>تقسيط لمدة 24 شهرًا عبر بنك MTS</td></tr><tr><td> <strong>mts_installment_0_0_36</strong> </td><td>تقسيط لمدة 36 شهرًا عبر بنك MTS</td></tr><tr><td><strong>monetaworld</strong></td><td>بطاقات البنوك العالمية، باستثناء روسيا</td></tr><tr><td><strong>sbrf_bnpl</strong></td><td>تقسيط عبر سبير</td></tr></tbody></table>

متعدد القيم **بواسطة الخط العمودي** مسموح بالتقسيم.\
مثال:

```python
prodamus_available_payment_methods = "AC|PC|QW"
```

`prodamus_currency` – هذا معامل إضافي آخر يتيح عرض المبلغ بعملة محددة.

العملات الممكنة:

* `kzt` – للِّينغي
* `eur` – لليورو
* `usd` – للدولار

وبالتالي، يكون المبلغ المعروض في الرابط بالعملة المختارة.

**ردّ النداء `payment_callback` عند استلام** `currency` و `currency_sum` يجب الانتباه إلى المعاملات، حيث يتم تحديد العملة والمبلغ فيها.

{% hint style="warning" %}
إذا لم يتم تحديده، فسينتقل إلى صفحة لا تحتوي على طرق دفع.\
يمكن إضافة طرق الدفع عبر التفعيل. ويمكن الاطلاع على الطرق المفعلة من إعدادات الصفحة أو من خلال اختبار رابط الدفع.
{% endhint %}

<div data-with-frame="true"><figure><img src="/files/20fa41bd47b142adba917aad2c8d053bc4f328f5" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/5dda410fe7e68f37a3672657eb4a3bde99e84826" alt="" width="563"><figcaption></figcaption></figure></div>

### كيفية معالجة النتيجة

**دفع ناجح**

**مهم:** بعد الدفع الناجح أو الفاشل تصل إلى البوت ردود نداء (callbacks) يمكنك من خلالها تحديد ما إذا كانت عملية الدفع قد تمت بنجاح.

تظهر ردود النداء في النظام مثل رسائل المستخدم، لكن لا يمكن للمستخدم إرسالها. وتكون على شكل مفتاح سري مع الحالة. مثال:

```
453e8fba8b7cef9ce58dc6e18e25b39ad5a05748175a3f205f2b084acbfc3b66_success
```

أو

```
453e8fba8b7cef9ce58dc6e18e25b39ad5a05748175a3f205f2b084acbfc3b66_fail
```

بعد الدفع الناجح **prodamus\_payment\_completed** يأخذ المتغير `True` القيمة.

**ملاحظة:** تصل ردود النداء متأخرة قليلًا، لذلك من الأفضل إرسال رسالة إلى المستخدم بعد إرسال الرابط:

> “بعد إجراء الدفع، يرجى انتظار اكتمال عملية الدفع بنجاح.”

***

**بنية ردّ النداء**

بالنسبة للروابط التي تُنشأ عبر زر الدفع أو عبر دالة في الحاسبة، يصل إلى البوت ردّ نداء تلقائي بعد الدفع. ويتكون من:

```
<المفتاح_السري>_success <مبلغ_الدفع>
```

مثلًا:

```
ovg58keefc_success
```

* `ovg58keefc` – المفتاح السري الكامل لنظام الدفع
* `_success` — نتيجة معالجة الطلب (دفع ناجح)

***

**استخدام عملي**

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

<div data-with-frame="true"><figure><img src="/files/33ae6216c14f2d69b5d4bd1251e8a3691d94c10b" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="danger" %}
يجب أن يكون نوع المقارنة "Full match" / "مطابقة تامة"

لإجراء الدفع مرة أخرى، يجب بالضرورة **payment\_sum** تصفير المتغير وحذف الرابط الذي تم إنشاؤه سابقًا. عندها فقط **payment\_sum** يمكن تعيين قيمة جديدة للمتغير والحصول على الرابط المحدّث.
{% endhint %}

#### إلغاء تفعيل الاشتراك / إعادة تفعيله

كما توجد في نظام Prodamus إشعارات حول تفعيل الاشتراك أو إيقافه:

<div data-with-frame="true"><figure><img src="/files/c9f7581c30c9303a2aa549568006ad25db80985b" alt=""><figcaption></figcaption></figure></div>

**«الاشتراك أوقفه المستخدم»** – إذا أُوقِف الاشتراك يدويًا (مثلًا عند إلغاء الاشتراك).\
قد تصل هذه الرسالة قبل انتهاء الفترة المدفوعة الحالية. ويعتمد الإجراء على قرارك: تجاهلها، أو أخذها في الاعتبار، أو محاولة استرجاع المستخدم.

**«أعاد المستخدم تفعيل الاشتراك»** – تم استعادة الاشتراك.\
قد تصل هذه الرسالة إذا أعاد المستخدم تفعيل الاشتراك قبل انتهاء الفترة المدفوعة الحالية. ويعتمد الإجراء على قرارك: تجاهلها أو إخراج المستخدم من قائمة المراقبة.

**«إلغاء تفعيل الاشتراك»** – في حال إيقاف الاشتراك بعد عدة محاولات دفع فاشلة.

### حفظ القيم من ردّ النداء

بعد وصول إشعار الدفع الناجح **payment\_callback** يُكتب ردّ النداء من Prodamus إلى المتغير، ويحتوي على جميع بيانات الدفع. يمكن حفظ هذه البيانات واستخدامها بالطريقة التي تناسبك.

مثال على ردّ النداء:

```json
{
  "date": "2021-03-30T11:44:43+03:00",
  "order_id": "757679",
  "order_num": "",
  "domain": "demo.payform.ru",
  "sum": "14.50",
  "customer_phone": "+77777777777",
  "customer_extra": "منتج",
  "payment_type": "بطاقة بلاستيكية Visa, MasterCard, MIR",
  "commission": "3.5",
  "commission_sum": "0.51",
  "attempt": "1",
  "discount_value": "10.5",
  "products[0][name]": "الوصول إلى المواد التعليمية",
  "products[0][price]": "14.50",
  "products[0][quantity]": "1",
  "products[0][sum]": "14.50",
  "payment_status": "success",
  "payment_status_description": "دفع ناجح",
  "payment_init": "manual"
}
```

عند إنشاء الرابط **product\_name** و **payment\_description** يمكن إظهار المتغيرات. وعند وصول ردّ النداء يمكن الحصول عليها كما يلي:

```python
product = get(payment_callback,'products[0][name]')
description = get(payment_callback,'customer_extra')
```

<div data-with-frame="true"><figure><img src="/files/ece5b5828deb73a42ac58a4ca66c3e74477a5857" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
انتبه: **payment\_sum** يُعطى المتغير القيمة الأخيرة، وهي **من المتغيرات غير الإلزامية** وتأتي بعده: **payment\_description**, **product\_name**.
{% endhint %}

يمكن الحصول على المبلغ كما يلي:

```python
summa = get(payment_callback, 'sum')
```

### **ردود النداء المتاحة**

إلى جانب ردود النداء الأساسية للدفع الناجح، تصل في المحادثة رسائل لا يراها المستخدم، وهي:

<details>

<summary>ردود النداء</summary>

* ألغى المشترك الاشتراك ([المزيد هنا](#deaktivaciya-reaktivaciya-podpiski))
* أعاد المشترك تفعيل الاشتراك ([المزيد هنا](#deaktivaciya-reaktivaciya-podpiski))
* تم إنهاء الاشتراك
* دفع غير ناجح - مع ملاحظة توضيحية (كما في لقطة الشاشة أعلاه)
* إشعار بعملية خصم قادمة - تاريخ ووقت الخصم القادم
* طلب تقسيط بحالة

</details>

<details>

<summary><strong>أمثلة على ردود النداء في محادثة مع العميل</strong></summary>

* **ألغى المشترك الاشتراك**
* **أعاد المشترك تفعيل الاشتراك**
* **تم إنهاء الاشتراك**
* **دفع غير ناجح - لا توجد أموال كافية.**
* **دفع غير ناجح - انتهت صلاحية البطاقة.**
* **دفع غير ناجح - تم تجاوز الحد الأقصى للبطاقة.**
* **دفع غير ناجح - البطاقة مفقودة**
* **دفع غير ناجح - خطأ في النظام**&#x20;
* **دفع غير ناجح - العملية مرفوضة. يرجى التواصل مع البنك المُصدر للبطاقة.**&#x20;
* **دفع غير ناجح - رفض البنك المُصدر تنفيذ العملية.**
* **دفع غير ناجح - رفض البنك تنفيذ العملية.**&#x20;
* **إشعار بعملية خصم قادمة - dd.mm.yyyy hh:mm**
* **تمت الموافقة على طلب التقسيط**
* **تم إلغاء طلب التقسيط**
* **تم رفض طلب التقسيط**

</details>

يمكنك، حسب رغبتك، إعداد إرسال أي رسالة للمستخدم. مثلًا، إرسال إشعار عند فشل الدفع التلقائي.

يمكن إعداد كتل الرد على الرسالة الخاصة بسبب محدد لفشل الدفع كما يلي:

<div data-with-frame="true"><figure><img src="/files/af76dabccd014aef3124ed1286ed140758bc9a3f" alt=""><figcaption></figcaption></figure></div>

يمكن إعداد إرسال رسالة إلى جميع عمليات الدفع الفاشلة، بغض النظر عن السبب، كما يلي:

<div data-with-frame="true"><figure><img src="/files/4a32875a5e6177c59100bba2a6de0b1df2ba76d1" alt=""><figcaption></figcaption></figure></div>

في جميع ردود النداء، إذا كان النص **«فشل الدفع»** فسيتم إرسال رسالة إلى المستخدم بالنص الذي تحدده.

## **كيفية الدفع بالاشتراك**

### **كيفية إنشاء اشتراك**

لإنشاء اشتراك، يجب أولًا **إنشاء منتج اشتراك** .\
تعليمات كاملة: [كيفية إنشاء الاشتراك وإعداده](https://help.prodamus.ru/payform/rekurrent-i-kluby/kak-sozdat-i-nastroit-podpiski)

ثم ننسخ **المعرّف** لمنتج الاشتراك. مثال، أدناه موضح من أين يمكن الحصول عليه:

<div data-with-frame="true"><img src="https://lh5.googleusercontent.com/YuaI5KhrMPHNozN0JNOE9kD_Jcw7a8LE6GigaM0vrVtmsDBvlHvK8GCX5IcNvaJuSQE8iWWYl0KCgR5JpYpcp9Sa2531RGDYWVLjhE72ipScrpodUWeb4KDrECRbBhz4kO-3lMvs" alt="إنشاء منتج اشتراك"></div>

لإنشاء رابط دفع الاشتراك، **prodamus\_subscription** يجب تعيين متغير **المعرّف** المنتج المشترك. بعد ذلك يتم تلقائيًا **prodamus\_pay\_url** سيظهر المتغير.

<div data-with-frame="true"><figure><img src="/files/134a387da4fcc557f0cc9d7ac4b89e1d12c4f888" alt="" width="563"><figcaption></figcaption></figure></div>

ترجمة إلى اللغة الكازاخية (أسلوب رسمي):

`prodamus_pay_url` يمكن عرض المتغير كرابط على الشاشة أو وضعه على زر يحمل النص «ادفع». مثال على الرابط: <https://payform.kz/7p3JR8/>

تتم معالجة النتيجة كما في الدفع لمرة واحدة (كما قرأت أعلاه).

بعد الاشتراك الناجح، يضاف إلى المستخدم المتغير المُدخل أثناء الدفع **customer\_phone** رقم الهاتف. رقم الهاتف مطلوب لإدارة الاشتراك.

إذا لم يتم **customer\_email** فيجب أن يكون **customer\_phone** إلزاميًا لإدارة الاشتراك.

### **`get_prodamus_subscription_url` كيفية إنشاء رابط للاشتراك باستخدام الدالة**

دعونا نراجع طريقة أخرى لإنشاء رابط الدفع لمنتج الاشتراك.

1. يتم إنشاء منتج اشتراك من لوحة Prodamus.\
   يمكن الاطلاع على التعليمات الكاملة عبر الرابط التالي:\
   [كيفية إنشاء الاشتراك وإعداده](https://help.prodamus.ru/payform/rekurrent-i-kluby/kak-sozdat-i-nastroit-podpiski)
2. ثم ننسخ **المعرّف** لمنتج الاشتراك. مثال، أدناه موضح من أين يمكن الحصول عليه:

<div data-with-frame="true"><img src="https://lh5.googleusercontent.com/YuaI5KhrMPHNozN0JNOE9kD_Jcw7a8LE6GigaM0vrVtmsDBvlHvK8GCX5IcNvaJuSQE8iWWYl0KCgR5JpYpcp9Sa2531RGDYWVLjhE72ipScrpodUWeb4KDrECRbBhz4kO-3lMvs" alt="إنشاء منتج اشتراك"></div>

للحصول على رابط الدفع لمنتج الاشتراك في الحاسبة نحدد الدالة&#x20;

`get_prodamus_subscription_url`(subscription\_id, product\_name, expired, customer\_phone, customer\_email, discount, description, extra\_params, products\_for\_receipt)

{% tabs %}
{% tab title="الآلة الحاسبة" %}
**مثال 1:** رابط دفع منتج الاشتراك

<figure><img src="/files/3f8e83303a8fb76516a2fcfce2d5675fd7694745" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="وصف المعامل" %}
`link = get_prodamus_subscription_url`(subscription\_id, product\_name, expired, customer\_phone, customer\_email, discount, description, extra\_params, products\_for\_receipt)

معاملات الدالة:

<table><thead><tr><th width="253">المعلمة</th><th>قيمة المعلمة</th></tr></thead><tbody><tr><td><strong><code>subscription_id</code></strong></td><td><strong>معرّف منتج الاشتراك</strong> – يمكن نسخه من لوحة Prodamus (معامل إلزامي).</td></tr><tr><td><strong><code>product_name</code></strong></td><td><strong>اسم المنتج</strong> (معامل إلزامي).</td></tr><tr><td><strong><code>expired</code></strong></td><td><p><strong>مدة صلاحية رابط الدفع</strong> – بصيغة dd.mm.yyyy (مثلًا: 25.01.2021).</p><p>يمكن أيضًا تحديده في حقل «الحاسبة»:</p><pre class="language-python"><code class="lang-python">expired = current_date + 2  # سيكون الرابط صالحًا لمدة يومين حتى الساعة 00:00
</code></pre><p><code>expired</code> يمكن أيضًا تحديد المعامل بوقت محدد، بصيغة: dd.mm.yyyy hh:mm (مثلًا: 25.01.2021 12:23).</p><p>يمكن أيضًا استخدام المتغيرات القياسية، مثل ضبط صلاحية الرابط لمدة 30 دقيقة:</p><pre class="language-python"><code class="lang-python">time = current_time + 30
expired = "#{current_date} #{time}"
</code></pre><p>إذا أردت تجاهل هذا المعامل، فضع بدلًا منه علامة اقتباس مفردة أو مزدوجة، أو <code>None</code> قيمة.</p></td></tr><tr><td><strong><code>customer_phone</code></strong></td><td><p><strong>رقم هاتف من يقوم بالدفع</strong> — اختياري، إذا كانت <code>customer_email</code> إذا تم تحديد المعامل.</p><p>إذا أردت تجاهل هذا المعامل، فضع بدلًا منه علامة اقتباس مفردة أو مزدوجة.</p></td></tr><tr><td><strong><code>customer_email</code></strong></td><td><p><strong>البريد الإلكتروني لمن يقوم بالدفع</strong> — اختياري، إذا كانت <code>customer_phone</code> إذا تم تحديد المعامل.</p><p>إذا أردت تجاهل هذا المعامل، فضع بدلًا منه علامة اقتباس مفردة أو مزدوجة.</p></td></tr><tr><td><strong><code>discount</code></strong></td><td><p><strong>مقدار الخصم</strong> – يمكن تمرير المعامل كعدد صحيح أو عشري: 25 أو 63.5.</p><p>إذا أردت تجاهل هذا المعامل، فضع بدلًا منه علامة اقتباس مفردة أو مزدوجة.</p></td></tr><tr><td><strong><code>description</code></strong></td><td><p><strong>وصف المنتج</strong> – إذا لم يُحدَّد، فسيُملأ افتراضيًا <code>'دفع الفاتورة order_id'</code> .</p><p>إذا أردت تجاهل هذا المعامل، فضع بدلًا منه علامة اقتباس مفردة أو مزدوجة.</p></td></tr><tr><td><strong><code>extra_params</code></strong></td><td><p><strong>معلمات إضافية</strong>، وهي المعاملات غير الموجودة في هذه الدالة.<br>يمكن الاطلاع على المعاملات الإضافية الممكنة في توثيق API لنظام الدفع:<br><a href="https://help.prodamus.ru/payform/integracii/rest-api/instrukcii-dlya-samostoyatelnaya-integracii-servisov">دليل Prodamus REST API</a></p><p><strong>مثال:</strong></p><pre class="language-python"><code class="lang-python">extra_params = {"payments_limit": "3"}
</code></pre><p>إذا أردت تجاهل هذا المعامل، فضع بدلًا منه علامة اقتباس مفردة/مزدوجة أو <code>None</code> قيمة.</p></td></tr><tr><td><strong><code>products_for_receipt</code></strong> </td><td><p><strong>سلسلة من 50 إلى 4000 حرف</strong>، بصيغة: <code>"وصف الطلب - السعر - رابط المورد الذي يتم شراؤه"</code></p><p>مثال:<br>دورة «دورة صيد البِليَش»، السعر 4999 تينغي، رابط صفحة الدورة: <a href="https://www.lovilescha.ru/courses/poimai_kilogram/">https://www.lovilescha.ru/courses/poimai_kilogram/</a>.</p><p>هذا المعامل <strong>إلزامي</strong>، وهو مطلوب لتمكين فَسْقلة المدفوعات عبر Prodamus إذا لم يكن لديك صندوق دفع إلكتروني خاص بك.</p></td></tr></tbody></table>
{% endtab %}

{% tab title="مثال على كود للنسخ" %}
extra\_params = {"payments\_limit": "3"}&#x20;

products\_for\_receipt = "دورة ‘دورة صيد البِليَش’، سعر الاشتراك الشهري 2000 تينغي، رابط صفحة الدورة: <https://www.lovilescha.ru/courses/poimai\\_kilogram/"&#x20>;

link\_prodamus\_sub = get\_prodamus\_subscription\_url(618988, 'دورة ‘دورة صيد البِليَش’', '27.03.2023 17:02', '79167777771', '<mail@mail.com>', 20, 'أفضل دورة في السوق', extra\_params, products\_for\_receipt)
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
إذا حدث خطأ في الكتلة عند الحصول على الرابط عبر عدة دوال، **قيمة الخطأ `error_payment_func` إلى المتغير** تُكتب.

يُسجَّل الخطأ في الآلة الحاسبة وفق الدالة الأخيرة.
{% endhint %}

### **كيفية إدارة حالة الاشتراك**

هذه الطريقة مخصصة للاشتراكات الفعلية فقط، ولا توجد ربطات بطاقات في الوضع التجريبي.

لإدارة الاشتراك، يجب بالضرورة **`customer_phone`** أو **`customer_email`** أن يكون أحد المعاملات

لإخراج المستخدم من الاشتراك، يجب إنشاء كتلة واستدعاء الدالة التالية:\
[delete\_subscription\_prodamus](https://store.salebot.pro/function/delete_subscription_prodamus)

**مثال على المعلمات:**

```json
{
  "customer_phone": "#{customer_phone}",
  "id_subscription":"#{prodamus_subscription}",
  "url":"https://demo.payform.ru/",
  "secret_key":"453e8fba8b7cef9ce58dc6e18e25b39ad5a05748175a3f205f2b084acbfc3b66",
  "switcher":"0",
  "profile_id":"12345"
}
```

* `url` – URL نموذج الدفع، مأخوذ من الإعدادات في المنشئ
* `secret_key` – المفتاح السري المأخوذ من الإعدادات
* `id_subscription` – معرّف منتج الاشتراك
* `customer_phone` – هاتف مالك الاشتراك
* `switcher` – إدارة الاشتراك: `0` – إيقاف الاشتراك، `1` – إعادة تفعيل الاشتراك
* `profile_id` – معرّف الملف الشخصي في نظام بروداموس

**ملاحظة:**\
إذا كان معرّف الملف الشخصي واردًا، فسيتم **`profile_id`** تخزينه في المتغير.\
`profile_id` إلى الدالة **`customer_phone`** أو **`customer_email`** ويمكن تمريره بدلاً من ذلك لإيقاف الاشتراك.

**مثال:** تهيئة كتل الاشتراك

<div data-with-frame="true"><figure><img src="/files/11b60967e81b50a99a7297fbba4f694500f75a7e" alt=""><figcaption></figcaption></figure></div>

يرجى ملاحظة أن الدالة **status** تعيد، ويمكنك حفظها ومعالجتها كما تشاء. عند الإيقاف الناجح للاشتراك أو إعادة تفعيله، **status = ok** يمكن أن يكون.

### دالة لإدارة الاشتراك

prodamus\_subscription\_switch\_status(subscription\_id, switcher, customer\_phone, customer\_email, profile\_id) المعلمات:

subscription\_id – معرّف منتج الاشتراك

switcher – إدارة الاشتراك: 0 – إيقاف الاشتراك، 1 – إعادة تفعيل الاشتراك

customer\_phone – هاتف مالك الاشتراك؛ اختياري، إذا تم تحديد customer\_email

customer\_email – عنوان البريد الإلكتروني لمالك الاشتراك؛ اختياري، إذا تم تحديد customer\_phone

profile\_id – معرّف الملف الشخصي في نظام بروداموس

<div data-with-frame="true"><figure><img src="/files/7b533dc156895a6936dcb90efbb049904581dfe4" alt=""><figcaption><p>مثال على استخدام الدالة prodamus_subscription_switch_status</p></figcaption></figure></div>

ترجمة إلى اللغة الكازاخية (أسلوب رسمي):

**مثال 1:** `customer_phone` تم تمرير المعلمة، `customer_email` تم تخطيها:

```python
stat = prodamus_subscription_switch_status('618117', '0', '75431312321')
```

**مثال 2:** `customer_email` تم تمرير المعلمة، `customer_phone` تم تخطيها:

```python
stat = prodamus_subscription_switch_status('618117', '0', '', 'examp@mail.com')
```

{% hint style="success" %}
إذا اكتملت جميع العمليات بنجاح، فإن الدالة **`ok`** أو تعيد وصف الخطأ في حال حدوث خطأ.
{% endhint %}

## إدارة الخصومات في الاشتراك

تقوم هذه الدالة بتعيين مقدار الخصم على الدفعات التالية للاشتراك. ويمكن أن يكون الخصم **محدودًا أو غير محدود** في عدد الدفعات.

```python
prodamus_subscription_discount(subscription_id, discount, customer_phone, num, profile_id)
```

المعلمات:

* `subscription_id` – معرّف الاشتراك
* `discount` – عدد عشري بدقة رقمين بعد الفاصلة؛ يجب أن تكون قيمته أكبر من الصفر ولا تتجاوز القيمة الأساسية للاشتراك
* `customer_phone` – رقم هاتف العميل، الصيغة: `+79999999999` (اختياري، إذا كان `customer_email` المتغير موجودًا؛ يظهر بعد الدفعة الأولى)
* `num` – عدد الدفعات التي سيُطبق عليها الخصم (اختياري؛ إذا لم يُذكر، فسيُطبق الخصم على جميع الدفعات)
* `profile_id` – معرّف الملف الشخصي في نظام بروداموس

إذا نجح تنفيذ الطلب، فإن الدالة `'ok'` ؛ وإذا حدث خطأ، فتعيد الدالة وصف الخطأ.

{% hint style="warning" %}
**لا يتم إعادة كتابة مقدار الخصم والفاصل الزمني إلا إذا تمت استدعاء الدالة مرة أخرى بقيم جديدة!**
{% endhint %}

**أمثلة:**

**1. منح خصم 1₽ على جميع المدفوعات التلقائية التالية** (لا يتم تحديد رقم الهاتف، لأنه يتم تلقائيًا `customer_phone` أخذه من المتغير؛ ويُطبق مبلغ الخصم افتراضيًا على كامل مدة الاشتراك):

```python
r = prodamus_subscription_discount('624034', '1')
```

<div data-with-frame="true"><img src="https://lh3.googleusercontent.com/_4i_sKKn39tHVdnb47xgj8fxfP_x9UGMWLaierBnpup9LCZMdVT0G9AmIOa8S_uMrVXWQIH6rvZnujCYPGcphkYvwFbCXEh819tWIjGIM4mHvd3afSlPzhZfcWk6D1z1tyBwFrZV" alt="" width="563"></div>

**2. مثال على منح خصم 2₽ على الدفعات الثلاث التالية** (يُمرَّر رقم الهاتف بين علامتي اقتباس فارغتين، لأنه يتم تلقائيًا `customer_phone` أخذه من المتغير):

```python
r = prodamus_subscription_discount('624034', '2', '', '3')
```

<div data-with-frame="true"><img src="https://lh5.googleusercontent.com/IgutVRIqTFbaof9A14qdQRLCB6oop4mSAIew5s3lz62Kb4YVHdHJEt6GuC7AACStDgRiR1d_XEG1k5Dj7c2M-VNtci16JbklMTEla8_RNWD7wBNeG649g0lnFiMZilhri3phwKr-" alt="" width="563"></div>

**3. مثال على عرض الخصم كعدد عشري** (الفاصل هو النقطة، وتُكتب القيم بدون علامات اقتباس)، ويمكن تمرير رقم الهاتف عبر متغير.

<div data-with-frame="true"><figure><img src="/files/aad255b580731d8f75627a03837abcfa99b3c342" alt="" width="563"><figcaption></figcaption></figure></div>

r = prodamus\_subscription\_discount(#{prodamus\_subscription}, 10.25, #{customer\_phone}, 3)

<div data-with-frame="true"><img src="https://lh3.googleusercontent.com/xJVbZ3Q5f6LzCsYtuX-JqaKYPc69lS6Wi4yA0ui2vBxmFkXXGIHSqgO2VoK0rzDPdNG-HxVpAnpRcmbZXQ_oSrtT7ijJcQA6ZOwjXLbKP8WsCFBip-4DwRnVHpz-fIPRt_Wldo0h" alt="" width="563"></div>

## **كيفية تعيين تاريخ الدفع التالي للاشتراك**

باستخدام هذه الطريقة، يمكن تحريك تاريخ الدفع التالي للاشتراك. ويمكن تحريك التاريخ فقط من تاريخ الدفع التالي الحالي إلى **«المستقبل»** لزيادة مدة المشاركة في النادي.

على سبيل المثال، يمكن استخدامها كمكافأة للمشتركين.

ولهذا، يجب استخدام الدالة التالية:

```python
prodamus_subscription_payment_date(subscription_id, date, customer_phone, profile_id)
```

المعلمات:

* `subscription_id` – معرّف الاشتراك
* `date` – تاريخ بصيغة dd.mm.yyyy hh:mm أو dd.mm.yyyy؛ وإذا تم تقديم dd.mm.yyyy فقط، فسيكون الوقت 00:00
* `customer_phone` – اختياري؛ إذا لم يُذكر، `customer_phone` فسيُؤخذ من المتغير؛ وإذا لم يتم العثور عليه، فلن تعمل الدالة
* `profile_id` – معرّف الملف الشخصي في نظام بروداموس

### كيفية إرسال المعلمات إلى بروداموس

لإرسال المعلمات المطلوبة (مثل تاريخ بدء الاشتراك، إيقاف التقسيط، إلخ) إلى نظام بروداموس، أضف إلى اسم المتغير **`prodamus_`** السابقة.

بعد ذلك، عند إنشاء رابط الدفع، سيتم إرسال المعلمات الموجودة في هذا المتغير تلقائيًا إلى نظام الدفع.

## كيفية اختبار الدفع

{% hint style="info" %}
نختبر الدفع فقط!
{% endhint %}

لمنع سحب الأموال من حسابك أثناء إعداد التكاملات ومسارات الدفع، **يمكنك استخدام بطاقات اختبار**.

{% hint style="warning" %}
أولاً، حوّل صفحة الدفع الخاصة بك إلى **وضع DEMO** ⤵\
ولا تنسَ الضغط على زر «حفظ».
{% endhint %}

<div data-with-frame="true"><figure><img src="/files/1925f97fbae8141bd530370a025f060197b70dc7" alt=""><figcaption></figcaption></figure></div>

#### يمكن استخدام حسابات اختبار لإجراء دفعة اختبارية.

**بطاقات سبربنك الاختبارية:**

**مير**\
رقم البطاقة: 2202 2050 0001 2424\
تاريخ الصلاحية: 05/35\
رمز التحقق على ظهر البطاقة (CVV): 669

**ماستركارد**\
رقم البطاقة: 5469 9801 0004 8525\
تاريخ الصلاحية: 05/26\
رمز التحقق على ظهر البطاقة (CVV): 041\
رمز التحقق 3-D Secure: 111111

**فيزا**\
رقم البطاقة: 4006 8009 0096 2514\
تاريخ الصلاحية: 05/26\
رمز التحقق على ظهر البطاقة (CVV): 941\
رمز التحقق 3-D Secure: 111111

{% hint style="success" %}
❗️عند الدفع باستخدام الحسابات الاختبارية، فإن جميع مسارات العمل والتكاملات المُهيأة **تعمل كما في الدفع العادي**❗️
{% endhint %}

تم التحقق من النموذج

{% hint style="danger" %}
للقبول الفعلي للمدفوعات، يجب أن تكون الواجهة **في وضع التشغيل** أي يجب ضبط مفتاح وضع العرض التجريبي على **أحمر فاتح** اللون.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/ar/integrations/payment/prodamus-blr/prodamus.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.