دورة حياة الفاتورة

تنتقل الفاتورة من الإنشاء إلى الإغلاق أو انتهاء الصلاحية. يصف هذا القسم الحالات التي يمكن أن تمر بها، وكيف تنتقل بينها، وما يستطيع التاجر فعله في كل خطوة.

حالات الفاتورة

الحالة	القيمة في API	الوصف	تدخل في البحث عن الدفعات
غير مدفوعة	unpaid	الفاتورة صادرة، ومهلة الدفع لم تنقضِ، ولم تصل دفعة	نعم
مدفوعة	paid	وُجدت دفعة ورُبطت بالفاتورة	لا
منتهية الصلاحية	expired	انقضت مهلة الدفع ولم تصل دفعة	نعم، لساعة إضافية بعد الانتهاء
ملغاة	canceled	ألغى التاجر الفاتورة يدويًا أو عبر API	لا

انتقالات الحالة

• إنشاء الفاتورة. تحصل الفاتورة فورًا على الحالة غير مدفوعة (Unpaid).
• غير مدفوعة ← مدفوعة. وصلت دفعة بمبلغ الفاتورة بالضبط، أو ربط التاجر دفعة يدويًا.
• غير مدفوعة ← منتهية الصلاحية. انقضت مهلة الدفع من دون أن تصل دفعة.
• غير مدفوعة ← ملغاة. ألغى التاجر الفاتورة.
• منتهية الصلاحية ← مدفوعة. وصلت الدفعة خلال ساعة بعد انتهاء الصلاحية ووجدتها الخدمة تلقائيًا، أو ربطها التاجر يدويًا.
• ملغاة. حالة نهائية؛ لا عودة منها.

الفاتورة في الحالة مدفوعة لا تغيّر حالتها أيضًا — لا يمكن دفعها مرة أخرى ولا إلغاؤها.

مهلة الدفع

تُحدد المهلة عند إنشاء الفاتورة وتتراوح من 30 دقيقة إلى 12 ساعة. القيم المسموحة: 30 دقيقة، وساعة واحدة، و3 ساعات، و6 ساعات، و12 ساعة.

حتى انقضاء المهلة يرى المشتري نموذج الدفع ويستطيع دفع الفاتورة. وبعد الانتهاء تنتقل الفاتورة إلى الحالة منتهية الصلاحية (Expired) ولا يعود نموذج الدفع يعرض الدفع.

لكل طرف من الطرفين ثمنه. المهلة القصيرة محفوفة بالخطر على الشبكات البطيئة — قد لا يلحق المشتري في الوقت المحدد. والمهلة الطويلة توسّع الفجوة بين سعر الصرف عند إنشاء الفاتورة وسعره عند الدفع.

نافذة البحث عن الدفعات

يستمر البحث عن الدفعات ساعة إضافية بعد مهلة الدفع — مراعاةً للشبكات البطيئة، حيث قد تتأكد المعاملة بعد انتهاء صلاحية الفاتورة رسميًا. طوال هذا الوقت يرى المشتري الفاتورة منتهية الصلاحية، لكن عندما تصل دفعة بالمبلغ الصحيح، تنتقل تلقائيًا إلى الحالة مدفوعة مع كل الإشعارات.

من هنا قاعدة لمن يبني التكامل: لا ترفض إشعار دفع لأن المهلة انقضت — هذا التحقق يقطع حصة من الدفعات الحقيقية.

إلغاء الفاتورة

تستطيع إلغاء فاتورة إذا كانت تحتوي على خطأ. يتطلب الإلغاء شرطين:

• الفاتورة لم تُدفع — أي أنها في الحالة غير مدفوعة (Unpaid)
• لم يفتح أحد صفحة دفع الفاتورة؛ وعدّاد المشاهدات صفر

يحمي الشرط الثاني من إلغاء فاتورة رآها المشتري بالفعل وربما بدأ دفعها.

الإلغاء لا رجعة فيه. تُستبعد الفاتورة الملغاة من البحث عن الدفعات، ولا يمكن ربط دفعة بها حتى يدويًا. إذا كان الدفع مرجحًا، فانتظر انقضاء المهلة بدل الإلغاء — الفاتورة منتهية الصلاحية ما زال يمكن إغلاقها بدفعة.

ما يُثبَّت عند الإنشاء وما يُعاد حسابه عند الدفع

عند إنشاء الفاتورة تحوّل الخدمة المبلغ الورقي إلى عملات مشفرة بالسعر الحالي وتثبّت المبالغ الناتجة على الفاتورة. هذه هي المبالغ التي يراها المشتري، وهي ما تبحث عنه الخدمة على السلسلة. ولا يعود سعر الصرف يؤثر فيها: مهما مرّ من الوقت، يدفع المشتري المبلغ المثبَّت بالضبط.

وعند لحظة الدفع تعيد الخدمة حساب المبالغ المحاسبية:

الحقل	ما يحدث
amountFiat	مبلغ الفاتورة الأصلي بالعملة الورقية. لا يتغير أبدًا
amountFiatUSD	تستبدله الخدمة بالمبلغ المستلم فعليًا محوَّلًا إلى USD بسعر لحظة الدفع
commissionFiatUSD	يُحسب من جديد من قيمة amountFiatUSD الجديدة بتعرفة المشروع

بسبب حركة سعر الصرف قد تختلف هذه القيم عن الأصلية حتى عندما تكون الدفعة مضبوطة. وللمطابقة مع الطلب في متجرك استخدم amountFiat — المبلغ الوحيد الذي يبقى من دون تغيير.

الإشعارات على مدى حياة الفاتورة

تُضبط الإشعارات لكل مشروع على حدة. وللفاتورة إشعاران:

• دفعة واردة (Incoming payment). يُرسل إلى البريد الإلكتروني وTelegram عند اكتشاف أي معاملة واردة على محفظتك، سواء ارتبطت بفاتورة أم لا.
• الفاتورة مدفوعة (Invoice paid). يُرسل إلى البريد الإلكتروني وTelegram وWebhook URL لحظة انتقال الفاتورة إلى الحالة مدفوعة — في الربط التلقائي واليدوي كليهما.

يعطي هذا قاعدة تشخيص بسيطة: إذا وصل إشعار دفعة واردة ولم يتبعه إشعار فاتورة مدفوعة، فالدفعة لم ترتبط بسبب اختلاف المبالغ وتحتاج إلى معالجة يدوية.

إعادة المشتري إلى موقع المتجر

في إعدادات المشروع تستطيع تحديد عنواني URL يعود المشتري إليهما من صفحة الدفع:

• رابط النجاح (Successful URL) — إعادة توجيه تلقائية بعد دفع الفاتورة
• رابط الإخفاق (Unsuccessful URL) — إعادة توجيه تلقائية عند فتح فاتورة منتهية الصلاحية أو ملغاة

يُفعَّل كل رابط على حدة. وإذا لم يُحدد الرابط، يبقى المشتري على صفحة الدفع ويرى حالة الفاتورة.

المعطى uid — معرّف الفاتورة للمشتري — يُلحق بالرابط: https://example.com/order/success?uid=AFhygKX21ecd. يستخدمه المتجر للعثور على الطلب وعرض صفحته الخاصة للمشتري.

الوصول إلى هذين الرابطين لا يؤكد الدفع — يستطيع المشتري فتح الرابط يدويًا. سلّم الطلبات بناءً على الـ webhook أو بعد التحقق من حالة الفاتورة عبر API.