VibeFox Iugu for PrestaShop — المساعدة

المتطلبات

PrestaShop: من 8.0 إلى 9.x.

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

العملة: الريال البرازيلي (BRL). يتقاضى Iugu بالريال البرازيلي فقط. تُخفى طريقة الدفع للسلال بعملة أخرى، وللإجماليات الأقل من R$ 1.00 (الحد الأدنى في Iugu).

حساب Iugu: تحتاج إلى رمزي API من لوحة Iugu، أحدهما من نوع "Test" والآخر من نوع "Live" (راجع الإعدادات). يستخدم Iugu عنوان API واحدًا للاثنين: الرمز هو ما يحدد هل الفواتير اختبارية أم حقيقية. لا حاجة لإعداد أي webhook في Iugu.

مفتاح ترخيص VibeFox: يُشترى من vibefox.net. يعمل المفتاح الواحد على نطاق واحد.

التثبيت

1. في لوحة الإدارة انتقل إلى Modules > Module Manager واضغط Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع اضغط Configure، أو ابحث لاحقًا عن VibeFox Iugu Gateway في قائمة الوحدات واضغط Configure.

3. أدخل مفتاح ترخيص VibeFox في الحقل License key داخل كتلة الترخيص في أعلى صفحة الإعدادات، ثم اضغط Activate (راجع مفتاح الترخيص).

4. أدخل رمزي API للاختبار والإنتاج (راجع الإعدادات)، واترك Test mode مفعّلًا، وفعّل Enable / Disable واضغط Save.

5. أنشئ طلب اختبار وادفعه في صفحة Iugu بدفعة اختبار من Iugu. عند الجاهزية أوقف Test mode.

عند التثبيت تنشئ الوحدة حالتين للطلب: Awaiting Iugu payment وIugu payment on hold. يعرض PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences. يُعرض Iugu في كل الأحوال للسلال بالريال البرازيلي (BRL) فقط.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Iugu Gateway > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. فوق الحقول تعرض الصفحة TEST MODE (تُنشأ الفواتير برمز API للاختبار دون رسوم حقيقية) أو LIVE. وتحذّر عندما يكون رمز الوضع النشط مفقودًا (فتُخفى طريقة الدفع عندئذ في الدفع)، وعندما تكون عملة المتجر الافتراضية غير BRL (فلا يُعرض Iugu عندئذ للسلال بعملات أخرى).

Iugu

Enable / Disable: Enable Iugu payments يشغّل طريقة الدفع أو يوقفها. الافتراضي: off.

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Iugu. مطلوب.

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely via Iugu. You will be redirected to complete your payment.

بيانات اعتماد API

أنشئ رموز API في Iugu Alia (alia.iugu.com): Settings > API integration > New. أنشئ رمزًا من نوع "Test" وآخر من نوع "Live".

Test mode: يستخدم رمز API للاختبار، لذلك لا تُجرى أي رسوم حقيقية. الافتراضي: on. عندما يكون وضع الاختبار مفعّلًا يعرض الدفع SANDBOX — Test mode enabled. No real charges. فوق الوصف. تستخدم فحوصات حالة الطلب واستردادته دائمًا رمز الوضع الذي أُنشئت فيه فاتورته، لذلك لا يؤثر تغيير الوضع في الطلبات القديمة.

Test API token: رمز API من Iugu من نوع "Test". يُستخدم عندما يكون وضع الاختبار مفعّلًا.

Live API token: رمز API من Iugu من نوع "Live" (الإنتاج). يُستخدم عندما يكون وضع الاختبار متوقفًا. احفظه في سرية.

لا تُعرض الرموز المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved tokens: ضع علامة على رمز ثم اضغط Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة.

إشعارات الدفع

Notification URL: تطلب كل فاتورة من Iugu أن يُبلغ بتغييرات الحالة إلى عنوان URL هذا لمتجرك. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_iugu_gateway/webhook. لا يوجد شيء يُعد في Iugu. ولا يضر وجود مُشغّل إضافي على مستوى الحساب (gatilho) يشير إلى العنوان نفسه. لا تحمل الإشعارات أي بيانات دفع يثق بها المتجر: تُقرأ الفاتورة دائمًا من واجهة برمجة تطبيقات Iugu (الحالة، المبلغ، العملة) قبل إنشاء الطلب أو تعديله.

تستجيب الوحدة لأحداث Iugu التي قد تغيّر حالة الفاتورة: invoice.status_changed، وinvoice.refund، وinvoice.released، وinvoice.dunning_action، وinvoices. لكل منها تقرأ الوحدة الفاتورة وتطبّق حالتها:

paid: يُنشأ الطلب كمدفوع (أو ينتقل إلى حالة المدفوع) بعد التحقق من المبلغ والعملة.

authorized or in_analysis: ينتظر الدفع بالبطاقة الاستيفاء أو يخضع للمراجعة. يُوضع الطلب في حالة الانتظار.

partially_paid: دُفعت الفاتورة جزئيًا. يُوضع الطلب في حالة الانتظار.

expired: انتهت صلاحية الفاتورة دون دفع. يتلقى الطلب المعلّق Payment error.

canceled: أُلغيت الفاتورة. يُلغى الطلب المعلّق.

refunded: استُردت الفاتورة في Iugu. يصبح الطلب مستردًا.

chargeback: اعترض حامل البطاقة على الدفعة. يُوضع الطلب المدفوع في حالة الانتظار.

تُجاب الأحداث الأخرى والفواتير التي لم ينشئها متجرك برمز HTTP 200 وتُتجاهل دون أي طلب إلى Iugu. ومن دون إشعارات تُفحص الفاتورة فقط عندما يعود العميل إلى المتجر من صفحة Iugu.

متقدم

Debug log: يكتب طلبات Iugu وإشعاراته في logs/wc_igu_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا تُسجَّل الرموز وبيانات العملاء. تُكتب الأخطاء والتحذيرات دائمًا، حتى عندما يكون المفتاح متوقفًا. الافتراضي: off.

Log: يعرض حجم السجل وأحدث إدخالاته. اضغط Clear log لتفريغه.

Delete Data on Uninstall: عندما يكون مفعّلًا، يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات البوابة والسجل. تُحفظ دائمًا الطلبات ومراجع فواتير Iugu والاستردادات وحالات الطلبات الخاصة بالوحدة، فتستمر الطلبات القديمة في العمل بعد إعادة التثبيت. الافتراضي: off.

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Iugu) ويؤكد. يُشترط بريد إلكتروني صالح للعميل. تنشئ الوحدة فاتورة Iugu بإجمالي السلة بالريال البرازيلي (BRL) بمهلة 3 أيام، وترسل العميل إلى صفحة فاتورة Iugu. هناك يدفع العميل بالبطاقة الائتمانية أو boleto أو PIX، بالوسائل المفعّلة في حسابك في Iugu. تعرض الفاتورة Order # ورقم السلة. يُرسل اسم العميل وبريده الإلكتروني إلى Iugu، إضافةً إلى اسم الشركة ورقم CPF/CNPJ من حقل Identification number أو VAT number في العنوان عند توفرهما. يُرسل الهاتف والعنوان فقط بالصيغة التي يقبلها Iugu (أرقام هواتف برازيلية، وعناوين برازيلية برمز CEP من 8 أرقام؛ ويُرسل رقم المنزل بصيغة s/n). لا يوجد طلب في هذه المرحلة بعد.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكد Iugu ذلك: تُقرأ الفاتورة من واجهة برمجة تطبيقات Iugu عند عودة العميل وعندما يرسل Iugu إشعارًا. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة Your payment with Iugu has been received.

إذا أنشأ العميل رمز boleto أو PIX وعاد قبل الدفع، يُنشأ الطلب في حالة Awaiting Iugu payment وتعرض صفحة التأكيد Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. ينتقل الطلب إلى Payment accepted عندما يبلغ Iugu باستلام المبلغ، إما بالإشعار أو عندما يفتح العميل رابط العودة مرة أخرى. إذا تعذّر الوصول إلى Iugu عند عودة العميل، تعرض صفحة Payment confirmation الرسالة We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. مع زر Check again وزر Back to checkout. ويعرض الطلب الذي أُلغيت فاتورته أو انتهت صلاحيتها دون دفع، على صفحة التأكيد الرسالة Your Iugu payment was not completed. Please contact us about this order.

إذا أُلغيت الفاتورة أو انتهت صلاحيتها قبل وجود طلب، يعود العميل إلى الدفع ويرى The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. تُحفظ السلة. وعندما يدفع العميل مرة أخرى، توجّهه الوحدة إلى الفاتورة المفتوحة نفسها إذا لم يتغير المبلغ والوضع. وإلا تلغي الفاتورة القديمة في Iugu وتنشئ فاتورة جديدة، حتى لا يمكن دفع السلة نفسها عبر فاتورتين مفتوحتين. وإذا دُفعت فاتورة قديمة مع ذلك، يظل الدفع مرتبطًا بالسلة.

إذا تعذّر على Iugu إنشاء الفاتورة، يبقى العميل عند الدفع مع رسالة قصيرة، مثل Iugu could not create the invoice: مع السبب وطلب مراجعة بيانات الفوترة، أو Could not connect to Iugu. Please try again in a moment. ويُكتب السبب التقني في السجل.

يعمل عنوان URL للإشعارات حتى عندما يكون المتجر في وضع الصيانة، ولا يحجبه قيد الدول في متجرك.

تقبل الوحدة المدفوعات لمرة واحدة فقط. ولا تتضمن نموذج بطاقة داخل الموقع، ولا بطاقات محفوظة، ولا اشتراكات أو فوترة متكررة، ولا carnê (دفاتر الدفع)، ولا مدفوعات مجزأة، ولا إعدادات تقسيط: استخدم إعدادات صفحة Iugu للأقساط. ولا يمكن اختيار طرق الدفع المعروضة في صفحة Iugu من إعدادات الوحدة: تُعرض جميع الطرق المفعّلة في حسابك في Iugu. ولا يمكن دفع الطلب الذي حالته Payment error أو Canceled مرة أخرى من المتجر؛ يقدّم العميل طلبًا جديدًا.

الطلبات والاسترداد

حالات الطلب

No order yet: أُرسل العميل إلى Iugu ولم يدفع بعد، أو لم يؤكد Iugu الدفع بعد. لا توجد سوى السلة.

Payment accepted: أكد Iugu الدفع. يُسجَّل الدفع برقم فاتورة Iugu كرقم معاملة، وتعرض ملاحظة رقم الفاتورة وطريقة الدفع (البطاقة الائتمانية أو boleto أو PIX).

Awaiting Iugu payment: عاد العميل برمز boleto أو PIX صادر. ينتقل الطلب إلى Payment accepted عندما يبلغ Iugu بالدفع.

Iugu payment on hold: دفع البطاقة مُعتمَد لكنه لم يُحصَّل بعد (حصّله في Iugu، ويكتمل الطلب عندما يبلغ Iugu بدفع الفاتورة)، أو الدفع قيد المراجعة، أو دُفعت الفاتورة جزئيًا، أو فُتح نزاع chargeback، أو أبلغ Iugu عن مبلغ أو عملة تختلف عن السلة (مثلًا إذا عُدّلت السلة بعد إنشاء الفاتورة)، أو وصل الدفع بعد إلغاء الطلب. وتشرح الملاحظات السبب. راجع الطلب ونفّذه أو استرد الدفع.

Payment error: انتهت صلاحية فاتورة الطلب المعلّق دون دفع. إذا أبلغ Iugu لاحقًا بأن الفاتورة مدفوعة، ينتقل الطلب إلى Payment accepted.

Canceled: أُلغيت فاتورة الطلب المعلّق في Iugu.

Refunded: استُرد الدفع كليًا عبر الوحدة أو في لوحة Iugu.

إذا دُفعت فاتورة أخرى من السلة نفسها أيضًا، فلا يتغير الطلب. وتطلب منك ملاحظة استرداد الدفع المكرر في Iugu.

كتلة الدفع في Iugu

تعرض صفحة الطلب كتلة Iugu payment تتضمن رقم فاتورة Iugu (مرتبطًا بالفاتورة في Iugu)، وطريقة الدفع، والحالة، والمبلغ الذي حصّله Iugu، والمبلغ المسترد، وشارة Test mode للفواتير الاختبارية، وسجل الاستردادات، وIugu notes الخاصة بالطلب.

الاسترداد

في كتلة Iugu payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واكتب سببًا اختياريًا، ثم اضغط Refund via Iugu. أكّد السؤال Refund this amount through Iugu? This cannot be undone. تحتاج إلى صلاحية تعديل الطلبات. يُرسل الاسترداد برمز الوضع الذي أُنشئت فيه الفاتورة، لذلك يجب أن يكون ذلك الرمز مُعدًّا.

البطاقة الائتمانية: استرداد كامل أو جزئي.

PIX: استرداد كامل فقط.

Boleto: لا يمكن استرداده عبر Iugu. أعِد المال إلى العميل بتحويل بنكي.

تُحسب الاستردادات من المبلغ الذي حصّله Iugu فعليًا عن الفاتورة، لذلك بعد اختلاف في المبلغ يمكنك الاسترداد حتى مبلغ ما دفعه العميل، لا حتى إجمالي الطلب. لا تُسترد إلا الفواتير المدفوعة، ولا يتجاوز المبلغ ما لا يزال قابلًا للاسترداد في Iugu. لا يُعتبر الاسترداد منجزًا إلا عندما يؤكده Iugu. إذا رفض Iugu الاسترداد أو لم يؤكده، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد الناجح إلى سجل الاستردادات والملاحظات مع رقم الفاتورة والسبب. الاسترداد الكامل يضع الطلب في حالة Refunded. الاسترداد الجزئي لا يغيّر الحالة. الاستردادات متاحة بعد أن يبلغ Iugu بأن الفاتورة مدفوعة.

لا تنشئ الوحدة إشعارات دائنة (credit slips). ولا ترسل أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب أي أموال عبر Iugu.

الاسترداد الكامل الذي يتم في لوحة Iugu يضع الطلب في حالة Refunded مع ملاحظة. ولا تُستورد الاستردادات الجزئية التي تتم في اللوحة.

مفتاح الترخيص

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Iugu Gateway هي الكتلة الأولى في صفحة Modules > Module Manager > VibeFox Iugu Gateway > Configure، فوق الإعدادات. أدخل المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مُخفًى، والحالة (مثلًا التاريخ الذي تبقى فيه الرخصة سارية ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-payment-iugu والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يستطيع تغيير المفتاح إلا الموظفون الذين لديهم صلاحية Configure لهذه الوحدة. وتتبع نصوص الكتلة لغة لوحة الإدارة (تشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، مثلًا Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، اضغط Check now. وإذا تعذّر الوصول إلى خادم التراخيص، تستمر الوحدة في العمل بآخر حالة معروفة.

يعمل المفتاح الواحد على نطاق واحد: نطاق المتجر الرئيسي، وكذلك في إعداد المتاجر المتعددة. ولا تؤدي إزالة المفتاح من المتجر إلى تحرير خانة النطاق. حرّر الخانة من حسابك في vibefox.net.

بدون مفتاح نشط لا يُعرض Iugu للعملاء عند الدفع. وإذا بدأ دفع رغم ذلك، يرى العميل الرسالة This payment method is not available. Please choose another one. ولا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء المفتاح، لكن لا يمكنك اختبارها عند الدفع. يظهر تذكير في Modules > Module Manager على تبويب Alerts. ولا تتأثر الطلبات الحالية: تظل المدفوعات التي بدأت تُؤكَّد، وتعمل الاستردادات.

عندما تنتهي صلاحية الترخيص، تستمر الوحدة في العمل، لكن التحديثات والدعم تحتاج إلى تجديد. يُعاد فحص الحالة تلقائيًا أثناء عملك في لوحة الإدارة: مرة واحدة يوميًا خلال أول 14 يومًا بعد إدخال المفتاح، ثم مرة واحدة أسبوعيًا. ولا حاجة إلى cron job. وعند إلغاء تثبيت الوحدة أو إعادة ضبطها تُحذف دائمًا مفتاح الترخيص وحالة الترخيص.

استكشاف الأخطاء وإصلاحها

لا يظهر Iugu عند الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن رمز الوضع النشط مُعدّ: Test API token في وضع الاختبار، وLive API token في وضع الإنتاج. يجب أن تكون عملة السلة BRL وأن يكون الإجمالي 1.00 R$ على الأقل. في Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة BRL ولدولة العميل ولمجموعة العميل. وتعرض صفحة الإعدادات تحذيرًا إذا كان الرمز أو العملة غير صحيحين.

تم الدفع لكن لم يُنشأ أي طلب: لم يصل إشعار Iugu إلى متجرك أو تعذّر التحقق منه. فعّل Debug log وراجع حقل Log في صفحة الوحدة. تحقق من أن متجرك يمكن الوصول إليه من الإنترنت عبر Notification URL، وأن رمز الوضع الذي أُنشئت فيه الفاتورة ما زال مُدخلًا. تُفحص الفاتورة أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

Notification answers verification failed: تعذّرت قراءة الفاتورة من واجهة برمجة تطبيقات Iugu في تلك اللحظة، مثلًا بسبب خطأ في الشبكة أو رمز خاطئ أو غياب رمز وضع الفاتورة. يعيد Iugu محاولة الإشعار.

Notification answers busy: كان السلة تُعالَج بطلب آخر في الوقت نفسه، أو تعذّر إنشاء الطلب (مثلًا إذا كانت الوحدة معطّلة). يعيد Iugu محاولة الإشعار. ويعرض السجل السبب.

Notification answers invalid invoice id: لم يحتوِ الإشعار على رقم فاتورة صالح. لا يتغير شيء.

الطلب في حالة Iugu payment on hold: اقرأ Iugu notes في كتلة الطلب. دفع البطاقة ينتظر التحصيل، أو الدفع قيد المراجعة، أو مدفوع جزئيًا أو متنازع عليه، أو المبلغ المدفوع لا يطابق السلة، أو وصل الدفع بعد إلغاء الطلب.

يرى العميل «Iugu payments are not available right now»: رمز API مفقود أو خاطئ. تحقق من رمز الوضع النشط.

يرى العميل «This order already has an Iugu payment that the store has to review»: فاتورة سابقة للسلة مُعتمَدة أو قيد المراجعة أو مدفوعة جزئيًا، لكن تعذّر إنشاء الطلب. تحقق من الفاتورة في Iugu ومن السجل.

فشل الاسترداد: اقرأ الرسالة في الكتلة. لا يمكن استرداد مدفوعات boleto عبر Iugu، ولا تُسترد مدفوعات PIX إلا كليًا، ولا تُسترد إلا الفواتير المدفوعة. إذا قالت الرسالة إن الدفع تم في وضع الاختبار أو الإنتاج ولا يوجد رمز مُعدّ لذلك الوضع، فأدخل رمز ذلك الوضع. إذا لم يؤكد Iugu الاسترداد، فتحقق من الفاتورة في Iugu قبل إعادة المحاولة.

يستطيع المطوّرون تغيير طلب الفاتورة، مثلًا لتقييد طرق الدفع باستخدام payable_with، في الخطاف actionWcpIuguInvoiceData.

إلغاء التثبيت

انتقل إلى Modules > Module Manager، وافتح القائمة بجانب VibeFox Iugu Gateway، واختر Uninstall. مفتاح الترخيص وحالة الترخيص لهذه الوحدة يُحذفان دائمًا. إذا كان Delete Data on Uninstall مفعّلًا تُحذف إعدادات البوابة والسجل. وإذا كان متوقفًا تُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. تُحفظ دائمًا مراجع فواتير Iugu والاستردادات وحالات الطلبات Awaiting Iugu payment وIugu payment on hold، لذلك يمكن استرداد الطلبات المدفوعة سابقًا، وتستمر مطابقة الإشعارات المتأخرة بعد إعادة التثبيت. تحتفظ الطلبات الحالية بملاحظات الدفع وأرقام المعاملات الخاصة بها.

Iugu علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ Iugu ولا يصادق عليها Iugu.