سند لووكوميرس

ربط احترافي مع منصة سند لإصدار الفواتير الضريبية المتوافقة مع متطلبات الهيئة (ZATCA) للمرحلة الثانية، مع أتمتة كاملة، مراقبة ذكية، ومنع أخطاء الامتثال الشائعة.

فواتير PDF + QR إشعارات دائن للاسترجاع Webhooks موثوقة حماية حذف الطلبات لوحة مراقبة

1) نظرة عامة

ماذا تقدم الإضافة؟

  • إرسال بيانات الفواتير تلقائياً إلى منصة سند عند اكتمال الدفع.
  • إتاحة تحميل فاتورة PDF (تتضمن QR) للعميل والإدارة.
  • إصدار إشعار دائن عند الاسترجاع (Refund) وربطه بالفاتورة الأصلية.
  • مراقبة صحة التكامل (Webhooks / جدولة / طوابير) من لوحة التحكم.

متى تُستخدم؟

  • متاجر WooCommerce التي تحتاج امتثال المرحلة الثانية للفوترة الإلكترونية.
  • الحالات التي تحتاج أتمتة كاملة بدون تدخل يدوي في إصدار الفواتير.
  • الفرق التي تريد سجل تتبع (Logs) واضح لحالات الإرسال والاسترجاع.
هذا الدليل يركز على التشغيل العملي: الإعداد، الويبهوك، تدفق الفواتير، الاسترجاعات، والمشاكل الشائعة.

2) المتطلبات قبل التثبيت

متطلبات النظام

  • WordPress + WooCommerce محدثين (يوصى بأحدث نسخ مستقرة).
  • HTTPS مفعّل على الدومين (مهم لاستقبال الويبهوك).
  • تمكين REST API وعدم حظره من جدار حماية/إضافة أمنية.

معلومات مطلوبة للإعداد

  • مفتاح API من منصة سند.
  • بيانات المنشأة والرقم الضريبي (VAT) وإعدادات المتجر الأساسية.
  • تحديد البيئة: تجريبية (Sandbox) أو إنتاجية (Production).
يوصى: روابط دائمة غير Plain مهم: عدم كاش لروابط الويبهوك ممنوع: تعطيل REST API

3) التثبيت والإعداد السريع

  1. 1

    رفع الإضافة وتفعيلها

    لوحة تحكم ووردبريس → إضافات → أضف جديد → رفع إضافة (ZIP) → تفعيل.

  2. 2

    معالج الإعداد (Setup Wizard)

    بعد التفعيل ستظهر خطوات إعداد سريعة للتحقق من الاتصال وتكوين البيانات الأساسية.

  3. 3

    اختبار الاتصال

    تأكد من ظهور حالة اتصال ناجحة قبل بدء تشغيل المتجر في الإنتاج.

4) الويبهوك والاستقرار

الهدف

الويبهوك يضمن وصول أحداث سند إلى المتجر (تحديث حالة، إعادة إرسال، تتبع… إلخ) بدون تأخير.

روابط الويبهوك

قد يختلف الرابط حسب إعداد الروابط الدائمة في ووردبريس.

/wp-json/sanad-woo/v1/webhook
/?rest_route=/sanad-woo/v1/webhook
إذا كانت الروابط الدائمة لديك على وضع Plain، استخدم رابط rest_route لتفادي مشاكل إعادة الكتابة (Rewrite).

أفضل الممارسات

  • تأكد أن السيرفر يسمح بطلبات POST على رابط الويبهوك.
  • إذا تستخدم Cloudflare أو WAF: اسمح للرابط (allowlist) وفعّل استثناء من الكاش.
  • يفضل إضافة ترويسة توقيع (Signature) من سند للتحقق من صحة الطلب (HMAC).

فحص سريع

افتح لوحة التحكم في سند → Health / Monitoring → تحقق من حالة الويبهوك (200 OK).

إذا ظهرت 404/500: راجع إعداد الروابط الدائمة وإضافات الأمن والكاش.

5) تدفق الفواتير داخل WooCommerce

متى يتم إصدار الفاتورة؟

  • بعد نجاح الدفع وتحوّل الطلب إلى الحالة المستهدفة (مثل Processing/Completed حسب إعداداتك).
  • تُرسل بيانات الفاتورة إلى سند، ثم يتم إرفاق PDF/QR للطلب.

أين تظهر الفاتورة؟

  • للعميل: صفحة الشكر + صفحة "طلباتي".
  • للإدارة: داخل شاشة الطلب في لوحة التحكم.
الهدف هو تقليل التدخل اليدوي: بمجرد نجاح الدفع، تتم دورة الإصدار والإرفاق تلقائياً.

6) الاسترجاع وإشعار الدائن (Credit Note)

الطريقة الصحيحة للإلغاء

  • لا تحذف الطلب إذا كان له فاتورة.
  • استخدم Refund داخل WooCommerce لضمان إصدار إشعار دائن بشكل نظامي.

ما الذي يحدث عند Refund؟

  • توليد إشعار دائن وربطه بالفاتورة الأصلية.
  • تحديث حالة السجل في لوحة سند/لوحة المتجر.
Refund جزئي مدعوم حسب إعدادات المتجر ربط إشعار الدائن بالفاتورة الأصلية

7) لوحة التحكم والمراقبة

المؤشرات الأساسية

  • صحة التكامل: Webhooks / جدولة / اتصال API.
  • قائمة الانتظار: ما ينتظر الإرسال/المعالجة.
  • تقارير آخر 24 ساعة: نجاح/فشل إرسال الفواتير.

متى أراجع اللوحة؟

  • بعد التثبيت مباشرة للتأكد أن كل شيء أخضر.
  • عند إضافة بوابة دفع جديدة أو تغيير إعدادات السيرفر.
  • عند ملاحظة تأخر الفواتير أو فشل webhook.

8) استكشاف الأخطاء الشائعة

الويبهوك يفشل مع Permalinks = Plain

استخدم الرابط:

/?rest_route=/sanad-woo/v1/webhook

أو غيّر الروابط الدائمة لأي خيار غير Plain (مثل Post name).

خطأ 500 أثناء استقبال الويبهوك

السبب غالباً ثيم/إضافة تستدعي وظائف WooCommerce Cart أثناء REST. تأكد أن الثيم لا يستدعي cart بدون تحقق، وجرّب تعطيل إضافات الكاش/الأمن مؤقتاً.

لا يتم إنشاء فاتورة بعد الدفع
  • تحقق من حالة الطلب المستهدفة في إعدادات الإضافة.
  • راجع لوحة المراقبة/السجل لمعرفة سبب عدم الإرسال.
  • تأكد أن السيرفر يستطيع الاتصال بخوادم سند عبر HTTPS.
العميل لا يرى رابط تحميل PDF
  • تأكد أن الفاتورة تم إصدارها فعلياً وأن رابط PDF تم حفظه.
  • جرّب تعطيل إضافات الكاش لصفحات حساب العميل/الطلب.

9) أسئلة سريعة

هل الإضافة تمنع حذف الطلبات؟ ولماذا؟

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

هل أحتاج مفاتيح ترخيص؟

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

هل يعمل على Sandbox و Production؟

نعم. اختر البيئة من إعدادات الإضافة أثناء معالج الإعداد.

10) الدعم الفني

للدعم الفني أثناء الإعداد أو التشغيل، تواصل معنا عبر واتساب:

تواصل عبر واتساب

جهّز قبل التواصل: رابط المتجر، نسخة WordPress/WooCommerce، ولقطة من قسم المراقبة/السجل.