রিসেলার API ডকুমেন্টেশন

বেস URL ও ট্রান্সপোর্ট

এই রেফারেন্সের সব পাথ নিচের বেস URL-এর সাপেক্ষে লেখা। রিকোয়েস্ট ও রেসপন্স HTTPS-এর মাধ্যমে JSON আকারে আসা-যাওয়া করে। পরিমাণগুলো স্ট্রিং হিসেবে থাকে, তাই float রাউন্ডিংয়ের ভুল ঢোকার সুযোগ নেই। প্রতিটি টাইমস্ট্যাম্প ISO 8601 ফরম্যাটে, UTC সময়ে দেওয়া হয়।

https://shop2topup.com/api/endpoints/v1

অথেন্টিকেশন

প্রতিটি রিকোয়েস্টে একটি হেডার পাঠাতে হয়। API key পেয়ারটি আপনার রিসেলার প্যানেলের API Access পেজ থেকে ইস্যু করা হয়, আর চাইলে IP অ্যালাউলিস্ট দিয়ে সীমিত করা যায়। তালিকার বাইরের কোনো ঠিকানা থেকে কল এলে বিজনেস লজিকে পৌঁছানোর আগেই IP_NOT_ALLOWED দিয়ে তা বাতিল হয়ে যায়।

Authorization: Bearer <keyId>.<secret>

প্রথম কল

কিছু ইনস্টল করতে হবে না। নিজের API key বসিয়ে দিন, লাইভ ক্যাটালগের ডেটা চলে আসবে।

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

রেসপন্সের নিয়ম

• প্রতিটি রেসপন্সে একটি boolean success ফিল্ড থাকে। তাই একটি মাত্র শর্তেই সফল রেসপন্স আর যেকোনো ব্যর্থতা আলাদা করা যায়।
• ব্যর্থ হলে একটি error অবজেক্ট আসে, যাতে থাকে স্থায়ী একটি code, মানুষের পড়ার মতো একটি message আর ঐচ্ছিক details। শর্ত লিখুন code দেখে, message দেখে কখনো নয়।
• অর্থের মান সবসময় USD-তে দশমিক স্ট্রিং হিসেবে আসে, যেমন "0.950000"। তুলনা বা যোগ করার আগে একে binary float-এ পার্স করবেন না।
• তালিকা ফেরত দেওয়া এন্ডপয়েন্টগুলোর রেসপন্সে একটি পেজিনেশন অবজেক্ট থাকে, যার ভেতরে থাকে page, limit, total ও total_pages।
• আপনার দেওয়া order_id UUID-এর ভিত্তিতে অর্ডার তৈরি idempotent। তাই আবার চেষ্টা করলেও কখনো দুবার চার্জ কাটা হবে না।

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "action": "FIX_INPUT",
    "retryable": false,
    "retry_after": null,
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

রেফারেন্সের অংশগুলো

রেট লিমিট

লিমিট প্রতিটি অ্যাকাউন্টের জন্য আলাদা, আর তা গোনা হয় রোলিং উইন্ডোতে। ক্যাটালগ, অর্ডার ও অ্যাকাউন্ট এন্ডপয়েন্টে X-RateLimit-Limit, X-RateLimit-Remaining ও X-RateLimit-Reset থাকে। থ্রটল হওয়া কল 429 ফেরত দেয়, সঙ্গে থাকে Retry-After হেডার। প্লেয়ার ভ্যালিডেশনের হিসাব অবশ্য চলে আপনার দৈনিক প্লেয়ার-চেক কোটা দিয়ে: এটি কোনো X-RateLimit হেডার পাঠায় না, কোটার তথ্য দেয় 429 body-র ভেতরে।

ওয়েবহুক

অর্ডারের ফলাফল আপনার রেজিস্টার করা HTTPS এন্ডপয়েন্টে পাঠানো হয়, raw body-র ওপর HMAC-SHA256 সিগনেচারসহ। ইভেন্টের তালিকা, হেডারের তালিকা, payload-এর গঠন আর যাচাইয়ের একটি কোড স্নিপেট API ওভারভিউ পেজে দেওয়া আছে।