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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبّت ومفعّل. بدون WooCommerce لا تُفعَّل الإضافة.

PHP: 8.0 أو أحدث.

عملة المتجر: الريال البرازيلي (BRL). تتعامل Iugu بالريال البرازيلي فقط. تُخفى وسيلة الدفع عندما يستخدم المتجر، أو الطلب في صفحة Pay for order، عملة أخرى، وكذلك للمبالغ الأقل من R$ 1,00 (الحد الأدنى لـ Iugu).

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

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

التثبيت

1. في WordPress انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP للإضافة، ثم انقر على Install Now. يمكنك أيضًا رفع مجلد wcp_iugu_gateway إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

3. اضبط عملة المتجر على الريال البرازيلي (BRL) في WooCommerce > Settings > General.

4. افتح الإعدادات: WooCommerce > Settings > Payments > Iugu > Manage، أو انقر على Settings أسفل اسم الإضافة في صفحة Plugins.

5. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص في أعلى الصفحة، ثم انقر على Activate.

6. أدخل رمزي API للاختبار والإنتاج (راجع الإعدادات)، واترك Test mode مفعّلًا، وفعّل Enable / Disable، ثم احفظ.

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

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Iugu. تحت عنوان البوابة تعرض الصفحة TEST MODE (تُنشأ الفواتير برمز API للاختبار دون خصم حقيقي) أو LIVE. وتحذّر عندما يكون رمز الوضع النشط مفقودًا (عندها تُخفى وسيلة الدفع في صفحة الدفع)، وعندما لا تكون عملة المتجر BRL. وفي قائمة وسائل الدفع تُعرض 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: Use the test API token (no real charges). الافتراضي: on. ما دام وضع الاختبار مفعّلًا، تعرض صفحة الدفع SANDBOX — Test mode enabled. No real charges. فوق الوصف. تستخدم استعلامات الحالة والاستردادات الخاصة بأي طلب دائمًا رمز الوضع الذي أُنشئت فيه فاتورته، لذلك لا يؤثر تبديل الوضع في الطلبات القديمة.

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

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

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

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

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

paid: يُعلَّم الطلب كمدفوع بعد التحقق من المبلغ والعملة.

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

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

expired: انتهت صلاحية الفاتورة دون دفع. يصبح الطلب «فشل»، ويستطيع العميل الدفع مرة أخرى.

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

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

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

تُجاب الأحداث الأخرى والفواتير التي لا تخص طلبًا في هذا المتجر بالرد OK وتُتجاهل. وبدون إشعارات لا يُتحقق من الطلب إلا عندما يعود العميل إلى المتجر من صفحة Iugu.

متقدم

Debug log: Log API requests and notifications في WooCommerce > Status > Logs، المصدر wcp_iugu_gateway، دون رموز أو بيانات عملاء. تُسجَّل الأخطاء دائمًا. الافتراضي: off.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. الافتراضي: off.

الدفع

يختار العميل وسيلة الدفع (افتراضيًا Iugu) ويُتمّ الطلب. يُشترط بريد إلكتروني صالح للفوترة. تُنشئ الإضافة فاتورة Iugu بإجمالي الطلب بالريال البرازيلي (BRL)، تستحق خلال 3 أيام، وترسل العميل إلى صفحة فاتورة Iugu. هناك يدفع العميل بالبطاقة الائتمانية أو boleto أو PIX، بالوسائل المفعّلة في حسابك في Iugu. يُرسل اسم العميل وبريده الإلكتروني إلى Iugu، إضافةً إلى رقم CPF/CNPJ ورقم المبنى والحي من حقول الدفع في «Brazilian Market on WooCommerce» إذا وُجدت. ولا يُرسل الهاتف والعنوان إلا بالصيغة التي تقبلها Iugu (أرقام هواتف برازيلية، وعناوين برازيلية برقم CEP من 8 أرقام).

بعد الدفع يعود العميل إلى صفحة «Order received» في متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Iugu: تُقرأ الفاتورة من واجهة Iugu البرمجية عندما يعود العميل وعندما ترسل Iugu إشعارًا. إذا أنشأ العميل رمز boleto أو PIX وعاد قبل الدفع، يبقى الطلب في حالة الانتظار حتى تؤكد Iugu الدفع. ولا يلغي مؤقت الطلبات غير المدفوعة في WooCommerce الطلبات التي ما زالت فاتورة Iugu الخاصة بها مفتوحة.

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

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

تعمل وسيلة الدفع في صفحة الدفع الكلاسيكية وفي كتلة Checkout وفي صفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

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

حالات الطلب

Pending payment: أُنشئت الفاتورة ولم يدفع العميل بعد.

Processing or Completed: أكدت Iugu الدفع. يضبط WooCommerce الحالة المعتادة للطلب المدفوع. تعرض ملاحظة الطلب رقم فاتورة Iugu ووسيلة الدفع (البطاقة الائتمانية أو boleto أو PIX). رقم المعاملة هو رقم فاتورة Iugu، وهو على شاشة الطلب يرتبط بالفاتورة في Iugu.

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

Failed: انتهت صلاحية الفاتورة دون دفع. يستطيع العميل دفع الطلب مرة أخرى.

Cancelled: أُلغيت الفاتورة في Iugu.

Refunded: استُردت الفاتورة التي دفعت الطلب في Iugu.

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

الاسترداد

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Iugu. يُرسل الاسترداد برمز الوضع الذي أُنشئت فيه الفاتورة.

Credit card: استرداد كامل أو جزئي.

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

Boleto: لا يمكن استرداده عبر Iugu. أعِد المبلغ إلى العميل عبر التحويل المصرفي، ثم سجّل الاسترداد يدويًا دون استخدام Refund via Iugu.

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

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

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. تقع كتلة الترخيص في أعلى WooCommerce > Settings > Payments > Iugu. ألصق المفتاح في License key وانقر على Activate. تعرض الكتلة الحالة، مثل التاريخ الذي يبقى فيه الترخيص فعّالًا ونطاقك. استخدم Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. يفتح الرابط Manage licenses and domains in your account حسابك في vibefox.net.

يعمل المفتاح الواحد على نطاق واحد. ولا تؤدي إزالة المفتاح من موقع إلى تحرير خانة النطاق الخاصة به. حرّر الخانة من حسابك في vibefox.net.

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

عند انتهاء صلاحية الترخيص تواصل الإضافة العمل، لكن التحديثات والدعم تتطلب التجديد. تُعاد مراجعة الحالة تلقائيًا في الخلفية.

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

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

تمّ الدفع لكن الطلب ما زال Pending payment: لم يصل إشعار Iugu إلى متجرك أو تعذّر التحقق منه. فعّل Debug log وراجع WooCommerce > Status > Logs، المصدر wcp_iugu_gateway. تحقّق من أن موقعك يمكن الوصول إليه من الإنترنت عبر عنوان الإشعارات المعروض في الإعدادات، وأن رمز الوضع الذي أُنشئت فيه الفاتورة ما زال مُدخلًا. ويُتحقق من الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

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

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

الطلب في حالة On hold: اقرأ ملاحظات الطلب. boleto أو PIX ما زال غير مدفوع، أو الدفع بالبطاقة ينتظر التحصيل، أو الدفع قيد المراجعة، أو مدفوع جزئيًا أو متنازع عليه، أو المبلغ المدفوع لا يطابق الطلب، أو الدفعة وصلت بعد إلغاء الطلب.

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

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

تعرض كتلة الترخيص خطأً: اتبع الرسالة الظاهرة في الكتلة. فمثلًا إذا كان المفتاح مستخدمًا في نطاق آخر، فحرّر خانة في حسابك في vibefox.net وانقر على Check now. وإذا تغيّر عنوان الموقع، فانقر على Check now لتفعيل المفتاح للنطاق الجديد. وإذا تعذّر الوصول إلى خادم التراخيص، تواصل الإضافة العمل بآخر حالة معروفة.

يمكن للمطورين تعديل طلب الفاتورة، مثلًا لتقييد وسائل الدفع باستخدام payable_with، عبر الفلتر wc_igu_invoice_data.

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

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

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