مرجع الواجهة: الفواتير والاسترداد

طرق الفواتير: createInvoice و getInvoices و deleteInvoice و refundInvoice. والقواعد المشتركة (المصادقة والغلاف والمبالغ و spend_id) في صفحة مرجع واجهة التجار؛ أما الشرح المتدرّج فهو قبول المدفوعات بالفواتير.

createInvoice

POST /pay/api/createInvoice — الصلاحية invoices، والحد 60 في الدقيقة.

الوسيط	النوع	إلزامي	المعنى
currency_type	نص	لا	crypto (الافتراضي) أو fiat
asset	نص	في وضع العملات الرقمية	العملة المطلوب تحصيلها، مثل USDT. ولا يجوز مع fiat
fiat	نص	في الوضع الورقي	العملة الورقية التي حُدّد بها السعر (أسطر is_fiat من getCurrencies)
accepted_assets	نص / مصفوفة	لا	في الوضع الورقي فقط: العملات التي يجوز للدافع الدفع بها — سلسلة مفصولة بفواصل ("USDT,GRAM") أو مصفوفة JSON. وإغفاله يعني كل العملات المدعومة
amount	نص	نعم، ما لم يُضبط open_amount	سلسلة عشرية موجبة: وحدات العملة في الوضع الرقمي، ووحدات العملة الورقية (بحد أقصى 2 منزلة عشرية) في الوضع الورقي
open_amount	منطقي	لا	امتداد، وفي الوضع الرقمي فقط: بلا مبلغ ثابت — يُدخل الدافع المبلغ عند الدفع (التبرعات والإكراميات). ولا يجتمع مع amount
description	نص	لا	حتى 1024 حرفًا، ويظهر للدافع
hidden_message	نص	لا	حتى 2048 حرفًا، ولا يُكشف للدافع إلا بعد الدفع
payload	نص	لا	حتى 4096 حرفًا من بياناتك أنت، تعود إليك في الفاتورة وفي الويب هوك
allow_comments	منطقي	لا	يسمح للدافع بإرفاق تعليق (الافتراضي true)
allow_anonymous	منطقي	لا	يسمح للدافع بإخفاء هويته (الافتراضي true)
paid_btn_name	نص	لا	زر ما بعد الدفع: viewItem أو openChannel أو openBot أو callback
paid_btn_url	نص	لا	رابط الزر http(s) — وهو إلزامي متى ضُبط paid_btn_name
swap_to	نص	لا	مبادلة المدفوعات الواردة تلقائيًا إلى هذه العملة. ويجري ذلك بأفضل جهد: فإن تعذّرت المبادلة لحظة الدفع نجحت الدفعة دون مبادلة
expires_in	عدد صحيح	لا	عدد الثواني حتى انتهاء صلاحية الفاتورة، حتى 2678400 (31 يومًا)؛ وإغفاله أو 0 يعني بلا انتهاء
rate_lock_seconds	عدد صحيح	لا	امتداد، وفي الوضع الورقي فقط: تثبيت أسعار التحويل لحظة الإنشاء طوال هذه المدة (انظر أدناه)

والنتيجة — وهي أيضًا حمولة ويب هوك invoice_paid — هي كائن الفاتورة. وأهم حقوله:

• الهوية والحالة: invoice_id و hash (المعرّف العلني داخل pay_url) و status (active / paid / expired) و pay_url — وهو رابط t.me الذي ترسله إلى الدافع (و bot_invoice_url و mini_app_invoice_url و web_app_invoice_url أسماء بديلة له).
• المبالغ: amount (القيمة الاسمية — بوحدات العملة الورقية في الفاتورة الورقية، وبالعملة الرقمية فيما عداها؛ وقيمته null ما دامت فاتورة المبلغ المفتوح غير مدفوعة) و amount_minor، وفي الفواتير الورقية المدفوعة paid_asset / paid_amount / paid_fiat_rate — أي العملة الرقمية التي حُصِّلت فعلًا والسعر المستعمل.
• الرسوم: fee_asset / fee_amount، وتُسجَّل لحظة الدفع — وهي الرقم المعتمد في دفاترك (fee و usd_rate اسمان بديلان مهجوران من Crypto Bot). راجع الرسوم والحدود.
• الدافع: paid_by_user_id (وقيمته null متى اختار الدافع إخفاء هويته) و paid_anonymously و comment.
• الاسترداد (امتداد): refunded_amount / refunded_minor (تراكميان) و refunded_at، ويُسجَّل متى استُرد المبلغ كاملًا.
• تثبيت السعر (امتداد): rate_lock_until و rate_lock_rates — وهي الأسعار المسجّلة لكل عملة، وقيمتها null إن لم يُطلب التثبيت.
• كما أُنشئت: description و hidden_message و payload و paid_btn_name / paid_btn_url و expiration_date (و expires_at اسم بديل له)، وحقول المبادلة (swap_to و is_swapped و swapped_to و swapped_rate و swapped_output…).

الأخطاء: 400 invalid_currency (خلط بين العملة الرقمية والورقية)، و 400 invalid_amount، و 404 unknown_asset، و 400 unsupported_fiat، و 400 paid_btn_url_required؛ وفي طلبات تثبيت السعر: 400 rate_lock_fiat_only و 409 ratelock_disabled و 409 rate_unavailable (لا يوجد سعر حديث لإحدى العملات المقبولة — أعد المحاولة).

كيف تُدفع الفواتير

يدفع الدافع من رصيد محفظته في التطبيق المصغّر — فورًا وبلا رسوم شبكة. ويستطيع أيضًا تمويل الفاتورة من محفظة خارجية: فيعرض له التطبيق عنوان إيداع، ويصل تحويله إلى محفظته هو، وتُدفع الفاتورة تلقائيًا فور وصوله. وفي الحالتين ترى أنت الشيء نفسه: فاتورة paid عادية وويب هوك invoice_paid — بلا وسائط ولا حقول إضافية تعالجها.

وفي الفاتورة الورقية يُحسب المبلغ بالعملة الرقمية لحظة الدفع، ويُقرَّب إلى الأعلى لمصلحتك، فلا تستلم أبدًا أقل من القيمة الاسمية بالعملة الورقية. وإن لم يتوفر سعر حديث، فشلت الدفعة عند الدافع بدل أن تُسوَّى بسعر قديم.

تثبيت السعر في الفاتورة الورقية

مرّر rate_lock_seconds ليُسجَّل السعر الحالي لكل عملة مقبولة لحظة الإنشاء. وما دام التثبيت ساريًا يرى الدافع المبالغ المسجّلة بالضبط، ويجري التحويل بالسعر المسجَّل — وتتحمّل أنت مخاطرة السعر طوال النافذة. ويحصر الخادم النافذة بين 60 ثانية والحد الأقصى للمنصة (15 دقيقة حاليًا).

وحين ينقضي التثبيت تبقى الفاتورة قابلة للدفع وتعود بهدوء إلى التحويل بسعر لحظة الدفع. فإن أردت أن تنتهي الفاتورة بانتهاء التثبيت، فاضبط expires_in على القيمة نفسها.

getInvoices

GET /pay/api/getInvoices — الصلاحية read. المرشِّحات: asset و fiat و invoice_ids (مفصولة بفواصل) و status (active / paid / expired — و expired امتداد؛ أما active فتستثني الفواتير التي تجاوزت أجلها)، إضافة إلى offset / count. تعيد {"items": [invoice, …]} بالأحدث أولًا.

deleteInvoice

POST /pay/api/deleteInvoice — الصلاحية invoices. وسيط واحد: invoice_id. يلغي فاتورة غير مدفوعة ويعيد true. الأخطاء: 404 invoice_not_found و 409 invoice_already_paid — فالفاتورة المدفوعة لا تُحذف، لأن المال قد تحرّك فعلًا.

refundInvoice

POST /pay/api/refundInvoice — الصلاحية refunds، والحد 30 في الدقيقة. وهو امتداد على Crypto Bot: يعيد المبلغ الاسمي لفاتورة مدفوعة — أو جزءًا منه — من رصيد تطبيقك إلى من دفعها، ولو دفع دون كشف هويته، ودون أن تنكشف هويته.

الوسيط	النوع	إلزامي	المعنى
invoice_id	عدد صحيح	نعم	الفاتورة المدفوعة
amount	نص	لا	المبلغ المطلوب استرداده بعملة الفاتورة. وإغفاله يعني كامل المتبقي غير المسترد. وتتراكم الاستردادات الجزئية حتى المبلغ الاسمي
spend_id	نص	لا	مفتاح منع التكرار — استعمله لتعيد محاولةٌ انتهت مهلتها النتيجة نفسها بدل أن تسترد المبلغ مرتين

والنتيجة هي كائن الفاتورة بعد تحديثه ومعه refunded_amount / refunded_minor التراكميان؛ ويُسجَّل refunded_at متى استُرد المبلغ كاملًا. وتبقى الحالة paid. ولا تُعاد رسوم المنصة. ويطلق كل استرداد ويب هوك refund_completed الاختياري.

الأخطاء: 404 invoice_not_found و 409 invoice_not_paid و 409 already_refunded (لم يبق شيء للاسترداد) و 409 amount_too_big (أكثر من المتبقي غير المسترد) و 409 insufficient_funds و 400 invalid_amount، وزوج spend_id: 409 idempotency_conflict / 409 idempotency_in_progress.