Merchant API maʼlumotnomasi

Barcha metodlar uchun umumiy qoidalar va katalogni oʻqish metodlari. Metodlar boʻyicha alohida sahifalar: invoyslar va qaytarishlar, oʻtkazmalar va cheklar, obunalar, webhooklar.

API Crypto Bot bilan mos: mavjud Crypto Bot integratsiyasi faqat bazaviy manzil va token almashtirilgandan keyin ishlaydi. Bu shartnomadan tashqaridagi hamma narsa quyida kengaytma deb belgilangan.

Bu sahifalar yonida butun API uchun mashina oʻqiy oladigan OpenAPI 3.1 spetsifikatsiyasi eʼlon qilingan — har bir metod, obyekt, xato nomi va webhook: crypto-pay-openapi.yaml · crypto-pay-openapi.json. Uni kod generatorlariga, API mijozlariga yoki sunʼiy intellekt vositalaringizga bering.

Bazaviy manzil va autentifikatsiya

Barcha metodlar https://crypto.tgpaybot.com/pay/api/<methodName> manzilida joylashgan.

Har bir soʻrov TgCryptoPay-API-Token sarlavhasidagi token bilan autentifikatsiya qilinadi (Crypto-Pay-API-Token moslik uchun muqobil nom sifatida qabul qilinadi; ikkalasi yuborilsa, kanonik nom ustun keladi). Yetishmayotgan, notoʻgʻri yoki bekor qilingan token — shuningdek oʻchirilgan ilovaning tokeni — 401 unauthorized qaytaradi.

Token <app_id>:<secret> koʻrinishida boʻladi va bir marta — yaratishda yoki yangilashda — koʻrsatiladi; server faqat uning xeshini saqlaydi. Qarang: Dasturchi sifatida ishni boshlash.

Tokenlar va huquqlar

Bir xilda autentifikatsiya qilinadigan ikki xil kalit bor:

• Asosiy token — barcha metodlarga toʻliq kirish va webhooklarni imzolaydigan yagona kalit.
• Cheklangan tokenlar (kengaytma) — har bir ilovada 10 tagacha amaldagi token; Yana → Merchant API boʻlimidagi Cheklangan tokenlar blokida yaratiladi, har biri oʻz nomi va huquqlar toʻplami bilan. Bittasini bekor qilish bir zumda boʻladi va qolganlariga tegmaydi; asosiy tokenni yangilash ham ularga tegmaydi.

Huquq	Qaysi metodlarni ochadi
(istalgan amaldagi token)	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

Huquqlar bir-biridan mustaqil va qoʻshiladi — invoices huquqi read huquqini oʻz ichiga olmaydi, shuning uchun faqat invoys chiqaradigan server hech narsa oʻqiy olmaydigan tokenni ushlab tursa ham boʻladi. Token qamrab olmagan metodni chaqirish 403 scope_required qaytaradi. getMe joriy tokenning huquqlarini (scopes; asosiy token uchun null) va nomini (token_name) bildiradi — qoʻlingizda nima borligini har doim tekshira olasiz.

Soʻrovlar va javoblar

• Oʻqish metodlari — GET, parametrlari query-satrda. Mablagʻni harakatlantiruvchi metodlar — faqat POST: parametrlar JSON-tanada, form-urlencoded yoki query-parametrlarda (ziddiyatda tana ustun keladi); multipart/form-data qabul qilinmaydi.
• Har bir javob — bitta konvertdagi JSON: muvaffaqiyat {"ok": true, "result": …}, xato {"ok": false, "error": {"code": <HTTP status>, "name": "<error_name>"}}. error.name boʻyicha shoxlaning — bu barqaror, mashina oʻqiydigan satr.
• Bitta chekka holat: GET metodidagi notoʻgʻri turdagi query-qiymat (masalan, offset=abc) konvertdan tashqarida {"detail": …} tanasi bilan HTTP 422 qaytaradi. Query-qiymatlarni toʻgʻri turda uzating.

Summalar

• Kriptosummalar — aktivning butun birliklaridagi oʻnlik satrlar ("10.5"), hech qachon JSON-sonlar emas. Javoblarda qoʻshimcha ravishda amount_minor (kengaytma) ham bor: minor birliklardagi butun summa satr koʻrinishida, chunki wei masshtabidagi qiymatlar JavaScriptdagi Number turini toʻldirib yuboradi.
• Har bir aktivning decimals qiymatini getCurrencies javobidan oling — arifmetikani kodga yozib qoʻyilgan jadvalga emas, shu maʼlumotga quring.
• Fiat summalarda kasr qismi koʻpi bilan 2 xonali.
• Kurslar — qatʼiy nuqtali satrlar, hech qachon sonlar emas.

Sahifalash

Roʻyxat metodlari (getInvoices, getChecks, getTransfers, getSubscriptions) offset (standart 0) va count (standart 100, maksimum 1000; getSubscriptions uchun 500) parametrlarini qabul qiladi va {"items": […]} qaytaradi, yangilari birinchi. ID boʻyicha filtrlar (invoice_ids, check_ids, transfer_ids) — vergul bilan ajratilgan butun sonlar roʻyxati. Hamma joydagi vaqt belgilari — ISO 8601 satrlari.

Idempotentlik: spend_id

Mablagʻni harakatlantiruvchi metodlar siz generatsiya qiladigan spend_id kalitini qabul qiladi (1–64 belgi): transfer metodida va transferBatch ichidagi har bir elementda majburiy, createCheck va refundInvoice metodlarida ixtiyoriy (kengaytma — baribir ishlating). Xuddi shu kalit va xuddi shu parametrlar bilan qayta urinish mablagʻni ikkinchi marta koʻchirish oʻrniga dastlabki natijani takrorlaydi, shuning uchun taymaut boʻyicha uzilgan soʻrovni qayta yuborish har doim xavfsiz. Xuddi shu kalit boshqa parametrlar bilan 409 idempotency_conflict qaytaradi; dastlabki soʻrov hali bajarilayotganda qayta urinish esa — 409 idempotency_in_progress.

Soʻrovlar limiti

Har bir ilova uchun, uning barcha tokenlariga umumiy; oshirilsa 429 rate_limited qaytadi:

Metod	Limit
createInvoice, createCheck	daqiqasiga 60 ta
refundInvoice, transfer	daqiqasiga 30 ta
transferBatch	daqiqasiga 10 ta

Oʻqish metodlari cheklanmagan. Platformada texnik ishlar vaqtida yozuv metodlari 503 maintenance qaytaradi, oʻqish ishlashda davom etadi.

Katalog va hisob metodlari

getMe

GET /pay/api/getMe — parametrsiz. Ilova maʼlumotlarini qaytaradi: app_id, name, payment_processing_bot_username, webhook_url, webhook_events (ilova obuna boʻlgan qoʻshimcha webhook turlari) va yuqorida tavsiflangan token maydonlari — scopes / token_name.

getBalance

GET /pay/api/getBalance — parametrsiz. Har bir qoʻllanadigan aktiv uchun bittadan satr qaytaradi, hatto nol boʻlsa ham: currency_code, available (sarflash mumkin boʻlgan balans), onhold (faollashtirilmagan cheklaringizda bloklangan mablagʻ) va amount_minor.

getCurrencies

GET /pay/api/getCurrencies — parametrsiz. API nimani qoʻllab-quvvatlashining asosiy roʻyxati: kripto satrlari (is_blockchain: true) va invoys chiqarish mumkin boʻlgan fiat valyutalar (is_fiat: true). Har bir satrda code, name, decimals va is_stablecoin bayrogʻi boʻladi.

getExchangeRates

GET /pay/api/getExchangeRates — parametrsiz. Kripto→fiat kotirovkalari: source, target, rate (qatʼiy nuqtali satr) va is_valid — false boʻlsa, butun jadval eskirgan keshdan berilgan; bunday kurslarni faqat taxminiy deb hisoblang.

getStats

GET /pay/api/getStats — ixtiyoriy start_at / end_at (ISO 8601; standart oyna — oxirgi 24 soat). Quyidagilarni qaytaradi: volume (oyna ichida toʻlangan invoyslarning qiymati, USD), conversion (yaratilganlarning necha foizi toʻlangani), unique_users_count, created_invoice_count, paid_invoice_count va oynaning haqiqiy chegaralari. Oʻqib boʻlmaydigan sana 400 invalid_date qaytaradi.

Har qanday metod qaytarishi mumkin boʻlgan xatolar

HTTP	error.name	Qachon
401	unauthorized	yetishmayotgan, notoʻgʻri yoki bekor qilingan token
403	scope_required	tokenda metod uchun huquq yoʻq
400	invalid_request	oʻqib boʻlmaydigan yoki notoʻgʻri parametrlar (POST)
429	rate_limited	soʻrovlar limiti oshirildi
503	maintenance	texnik ishlar (yozuv metodlari)
500	internal_error	kutilmagan server xatosi

Metodga xos xatolar har bir metodning oʻz sahifasida sanab oʻtilgan.