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

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

الواجهة متوافقة مع Crypto Bot: فالتكامل القائم مع Crypto Bot يعمل بعد تغيير العنوان الأساسي والرمز لا غير. وكل ما يتجاوز ذلك العقد موسوم أدناه بـامتداد.

ويُنشر مع هذه الصفحات وصف OpenAPI 3.1 كامل للواجهة يقرأه الحاسوب — كل طريقة وكائن واسم خطأ وويب هوك: crypto-pay-openapi.yaml · crypto-pay-openapi.json. مرّره إلى مولّدات الشيفرة أو عملاء الواجهات أو أدوات الذكاء الاصطناعي لديك.

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

كل الطرق تحت https://app.tgpaycrypto.com/pay/api/<methodName>.

صادِق على كل طلب بالرمز في الترويسة TgPayCrypto-API-Token (وتُقبل 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

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

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

• طرق القراءة تُستدعى بـ 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 422 بجسم {"detail": …} خارج الغلاف. فأرسل قيم استعلام سليمة الأنواع.

المبالغ

• مبالغ العملات الرقمية سلاسل عشرية بوحدات العملة الكاملة ("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 و transfer	30 في الدقيقة
transferBatch	10 في الدقيقة

وطرق القراءة بلا حد. وأثناء صيانة المنصة تعيد طرق الكتابة 503 maintenance، بينما تستمر القراءة في العمل.

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

getMe

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

getBalance

GET /pay/api/getBalance — بلا وسائط. تعيد مصفوفة فيها سطر لكل عملة مدعومة، ولو كان رصيدها صفرًا: currency_code و available (الرصيد القابل للإنفاق) و onhold (المال المحجوز في شيكاتك القائمة) و 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 — وقيمتها false تعني أن الجدول كله يأتي من ذاكرة مؤقتة قديمة؛ فعامل تلك الأسعار على أنها استرشادية فقط.

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	الرمز لا يملك صلاحية الطريقة
400	invalid_request	وسائط غير قابلة للتحليل أو غير صالحة (POST)
429	rate_limited	تجاوز حد عدد الطلبات
503	maintenance	صيانة المنصة (طرق الكتابة)
500	internal_error	خطأ غير متوقع في الخادم

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