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

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

transfer

POST /pay/api/transfer — الصلاحية payouts، والحد 30 في الدقيقة. يُسوَّى فورًا ودفعة واحدة؛ ولا توجد حالة انتظار.

الوسيط	النوع	إلزامي	المعنى
user_id	عدد صحيح	نعم	معرّف المستلِم في تيليجرام. ويجب أن يكون مستخدمًا في التطبيق أصلًا — فالدفع إلى معرّف مجهول يُرجع خطأً بدل أن يترك المال معلَّقًا
asset	نص	نعم	رمز العملة
amount	نص	نعم	سلسلة عشرية موجبة؛ ويحدّه أيضًا الحد الأدنى والأقصى للتحويل الواحد لدى المنصة (تقدير بما يعادل الدولار الأمريكي بالأسعار الحالية)
spend_id	نص	نعم	مفتاح منع التكرار، من 1 إلى 64 حرفًا، فريد لكل عملية دفع
comment	نص	لا	حتى 1024 حرفًا، ويظهر للمستلِم
disable_send_notification	منطقي	لا	true = لا تُشعر المستلِم في تيليجرام

والنتيجة هي كائن التحويل: transfer_id و hash و user_id و asset و amount و amount_minor و spend_id و comment و status (وهي completed دائمًا) و created_at و completed_at.

الأخطاء: 404 user_not_found (المستلِم لم يستخدم التطبيق قط)، و 409 recipient_blocked، و 400 amount_too_small / 400 amount_too_big (خارج حدود التحويل الواحد)، و 409 insufficient_funds، و 404 unknown_asset، و 400 invalid_amount، وزوج spend_id: 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

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

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

وتُسوَّى العناصر كلٌّ على حدة، بالترتيب — فالعنصر الفاشل لا يُلغي ما سواه. ويعيد الاستدعاء 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 (مطابقة تامة — للبحث عن عملية دفع بمفتاحك أنت)، إضافة إلى offset / count. تعيد {"items": [transfer, …]} بالأحدث أولًا.

createCheck

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

الوسيط	النوع	إلزامي	المعنى
asset	نص	نعم	رمز العملة
amount	نص	نعم	سلسلة عشرية موجبة
pin_to_user_id	عدد صحيح	لا	لا يستلمه إلا صاحب هذا المعرّف في تيليجرام
pin_to_username	نص	لا	لا يستلمه إلا صاحب اسم المستخدم هذا (و @ اختيارية؛ ويُهمَل هذا الوسيط إذا ضُبط pin_to_user_id معه). ويجب أن يكون الاسم لمستخدم قائم في التطبيق
spend_id	نص	لا	مفتاح منع التكرار (امتداد) — استعمله

والنتيجة هي كائن الشيك: check_id و hash و asset و amount و amount_minor و bot_check_url (رابط الاستلام على t.me) و status (active / activated) و pin_to_user_id و created_at و activated_at. ويطلق الاستلام ويب هوك check_activated الاختياري.

الأخطاء: 404 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, …]} بالأحدث أولًا؛ والشيكات المحذوفة لا تُعاد أبدًا.