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

المتطلبات

OpenCart: 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 والإصدارات الأحدث (تم الاختبار على 4.1.0.3).

PHP: 8.0 أو أحدث.

العملة: الريال البرازيلي (BRL). تحصّل Iugu المدفوعات بالريال البرازيلي فقط، لذلك يجب أن يتوفر في المتجر BRL ضمن System > Localisation > Currencies. يُخفى خيار الدفع عندما تكون عملة الدفع لدى العميل غير BRL، وكذلك عندما يقل إجمالي الطلب عن R$ 1,00 (الحد الأدنى لـ Iugu).

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

CPF/CNPJ (اختياري): لا يملك OpenCart حقل CPF خاصًا به. إذا أضفت حقلًا مخصصًا للعميل أو للعنوان يحتوي اسمه على CPF أو CNPJ (Customers > Custom Fields)، فإن قيمته تُرسل إلى Iugu.

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

التثبيت

يحتوي هذا التنزيل على ملف zip واحد فيه حزم الإصدارين من OpenCart. فُكّه على حاسوبك. يحتوي على README.txt، وحزمة OpenCart 3 wcp_iugu_gateway-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_iugu_gateway.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة انتقل إلى Extensions > Installer، واضغط Upload واختر الملف wcp_iugu_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا حاجة إلى تحديث Extensions > Modifications. وبدلًا من المثبّت يمكنك نسخ محتويات مجلد upload الموجود في هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Iugu Gateway واضغط Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

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

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

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

OpenCart 4

1. في لوحة الإدارة انتقل إلى Extensions > Installer، واضغط Upload واختر الملف wcp_iugu_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الامتداد من اسم الملف، ولا تعمل الحزمة إذا أُعيد تسميتها.

2. تظهر الحزمة في قائمة الامتدادات المثبتة في الصفحة نفسها. اضغط Install (زر + الأخضر) بجانبها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Iugu Gateway، واضغط Install (زر + الأخضر)، ثم Edit (زر القلم).

4. أدخل مفتاح الترخيص ورموز API كما في الخطوات من 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الفرق الوحيد هو عنوان Notification URL (انظر إشعارات الدفع).

تبدأ عملية التثبيت الجديدة بطريقة الدفع معطّلة ووضع الاختبار مفعّلًا.

الإعدادات

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

عند الحفظ، لا يجوز أن يكون Title فارغًا أو أطول من 128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا، ويجب أن يكون Total رقمًا يساوي 0 أو أكبر، ويجب أن تكون المنطقة الجغرافية وحالات الطلب المحددة موجودة. وإلا فلن يُحفظ شيء، وسيحدد الخطأ الحقل المعني.

Iugu

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

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

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: ادفع بأمان عبر Iugu. ستتم إعادة توجيهك لإكمال الدفع.

Sort Order: ترتيب Iugu بين طرق الدفع عند إتمام الشراء. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض Iugu فقط لعناوين الدفع الواقعة في المنطقة الجغرافية المحددة. الافتراضي: All zones. تُعدّ المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي الشراء، بالعملة الافتراضية للمتجر، الذي يجب أن يصل إليه الطلب قبل عرض Iugu. اتركه فارغًا لعرض Iugu لأي إجمالي. وتتطلب Iugu نفسها ما لا يقل عن R$ 1,00.

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

أنشئ رموز API في Iugu Alia (يحتوي القسم على رابط إليها): Settings > API integration > New. أنشئ رمزًا من نوع "Test" ورمزًا من نوع "Live".

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

Test API token: رمز API الخاص بـ Iugu من نوع "Test". يُستخدم أثناء تفعيل وضع الاختبار.

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

لا تُعرض الرموز المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. اكتب قيمة جديدة فقط إذا أردت تغييرها. لإزالة رمز محفوظ، ضع علامة على Clear the saved token on save أسفل الحقل، ثم اضغط Save.

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

Notification URL: تطلب كل فاتورة من Iugu أن تُبلغ بتغييرات الحالة إلى عنوان URL هذا في متجرك. في OpenCart 3 يبدو بالشكل https://your-store/index.php?route=extension/payment/wcp_iugu_gateway/webhook، وفي OpenCart 4 بالشكل https://your-store/index.php?route=extension/wcp_iugu_gateway/payment/wcp_iugu_gateway.webhook، ويجب أن يكون متاحًا من الإنترنت. لا يوجد ما يلزم إعداده في Iugu. ولا يضر وجود مُشغّل إضافي على مستوى الحساب يشير إلى العنوان نفسه. لا تحمل الإشعارات أي بيانات دفع يثق بها المتجر: تُقرأ الفاتورة دائمًا من واجهة Iugu API (الحالة، المبلغ، العملة) قبل أن يتغير الطلب.

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

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

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). ولا يحصل على حالة إلا بعد أن تُبلغ Iugu عن الفاتورة، إما بالإشعار أو عند عودة العميل؛ وتُقرأ الفاتورة دائمًا من Iugu. يسرد كل حقل أدناه حالات طلبات OpenCart لديك.

Order Status After Payment: يُضبط بعد دفعة Iugu موثّقة. الافتراضي: قيد المعالجة.

Awaiting Iugu Payment Status: عاد العميل من صفحة Iugu وبيده فاتورة boleto أو PIX صادرة؛ وستؤكد Iugu المبلغ لاحقًا. الافتراضي: قيد الانتظار.

Iugu Payment On Hold Status: دفعة بطاقة مفوّضة لكنها غير محصّلة، أو دفعة قيد التحليل، أو دفعة جزئية، أو اعتراض على الدفعة (chargeback)، أو مبلغ أو عملة مختلفان عن الطلب، أو دفعة وصلت بعد إلغاء الطلب. توضح ملاحظة السبب؛ تحقق منه يدويًا. الافتراضي: قيد الانتظار، لأن OpenCart لا يملك حالة "On hold". يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Invoice Expired Status: انتهت صلاحية فاتورة طلب معلّق دون دفع. إذا أبلغت Iugu لاحقًا بأنها مدفوعة، يحصل الطلب على حالة ما بعد الدفع. الافتراضي: فشل.

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

Refunded Status: يُضبط بعد استرداد الدفعة بالكامل من صفحة الطلب أو من لوحة تحكم Iugu. الافتراضي: مسترد.

متقدم

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

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

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

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر رموز API.

Import: الصق ملف JSON مُصدَّرًا سابقًا واضغط Import لاستعادة الإعدادات. تبقى رموز API المحفوظة كما هي.

إتمام الشراء

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Iugu). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the Iugu invoice page to pay by credit card, boleto or PIX. ينشئ OpenCart الطلب في هذه الخطوة، ما يزال دون حالة. عندما يضغط العميل Confirm Order، تنشئ الإضافة فاتورة Iugu بإجمالي الطلب بالريال البرازيلي، واستحقاقها خلال 3 أيام، وترسل العميل إلى صفحة فاتورة Iugu. يلزم بريد إلكتروني صالح. تعرض الفاتورة Order # ورقم الطلب. هناك يدفع العميل ببطاقة الائتمان أو boleto أو PIX، بالطرق المفعّلة في حسابك لدى Iugu. يُمرَّر اسم العميل وبريده الإلكتروني إلى Iugu، إضافة إلى CPF/CNPJ من حقل مخصص يحمل اسم CPF أو CNPJ عندما يحتوي على 11 أو 14 رقمًا. ولا يُرسل الهاتف والعنوان إلا بالصيغة التي تقبلها Iugu (أرقام الهاتف البرازيلية، والعناوين البرازيلية برمز CEP مكوّن من 8 أرقام؛ ويُرسل رقم المنزل بالصيغة s/n).

في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، داخل النافذة Payment method options، وينقر على Confirm Order أسفل صفحة الدفع. وبشكل افتراضي لا يطلب OpenCart 4 عنوان الدفع؛ عندها يأخذ الامتداد عنوان الشحن وحقل CPF/CNPJ المخصص في عنوان الشحن.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Iugu: تُقرأ الفاتورة من واجهة Iugu API عندما يعود العميل وعندما ترسل Iugu إشعارًا. ثم يحصل الطلب على حالته بالطريقة المعيارية في OpenCart، مع رسائل البريد المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart.

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

إذا أُلغيت الفاتورة أو انتهت صلاحيتها، يعود العميل إلى صفحة الشراء برسالة The Iugu invoice was not paid (it was canceled or has expired). Your cart is kept: confirm the order again to pay. وإذا أُلغي الطلب لأن فاتورة Iugu الخاصة به أُلغيت، فالرسالة هي Your order was cancelled because its Iugu invoice was canceled. وإذا كانت السلة فارغة بالفعل (وكان طلب boleto أو PIX قد وصل إلى صفحة النجاح قبل انتهاء صلاحية فاتورته)، يرى العميل بدلًا من ذلك صفحة Payment confirmation تتضمن The Iugu invoice of order #... was not paid (it was canceled or has expired), so the order will not be shipped. To buy these items, please place a new order. (أو رسالة الإلغاء) وزر Continue. في OpenCart 4 تظهر هذه الرسائل أعلى صفحة الدفع. ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order؛ أما OpenCart 4 فيُحدِّث طلب الدفع الحالي، فيدفع العميل الطلب نفسه بفاتورة جديدة بعد انتهاء الفاتورة أو إلغائها. لكن السلة تُدفع مرة واحدة فقط. وقبل إنشاء فاتورة جديدة تتحقق الإضافة من الفواتير السابقة للسلة: إذا كانت إحداها مدفوعة، يُطبَّق ذلك الدفع ويذهب العميل إلى صفحة النجاح؛ وإذا كان للطلب نفسه فاتورة مفتوحة بالمبلغ والوضع نفسيهما، يُعاد العميل إليها؛ وتُلغى الفواتير المفتوحة الأخرى في Iugu. وإذا دُفعت فاتورة قديمة على أي حال، فإن الدفعة تُطابَق مع ذلك، ويُعلَّم الدفع المكرر لسلة مدفوعة بملاحظة. وأي تغيير في السلة، بما فيه الكمية الجديدة، يُحسب سلة جديدة تحتاج إلى دفعها الخاص.

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تظهر صفحة النجاح. وإذا أُغلق هذا الطلب في الأثناء (مثلًا انتهت صلاحية boleto أو ألغيته)، يُعاد العميل إلى صفحة الدفع مع الرسالة The Iugu invoice was not paid (it was canceled or has expired). Your cart is kept: confirm the order again to pay. أو، إذا كان قد دُفع قبل إغلاقه، مع الرسالة This order was closed by the store, so it will not be shipped. Your cart is kept: confirm the order again to pay. وإذا كان الطلب قد تم تقديمه بالفعل وتحتوي السلة الآن على شراء جديد، فإن Confirm Order يعيد تحميل صفحة الدفع. وفي الحالتين، يدفع Confirm Order التالي طلبًا جديدًا للسلة.

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

يعمل عنوان URL الخاص بالإشعارات أيضًا أثناء وجود المتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، ويضيف الامتداد في OpenCart 4 startup action يسمح بمرور الإشعار وعودة العميل.

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

الطلبات والمبالغ المستردة

حالات الطلب

بلا حالة (طلب مفقود): أُرسل العميل إلى Iugu ولم يدفع، أو انتهت صلاحية الفاتورة أو أُلغيت، أو لم تؤكد Iugu الدفع بعد. في Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط الفلتر Order Status على Missing Orders.

Order Status After Payment (الافتراضي قيد المعالجة): أكدت Iugu الدفع. تعرض ملاحظة معرّف الفاتورة وطريقة الدفع (بطاقة ائتمان أو boleto أو PIX).

Awaiting Iugu Payment Status (الافتراضي قيد الانتظار): عاد العميل بفاتورة boleto أو PIX صادرة. ينتقل الطلب إلى حالة المدفوع عندما تُبلغ Iugu عن الدفع.

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

Invoice Expired Status (الافتراضي فشل): انتهت صلاحية فاتورة الطلب المعلّق دون دفع. إذا أبلغت Iugu لاحقًا بأن الفاتورة مدفوعة، ينتقل الطلب إلى حالة المدفوع.

Invoice Canceled Status (الافتراضي ملغى): أُلغيت فاتورة الطلب المعلّق في Iugu.

Refunded Status (الافتراضي مسترد): استُرد الدفع بالكامل عبر الإضافة أو من لوحة تحكم Iugu.

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

تبويب VibeFox Iugu Gateway

في Sales > Orders افتح طلبًا دُفع عبر Iugu. في أسفل صفحة الطلب، بجانب History وAdditional، يعرض تبويب VibeFox Iugu Gateway معرّف Iugu invoice (مرتبطًا بالفاتورة في Iugu) مع تسمية Test mode للفواتير التجريبية، وPayment method، وStatus، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل المبالغ المستردة، وIugu notes الخاصة بالطلب. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

المبالغ المستردة

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

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

لا تعيد المرتجعات في Sales > Returns أي أموال عبر Iugu.

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

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

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

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

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

من دون مفتاح فعّال لا يُعرض Iugu للعملاء عند إتمام الشراء. وإذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. ويظل مستخدم الإدارة الذي سجّل الدخول إلى الإدارة في المتصفح نفسه يرى طريقة الدفع في المتجر، مع وسم (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء المفتاح. وفي OpenCart 4 لا تتوفر هذه المعاينة: لا يرى المتجر تسجيل دخول الإدارة، لذلك تبقى طريقة الدفع مخفية عن الجميع من دون مفتاح فعّال. وبعد أن تفتح صفحة Edit مرة واحدة، يظهر تذكير على Dashboard الإدارة. أغلقه بالزر × لإخفائه لمدة 7 أيام. والطلبات الحالية لا تتأثر: الدفعات التي بدأت بالفعل ما تزال تُؤكَّد، والمبالغ المستردة تعمل.

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

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

لا يظهر Iugu عند إتمام الشراء: تحقق من أن الترخيص فعّال، وأن Enable / Disable مفعّل، وأن رمز الوضع النشط مضبوط: Test API token في وضع الاختبار، وLive API token في الوضع الحي. يجب أن تكون عملة إتمام الشراء لدى العميل BRL وأن يكون الإجمالي 1,00 R$ على الأقل. وتحقق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات. تعرض صفحة الإعدادات تحذيرًا إذا كان الرمز أو العملة خاطئين.

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

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

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

يرد الإشعار بـ invalid invoice id: لم يكن في الإشعار معرّف فاتورة صالح. لا يتغير شيء.

الطلب في Iugu Payment On Hold Status: اقرأ Iugu notes في تبويب الطلب. تنتظر دفعة البطاقة التحصيل، أو الدفعة قيد التحليل، أو مدفوعة جزئيًا أو متنازع عليها، أو لم يتطابق المبلغ المدفوع مع الطلب، أو وصلت الدفعة بعد إلغاء الطلب.

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

يرى العميل "A valid billing email is required for Iugu": ليس للطلب عنوان بريد إلكتروني صالح.

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

يرى العميل This payment method is not available.: لم تعد جلسة إتمام الشراء تطابق الطلب، أو أُوقفت طريقة الدفع في الأثناء. يعيد العميل تحميل صفحة الشراء.

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

للمطوّرين: قبل إنشاء الفاتورة تُطلق الإضافة حدث OpenCart باسم wc_igu_invoice_data مع طلب الفاتورة والطلب، مثلًا لتقييد طرق الدفع باستخدام payable_with.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، واضغط Uninstall (الزر الأحمر −) بجانب VibeFox Iugu Gateway. تُحذف دائمًا مفتاح الترخيص وحالة الترخيص لهذه الإضافة. يحذف OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable / Disable، وSort Order، وGeo Zone، وTotal، وحالات الطلبات في قسم Orders، وتعود هذه إلى قيمها الافتراضية عند إعادة التثبيت. ويُحذف أيضًا حدث OpenCart الخاص بالإضافة (وفي OpenCart 4 أيضًا الـ startup action الذي يسمح بمرور الإشعار وعودة العميل في وضع الصيانة). إذا كان Delete data on uninstall مفعّلًا، تُحذف بقية إعدادات البوابة (العنوان، والوصف، ووضع الاختبار، ورموز API، ومفتاح سجل التصحيح) والسجل. وإذا كان معطّلًا، تُحفظ لإعادة التثبيت لاحقًا. تُحفظ مراجع فواتير Iugu والمبالغ المستردة دائمًا، لذلك تبقى الطلبات المدفوعة سابقًا قابلة للاسترداد، وتظل الإشعارات المتأخرة مطابقة بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، لإزالة ملفات الإضافة أيضًا، انتقل بعد إلغاء التثبيت إلى Extensions > Installer، واضغط Uninstall (زر − البرتقالي) بجانب VibeFox Iugu Gateway في قائمة الإضافات المثبتة، ثم Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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