ربط الدفعات واختلاف المبالغ

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

حالات الفاتورة والمهل وانتقالات الحالة يصفها قسم دورة حياة الفاتورة.

قاعدة تطابق المبلغ

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

يجب أن يطابق مبلغ الدفعة مبلغ الفاتورة بالضبط. لا هامش تسامح. يتكوّن المبلغ المستحق بمنزلتين عشريتين للعملتين المستقرتين USDT وUSDC، وبثماني منازل عشرية لبقية العملات المشفرة، وتُقارن الدفعة الواردة به بدقة. أي انحراف — دفع ناقص أو زائد، مهما صغر — يعني أن الربط التلقائي لن يحدث.

مثال. فاتورة بمبلغ 100.00 USD صدرت بمبلغ مثبَّت قدره 100.12 USDT.

مبلغ الدفعة الواردة	النتيجة
100.12 USDT	تنتقل الفاتورة تلقائيًا إلى الحالة مدفوعة (Paid)
100.11 USDT	لا ربط تلقائيًا
100.50 USDT	لا ربط تلقائيًا

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

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

ما يحدث عند اختلاف المبالغ

تسجّل الخدمة وصول الأموال لكنها لا تتخذ أي إجراء على الفاتورة:

• لا تغيّر الفاتورة حالتها. تبقى غير مدفوعة حتى مهلة الدفع. وما زال المشتري يستطيع إغلاقها بالمبلغ الصحيح ما دامت نافذة البحث مفتوحة.
• لا يُرسل أي webhook. لا يخرج الإشعار إلى Webhook URL إلا لحظة انتقال الفاتورة إلى الحالة مدفوعة.
• لا يُتتبع الدفع الجزئي. لا تتعرف الخدمة على الدفع الناقص ولا تحتفظ بمبلغ متبقٍ على الفاتورة.
• لا تُجمع الدفعات. إذا أتبع المشتري دفعًا ناقصًا بمعاملة ثانية بالفارق الناقص، لا تُجمع الدفعتان. تبقى كلتاهما دفعتين منفصلتين غير مرتبطتين.
• لا يُرد الدفع الزائد تلقائيًا. تذهب الأموال مباشرة إلى محفظتك؛ ورد الفارق إلى المشتري يجري خارج الخدمة.

لا توجد في الخدمة حالات وسيطة مثل مدفوعة جزئيًا أو مدفوعة بزيادة.

كيف يعلم التاجر بالمشكلة

إذا كانت الإشعارات مفعَّلة في إعدادات المشروع، يتلقى التاجر رسالة بريد إلكتروني ورسالة من بوت Telegram عن كل دفعة واردة — سواء ارتبطت بفاتورة أم لا.

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

لا تعمل القاعدة إلا داخل نافذة البحث. لا تراقب الخدمة المحافظ إلا ما دامت فاتورة واحدة على الأقل ببحث نشط. وإذا دفع المشتري حين لا توجد فواتير كهذه، لا تدخل الدفعة النظام إطلاقًا — لا إشعار، ولا سبيل إلى ربطها يدويًا.

تستطيع أيضًا العثور على الدفعات غير المرتبطة برمجيًا. تعيد الطريقة payments/list الدفعات عبر كل محافظك، والدفعة غير المرتبطة بفاتورة لا تحمل كائن invoice في الاستجابة. هذه هي المرشحة للربط اليدوي: قارن المبلغ والوقت بالفاتورة المتوقعة واستدعِ invoices/bindPayment.

الربط اليدوي للدفعات

إذا كنت متأكدًا من الدفعة المقابلة لكل فاتورة، فاربطهما يدويًا — في لوحة التحكم على صفحة الفاتورة أو في قائمة الدفعات، أو عبر API بالطريقة invoices/bindPayment.

شروط الربط

لا يكون الربط ممكنًا إلا عندما تتحقق كل الشروط معًا:

1. الفاتورة غير مدفوعة (Unpaid) أو منتهية الصلاحية (Expired). لا يمكن ربط الفواتير الملغاة والمدفوعة بالفعل.
2. الدفعة غير مرتبطة بفاتورة أخرى بعد. لا تُربط الدفعة الواحدة إلا بفاتورة واحدة.
3. وصلت الدفعة إلى محفظة مشارِكة في هذه الفاتورة.
4. تقع الدفعة داخل نافذة الدفع المتاحة — 24 ساعة قبل إنشاء الفاتورة و24 ساعة بعده.

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

ما يحدث بعد الربط

• تنتقل الفاتورة إلى الحالة مدفوعة — تمامًا كما في الربط التلقائي.
• يُرسل الـ webhook دائمًا. يخرج الإشعار عند كل انتقال إلى الحالة مدفوعة، بصرف النظر عن طريقة الربط.
• يُعاد حساب مبلغ الفاتورة بـ USD من الدفعة الفعلية. تستبدل الخدمة قيمة الحقل amountFiatUSD بالمبلغ المستلم فعليًا، بسعر لحظة الربط. المبلغ الأصلي في amountFiat لا يتغير.
• يُعاد حساب العمولة من المبلغ الفعلي. تُحسب بتعرفة المشروع على المبلغ الذي استلمته.