مرجع API پذیرنده

قراردادهای مشترک همه‌ی متدها، به‌علاوه‌ی متدهای کاتالوگِ فقط‌خواندنی، در همین صفحه آمده است. صفحه‌های متد به متد: صورت‌حساب و بازگشت وجه، انتقال و چک، اشتراک‌ها، وب‌هوک‌ها.

این API با Crypto Bot سازگار است: اگر پیش‌تر با Crypto Bot یکپارچه شده‌اید، کافی است آدرس پایه و توکن را عوض کنید. هر چیزی فراتر از آن قرارداد، پایین‌تر با افزوده مشخص شده است.

مشخصات ماشین‌خوان OpenAPI 3.1 از کل API — همه‌ی متدها، شیءها، نام خطاها و وب‌هوک‌ها — کنار همین صفحه‌ها منتشر شده است: crypto-pay-openapi.yaml · crypto-pay-openapi.json. آن را به تولیدکننده‌های کد، کلاینت‌های API یا ابزارهای هوش مصنوعی‌تان بدهید.

آدرس پایه و احراز اصالت

همه‌ی متدها روی https://crypto.tgpaybot.com/pay/api/<methodName> قرار دارند.

هر درخواست را با توکن در هدر TgCryptoPay-API-Token احراز اصالت کنید (Crypto-Pay-API-Token به‌عنوان نام جایگزین سازگاری پذیرفته می‌شود؛ اگر هر دو فرستاده شوند، نام رسمی برنده است). اگر توکن فرستاده نشود، نامعتبر یا باطل باشد — یا توکن برنامه‌ای باشد که حذف شده — پاسخ 401 unauthorized برمی‌گردد.

توکن به شکل <app_id>:<secret> است و فقط یک بار، موقع ساخت یا تعویض، نشان داده می‌شود؛ سرور تنها هش آن را نگه می‌دارد. شروع کار برای توسعه‌دهنده‌ها را ببینید.

توکن‌ها و دامنه‌های دسترسی

دو نوع اعتبارنامه به یک شکل احراز می‌شوند:

• توکن اصلی — دسترسی کامل به همه‌ی متدها، و تنها کلیدی که وب‌هوک‌ها را امضا می‌کند.
• توکن‌های محدود (افزوده) — تا 10 توکن زنده برای هر برنامه، ساخته‌شده در بیشتر ← API پذیرنده زیر توکن‌های محدود، هرکدام با یک برچسب و زیرمجموعه‌ای از دامنه‌ها. ابطال یکی آنی است و بر بقیه اثری ندارد؛ تعویض توکن اصلی هم به آن‌ها دست نمی‌زند.

دامنه	متدهایی که باز می‌کند
(هر توکن معتبر)	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 — بدون پارامتر. فهرست معتبر آنچه API پشتیبانی می‌کند: سطرهای رمزارز (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	خطای غیرمنتظره‌ی سرور

خطاهای خاص هر متد در صفحه‌ی خود آن متد آمده است.