مرجع واجهة التجار

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

تتبع الواجهة قواعد Crypto Bot للطرق الموثقة هنا. غيّر العنوان الأساسي والرمز، ثم اختبر الطرق التي يستخدمها تكاملك على الشبكة التجريبية. وتُوسم إضافاتنا أدناه بـامتداد.

يتوفر أيضًا وصف OpenAPI 3.1 قابل للقراءة آليًا: crypto-pay-openapi.yaml · crypto-pay-openapi.json. مرّره إلى مولّدات الشيفرة أو عملاء الواجهات أو أدوات الذكاء الاصطناعي لديك، لكن راجع صفحات الطرق أيضًا؛ فقد لا يتضمن المخطط بعض الامتدادات الأحدث بعد.

العنوان الأساسي والمصادقة

كل الطرق تحت https://app.tgpaycrypto.com/pay/api/<methodName>. وفي الشبكة التجريبية يكون العنوان الأساسي https://testnet.tgpaycrypto.com/pay/api — تطبيقات ورموز منفصلة، وعملات تجريبية بلا قيمة حقيقية.

صادِق على كل طلب بالرمز في الترويسة TgPayCrypto-API-Token (وتُقبل TgCryptoPay-API-Token، وهي الاسم المستعمل قبل 2026-09-07، و Crypto-Pay-API-Token اسمين بديلين متوافقين؛ وإذا أُرسلت أكثر من ترويسة فالغلبة للمعتمدة). والرمز الناقص أو غير الصالح أو المُبطَل — أو رمز محدود انتهت صلاحيته، أو رمز تطبيق محذوف، أو رمز مالكه محظور — يعيد 401 unauthorized.

والرمز على الصيغة <app_id>:<secret>، ويُعرض مرة واحدة عند الإنشاء أو التدوير؛ ولا يخزّن الخادم إلا هاشه. راجع البدء كمطوّر.

الرموز والصلاحيات

بيانات الاعتماد نوعان، وكلاهما يُستعمل للمصادقة بالطريقة نفسها:

• الرمز الرئيسي — وصول كامل إلى كل الطرق، وهو المفتاح الوحيد الذي يوقّع الويب هوك.
• رموز محدودة الصلاحيات (امتداد) — حتى 10 رموز غير مُبطلة لكل تطبيق، بما فيها الرموز المنتهية الصلاحية. افتح المزيد ← واجهة التجار، واختر التطبيق، ثم الوصول والرموز. أنشئها تحت رموز محدودة الصلاحيات، لكل رمز تسمية ومجموعة جزئية من الصلاحيات. وإبطال أحدها فوري ولا يمسّ البقية، ولا يمسّها تدوير الرمز الرئيسي كذلك. وقد تكون للرمز صلاحية محددة يتوقف بعدها عن قبول طلبات المصادقة.

الصلاحية	الطرق التي تفتحها
(أي رمز صالح)	getMe و getCurrencies و getExchangeRates
read	getBalance و getStats و getInvoices و getChecks و getTransfers و getSubscriptionPlans و getSubscriptions
invoices	createInvoice و deleteInvoice
refunds	refundInvoice
payouts	transfer و transferBatch
checks	createCheck و deleteCheck
subscriptions	createSubscriptionPlan و archiveSubscriptionPlan و cancelSubscription
webhooks	updateApp

والصلاحيات تراكمية ومستقلة — فـinvoices لا تستلزم read، ومن ثمّ يستطيع خادم لا يفعل إلا إنشاء الفواتير أن يحمل رمزًا لا يتيح قراءة الأرصدة أو سجل المدفوعات. واستدعاء طريقة لا يغطيها الرمز يعيد 403 scope_required. وتُبلِغ getMe عن صلاحيات الرمز الحالي في scopes (وقيمتها null للرمز الرئيسي) وعن token_name، فتعرف دائمًا ما الذي تحمله.

وضع المدفوعات الصادرة

الصلاحية تحدد الطرق التي يجوز للرمز استدعاؤها؛ أما وضع المدفوعات الصادرة في التطبيق فيحدد لمن يجوز لأي من رموزه — بما فيها الرئيسي — أن يدفع. والتطبيق الجديد يدفع لأي أحد من الدقيقة الأولى؛ ويستطيع المالك تضييق ذلك في المزيد ← واجهة التجار بفتح التطبيق ثم إعدادات المدفوعات ← المدفوعات الصادرة عبر الواجهة. يحدّ ذلك من الضرر إن تسرّب الرمز، شأنه في ذلك شأن الحد اليومي. أما توسيعه من جديد فيتطلب PIN أو القياسات الحيوية؛ ولا تستطيع الواجهة إلا قراءته (getMe ← payout_mode).

payout_mode	ما يجوز لـ transfer و transferBatch و createCheck
any	الدفع لأي مستخدم، وحجز المبلغ في الضمان لاسم @username مجهول، وإنشاء شيكات لحاملها — وهو الوضع الافتراضي، وسلوك Crypto Bot
allowlist	الدفع لمستخدمي تيليجرام المدرجين فقط. يجب إدراج كل مستلم لشيك مخصص أو لقائمة مستلمين. أما المستلمون الآخرون وأسماء @username غير المعروفة والشيكات لحاملها فتعيد 403 recipient_not_allowed
off	لا شيء — فكل استدعاء دفع يُرجع 403 payouts_disabled؛ أما الفواتير والاشتراكات والاستردادات والويب هوك فتعمل كالمعتاد

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

الطلبات والاستجابات

• طرق القراءة تُستدعى بـ GET بوسائط في سلسلة الاستعلام. أما الطرق التي تحرّك الأموال فبـ POST حصرًا — وسائطها في جسم JSON، أو بترميز form-urlencoded، أو في سلسلة الاستعلام (والجسم هو الغالب عند التعارض)؛ ويُرفض multipart/form-data.
• تستخدم الاستجابات الصادرة عن معالجات الواجهة غلاف JSON: النجاح {"ok": true, "result": …}، والخطأ {"ok": false, "error": {"code": <HTTP status>, "name": "<error_name>"}}. حدّد الإجراء المناسب بناءً على error.name — فهو معرّف نصي ثابت يمكن لشيفرتك معالجته.
• قد تُرفض قيمة استعلام من نوع خاطئ في طريقة GET (مثل offset=abc) قبل وصول الطلب إلى معالج الواجهة. تحقّق من حالة HTTP، ولا تفترض أن كل استجابة خطأ تستخدم الغلاف أعلاه. أرسل قيم الاستعلام بالأنواع المطلوبة.

المبالغ

• مبالغ العملات الرقمية سلاسل عشرية بوحدات العملة ("10.5") — لا أعدادًا في JSON أبدًا. وتحمل الاستجابات أيضًا amount_minor (امتداد): عدد الوحدات الصغرى على هيئة سلسلة، لأن الأعداد الصحيحة بمقياس wei قد تتجاوز النطاق الذي يمثّله Number في جافاسكربت بدقة.
• و decimals لكل عملة تأتي من getCurrencies — فاجعل حساباتك للمبالغ تنطلق منها بدل ترميزها في الشيفرة.
• الحد الأقصى للمنازل العشرية في مبالغ العملات الورقية: 2.
• والأسعار سلاسل بفاصلة ثابتة، لا أعدادًا.

الترقيم الصفحي

تأخذ طرق القوائم (getInvoices و getChecks و getTransfers و getSubscriptions) الوسيطين offset (افتراضيًا 0) و count (افتراضيًا 100، وبحد أقصى 1000؛ أما getSubscriptions فحدها 500)، وتعيد {"items": […]} بالأحدث أولًا. ومرشِّحات المعرّفات (invoice_ids و check_ids و transfer_ids) قوائم أعداد صحيحة مفصولة بفواصل. والطوابع الزمنية في كل موضع سلاسل بصيغة ISO 8601.

منع التكرار: spend_id

تأخذ الطرق التي تحرّك الأموال مفتاح spend_id يولّده المستدعي (من 1 إلى 64 حرفًا): وهو إلزامي في transfer وفي كل عنصر من transferBatch، واختياري في createCheck و refundInvoice (امتداد — واستعمله على أي حال). وإعادة المحاولة بالمفتاح نفسه والوسائط نفسها تعيد النتيجة الأصلية بدل تحريك الأموال مرتين، فيمكنك دائمًا إعادة محاولة طلب انتهت مهلته دون خطر. أما المفتاح نفسه بوسائط مختلفة فيعيد 409 idempotency_conflict؛ وإعادة المحاولة والأصل ما زال ينفَّذ تعيد 409 idempotency_in_progress.

حدود عدد الطلبات

هذه الحدود لكل تطبيق، ومشتركة بين كل رموزه؛ وتجاوزها يعيد 429 rate_limited:

الطريقة	الحد
createInvoice و createCheck	60 في الدقيقة
refundInvoice	30 في الدقيقة
transfer	30 في الدقيقة
transferBatch	10 في الدقيقة
updateApp	10 في الدقيقة
createSubscriptionPlan	20 في الدقيقة

قد تسري حدود إضافية على الطلبات. عند ظهور 429 rate_limited، زِد مدة الانتظار قبل إعادة المحاولة. وأثناء صيانة المنصة تعيد طرق الكتابة 503 maintenance، بينما تستمر القراءة في العمل.

طرق الكتالوج والحساب

getMe

GET /pay/api/getMe — بلا وسائط. تعيد هوية التطبيق: app_id و name و payment_processing_bot_username و webhook_url و webhook_events (أنواع الويب هوك الإضافية التي اشترك بها التطبيق)، وحقلي فحص الرمز scopes / token_name الموصوفين أعلاه، وpayout_mode (off / allowlist / any)، وdaily_payout_max_usd_cents (القيمة 0 تعني عدم وجود حد يضعه المالك)، وdaily_payout_spent_usd_cents (الإنفاق خلال آخر 24 ساعة).

updateApp

POST /pay/api/updateApp — الصلاحية webhooks. الوسائط الاختيارية: name (من 1 إلى 64 حرفًا)، وwebhook_url (رابط HTTPS عام؛ وتحذفه السلسلة الفارغة)، وwebhook_events (مصفوفة أو قائمة مفصولة بفواصل لأسماء الأحداث الإضافية المدعومة). تُبقي قائمة الأحداث الفارغة invoice_paid وحده. تعيد حقول التطبيق نفسها التي تعيدها getMe.

getBalance

GET /pay/api/getBalance — بلا وسائط. تعيد مصفوفة فيها سطر لكل عملة مدعومة، ولو كان رصيدها صفرًا: currency_code و available (الرصيد القابل للإنفاق) و onhold (أموال الشيكات غير المستلمة والمدفوعات المعلقة لأسماء @username) و amount_minor.

getCurrencies

GET /pay/api/getCurrencies — بلا وسائط. وهي القائمة المعتمدة لما تدعمه الواجهة: أسطر العملات الرقمية (is_blockchain: true) والعملات الورقية التي يمكن تسعير الفواتير بها (is_fiat: true). ويحمل كل سطر code و name و decimals وراية is_stablecoin.

getExchangeRates

GET /pay/api/getExchangeRates — بلا وسائط. أسعار العملات الرقمية مقابل الورقية: source و target و rate (سلسلة بفاصلة ثابتة) وis_valid. تعامل مع هذه الأسعار على أنها استرشادية. لا تضمن is_valid: true حداثة السعر. إذا تعذر الحصول على الأسعار، فقد تكون النتيجة مصفوفة فارغة. استخدم المبالغ والأسعار المسجّلة في الفاتورة لمطابقة سجلاتك مع دفعة فعلية.

getStats

GET /pay/api/getStats — ووسيطاها start_at / end_at اختياريان (بصيغة ISO 8601؛ والفترة الافتراضية هي آخر 24 ساعة). تعيد volume (قيمة الفواتير المدفوعة خلال الفترة، مقدّرة بالدولار وفق الأسعار الحالية؛ وتُحتسب العملات التي لا يتوفر لها سعر بقيمة صفر) و conversion (المدفوع إلى المُنشأ، نسبة مئوية) و unique_users_count و created_invoice_count و paid_invoice_count، وبداية الفترة الفعلية ونهايتها. والتاريخ الذي يتعذّر تحليله يعيد 400 invalid_date.

الأخطاء التي قد تعيدها أي طريقة

HTTP	error.name	متى
401	unauthorized	رمز ناقص أو غير صالح أو مُبطَل
403	scope_required	الرمز لا يملك صلاحية الطريقة
403	payouts_disabled	وضع المدفوعات الصادرة في التطبيق هو off (طرق الدفع فقط)
403	recipient_not_allowed	المستلِم غير مدرج في قائمة مستلِمي التطبيق (طرق الدفع فقط)
400	invalid_request	وسائط غير قابلة للتحليل أو غير صالحة (POST)
403	daily_cap_exceeded	ستتجاوز العملية الحد اليومي للمدفوعات الصادرة من التطبيق
403	verification_required	عمليات المالك الصادرة مقيّدة؛ يؤثر ذلك في التحويلات والشيكات والاستردادات
503	merchant_payouts_paused	الخصم من رصيد التطبيق موقوف مؤقتًا
429	rate_limited	تجاوز حد عدد الطلبات
503	maintenance	صيانة المنصة (طرق الكتابة)
500	internal_error	خطأ غير متوقع في الخادم

وأخطاء كل طريقة على حدة مذكورة في صفحتها.

أخطاء دون بنية JSON

لا يكفي أن يكون رد الخطأ نصًا عاديًا أو صفحة HTML لتحديد الطبقة التي أعادته. تحقق من حالة HTTP ومحتوى الرد وترويساته.

إذا أعاد Cloudflare الخطأ error code: 1010، فقد رفض العميل بناءً على بصمة المتصفح قبل وصول الطلب إلى API. صلاحيات الرمز ليست سبب هذا الخطأ من Cloudflare. قد يؤدي غياب User-Agent أو استخدام قيمة غير معتادة إلى تفعيل حماية الشبكة. جرّب إرسال ترويسة User-Agent باسم يعرّف عميلك، مثل MyShop/1.0، ثم أعد الطلب؛ هذا لا يضمن حل المشكلة. إذا استمر الخطأ، أرسل إلى الدعم حالة HTTP ومحتوى الرد وترويساته بعد إزالة الرموز وملفات تعريف الارتباط.