مرجع الواجهة: التحويلات والشيكات

طرق صرف الأموال. يرسل التحويل الأموال من رصيد تطبيقك إلى محفظة مستخدم في تيليجرام، أو يحجزها حتى يفتح المستلِم الجديد البوت. أما الشيك فرابط لاستلام مبلغ تموّله مسبقًا. والقواعد المشتركة (المصادقة وبنية الاستجابة والمبالغ و spend_id) في صفحة مرجع واجهة التجار.

وتخضع طرق صرف الأموال الثلاث كلها لما يحدده وضع المدفوعات الصادرة في التطبيق: فالتطبيق الجديد يدفع لأي أحد منذ البداية؛ وإذا ضيّق المالك الوضع، فلا يُدفع إلا للمستلِمين المدرجين في القائمة (403 recipient_not_allowed) أو لا يُدفع لأحد أصلًا (403 payouts_disabled). والمالك هو من يضبط الوضع في التطبيق المصغّر؛ ولا تستطيع الواجهة ذلك. أما الأغراض التي يجوز الدفع مقابلها فتحددها شروط واجهة التجار.

transfer

POST /pay/api/transfer — الصلاحية payouts، والحد 30 في الدقيقة. يتلقى المستلِم المعروف المبلغ فورًا. أما إذا كان username غير معروف، فيُنشأ تحويل بحالة pending: تبقى الأموال محجوزة في الضمان حتى يفتح المستلِم البوت باسم المستخدم نفسه. تُعاد الأموال غير المستلمة إلى رصيد التطبيق بعد انقضاء مدة الصلاحية البالغة 30 يومًا (expires_at). تأكد من ظهور status: "returned" قبل احتسابها في سجلاتك. أرسل invite_url إلى المستلِم بنفسك، فالبوت لا يستطيع مراسلة من لم يشغّله من قبل. الحالة النهائية هي completed أو returned؛ اشترك في الويب هوك للأحداث transfer_completed و transfer_returned، أو استعلم دوريًا باستخدام getTransfers.

الوسيط	النوع	إلزامي	المعنى
user_id	عدد صحيح	أحد الوسيطين فقط: user_id / username	معرّف المستلِم في تيليجرام؛ ويجب أن يكون مستخدمًا في التطبيق أصلًا
username	نص	أحد الوسيطين فقط: user_id / username	اسم المستخدم للمستلِم، مع @ أو بدونها؛ والاسم غير المعروف ينشئ عملية دفع قيد الانتظار
asset	نص	نعم	رمز العملة
amount	نص	نعم	سلسلة عشرية موجبة؛ ويحدّه أيضًا الحد الأدنى والأقصى للتحويل الواحد لدى المنصة (تقدير بما يعادل الدولار الأمريكي بالأسعار الحالية)
spend_id	نص	نعم	مفتاح منع التكرار، من 1 إلى 64 حرفًا، فريد لكل عملية دفع
comment	نص	لا	حتى 1024 حرفًا، ويظهر للمستلِم
disable_send_notification	منطقي	لا	تمنع القيمة true إشعار المستلِم عند الدفع الفوري؛ أما استلام تحويل معلّق فيرسل إشعارًا رغم ذلك

والنتيجة هي كائن التحويل: transfer_id و hash و user_id و recipient_username و asset و amount و amount_minor و spend_id و comment و status (pending / completed / returned) و created_at و completed_at و expires_at و invite_url. قد تكون قيمة user_id هي null أثناء انتظار المستلِم الجديد، وتبقى قيمة completed_at هي null حتى يكتمل التحويل.

الأخطاء: 403 payouts_disabled / 403 recipient_not_allowed (وضع المدفوعات الصادرة)، و 404 user_not_found (المعرّف غير معروف أو المستلِم غير متاح)، و 400 invalid_recipient (اسم المستخدم للمستلِم غير صالح)، و 400 amount_too_small / 400 amount_too_big (خارج حدود التحويل الواحد)، و 409 insufficient_funds، و 400 unknown_asset، و 400 invalid_amount، وزوج spend_id: 409 idempotency_conflict / 409 idempotency_in_progress. إذا لم تحدد user_id ولا username، أو حددت كليهما، يعيد الطلب خطأ في الوسائط.

transferBatch

POST /pay/api/transferBatch — الصلاحية payouts، والحد 10 في الدقيقة. وهو امتداد للدفع الجماعي: حتى 100 تحويل في استدعاء واحد.

وسيط واحد: items — مصفوفة كل عنصر فيها مجموعة وسائط transfer كاملة (user_id أو username، و asset و amount و spend_id، ومعها comment و disable_send_notification اختياريين). ويجب أن تكون قيم spend_id فريدة داخل الدفعة، وإلا فشل الاستدعاء كله بـ 400 duplicate_spend_id قبل تنفيذ أي شيء. وقد يُرفض الطلب كله قبل أي عملية دفع أيضًا بسبب بنية عنصر غير صالحة أو وضع المدفوعات الصادرة للتطبيق أو حده اليومي. بعد قبول الطلب، تُعاد النتائج في result.items.

وتُسوَّى العناصر كلٌّ على حدة، بالترتيب — فالعنصر الفاشل لا يُلغي ما سواه. ويعيد الاستدعاء HTTP 200 مع ok: true حتى لو فشل بعض العناصر، فافحص كل عنصر دائمًا:

• النجاح: {"ok": true, "spend_id": "…", "result": <transfer object>}
• الفشل: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} بأسماء الأخطاء نفسها في transfer المفرد.

وتتشارك عناصر الدفعة فضاء أسماء منع التكرار مع التحويلات المفردة: فإعادة إرسال الدفعة كلها — أو إعادة إرسال عنصر منها بوصفه transfer مفردًا بـ spend_id نفسه — تعيد النتيجة الأصلية بدل أن تدفع مرتين.

getTransfers

GET /pay/api/getTransfers — الصلاحية read. المرشِّحات: asset و transfer_ids (مفصولة بفواصل) و spend_id (مطابقة تامة — للبحث عن عملية دفع بمفتاحك أنت)، و status (pending / completed / returned)، إضافة إلى offset / count. تعيد {"items": [transfer, …]} بالأحدث أولًا.

createCheck

POST /pay/api/createCheck — الصلاحية checks، والحد 60 في الدقيقة. ينشئ افتراضيًا شيكًا لمرة واحدة من رصيد تطبيقك. يستطيع استلامه من يملك الرابط، أو المستخدم المحدد وحده. ينشئ الامتداد recipients قائمة مستلمين بمبلغ مستقل لكل منهم. يُحجز الإجمالي عند الإنشاء (ينتقل من available إلى onhold في getBalance). وتسري على إنشاء الشيكات حدود المبالغ والمدفوعات اليومية نفسها المطبّقة على التحويلات.

الوسيط	النوع	إلزامي	المعنى
asset	نص	نعم	رمز العملة
amount	نص	ما لم يُضبط recipients	سلسلة عشرية موجبة؛ ومع recipients يُحسب الإجمالي من القائمة
pin_to_user_id	عدد صحيح	لا	لا يستلمه إلا صاحب هذا المعرّف في تيليجرام
pin_to_username	نص	لا	لا يستلمه إلا صاحب اسم المستخدم هذا (و @ اختيارية؛ ويُهمَل هذا الوسيط إذا ضُبط pin_to_user_id معه). ويجب أن يكون الاسم لمستخدم قائم في التطبيق
spend_id	نص	لا	مفتاح منع التكرار (امتداد) — استعمله
recipients	مصفوفة	لا	امتداد: من 1 إلى 100 عنصر، لكل منها user_id أو username وamount كسلسلة عشرية موجبة. لا يجتمع مع تخصيص الشيك لمستخدم واحد
password	نص	لا	امتداد: كلمة مرور مطلوبة للاستلام، حتى 64 حرفًا
expires_in	عدد صحيح	لا	امتداد: مدة الصلاحية بالثواني؛ إغفاله أو 0 يعني بلا انتهاء

والنتيجة هي كائن الشيك: check_id و hash و asset و amount و amount_minor و bot_check_url (رابط الاستلام على t.me) و status (active / activated) وpin_to_user_id وcreated_at وactivated_at وexpires_at وrecipients (قيمته null للشيك العادي؛ وإلا يحتوي كل عنصر على user_id وusername وamount وamount_minor وclaimed_at). يطلق كل استلام ويب هوك check_activated الاختياري؛ ويشمل استلام حصة من قائمة أيضًا activated_slot. يعيد انتهاء الصلاحية المتبقي غير المستلم؛ وقد يرسل انتهاء شيك القائمة حدث check_expired.

تعرض الاستجابة الحالية كل شيك لم يُستلم بالكامل بحالة status: "active"، حتى لو انتهت صلاحيته. راجع expires_at أيضًا، ولا تعتبر active وحدها دليلًا على إمكانية استلام الرابط.

الأخطاء: 403 payouts_disabled / 403 recipient_not_allowed (وضع المدفوعات الصادرة — ففي الوضع allowlist يجب إدراج كل مستلم محدد أو موجود في قائمة المستلمين)، و 400 unknown_asset و 400 invalid_amount و 404 user_not_found (اسم المستخدم المحدَّد لا يطابق أحدًا) و 409 insufficient_funds، وزوج spend_id.

deleteCheck

POST /pay/api/deleteCheck — الصلاحية checks. وسيط واحد: check_id. يلغي شيكًا نشطًا ويعيد المتبقي غير المستلم إلى رصيد تطبيقك؛ ويعيد true. الأخطاء: 404 check_not_found و 409 check_not_active (استُلم بالكامل أو انتهت صلاحيته أو حُذف).

getChecks

GET /pay/api/getChecks — الصلاحية read. المرشِّحات: asset و check_ids (مفصولة بفواصل) و status (active / activated)، إضافة إلى offset / count. تعيد {"items": [check, …]} بالأحدث أولًا؛ والشيكات المحذوفة لا تُعاد أبدًا.