රීසෙලර් API ලේඛන

SHOP2TOPUP රීසෙලර් API යනු JSON භාවිත කරන REST API එකකි. එමගින් ඔබේම ෂොප් එකෙන්, ඔන්ලයින් ස්ටෝර් එකෙන් හෝ බොට් එකෙන් ගේම් ටොප් අප්, ගේම් රීචාජ් සහ වවුචර් කෝඩ් විකිණිය හැක. මෙම ලේඛනයේ සියලුම පොදු එන්ඩ්පොයින්ට්, ඒවායේ පරාමිති සහ ප්‍රතිචාර විස්තර කර ඇත.

මූලික URL ලිපිනය සහ සම්බන්ධතා ක්‍රමය

මෙම ලේඛනයේ ඇති සෑම මාර්ගයක්ම පහත මූලික URL එකට සාපේක්ෂයි. ඉල්ලීම් සහ ප්‍රතිචාර HTTPS හරහා JSON ලෙස හුවමාරු වේ. මුදල් අගයන් string ලෙස එවන නිසා දශම වටකිරීමේ දෝෂ ඇති නොවේ. සියලු වේලා මුද්‍රා UTC වේලාවෙන්, ISO 8601 ආකෘතියට අනුව දැක්වේ.

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

සත්‍යාපනය

සෑම ඉල්ලීමකටම අවශ්‍ය වන්නේ එක් හෙඩරයක් පමණි. යතුරු යුගලය ලබාදෙන්නේ ඔබේ රීසෙලර් පැනලයේ API Access පිටුවෙනි. එය අවසර ලත් IP ලැයිස්තුවකට සීමා කළ හැකි අතර, වෙනත් ලිපිනයකින් එන ඇමතුමක් කිසිදු ව්‍යාපාරික තර්කයක් ක්‍රියාත්මක වීමට පෙර IP_NOT_ALLOWED දෝෂයෙන් ප්‍රතික්ෂේප වේ.

ඉල්ලීමේ හෙඩරය

Authorization: Bearer <keyId>.<secret>

පළමු ඇමතුම

ස්ථාපනය කිරීමට කිසිවක් නැත. ඔබේම key එක දැමූ විට මෙයින් සජීවී කැටලොග් දත්ත ලැබේ.

cURL මගින් යවන ඉල්ලීම

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

ප්‍රතිචාරවල සම්මත ආකෘතිය

සෑම response එකකම boolean success field එකක් ඇත. ඒ නිසා එක් branch එකකින් සාර්ථක ප්‍රතිඵලය සියලු අසාර්ථක අවස්ථාවලින් වෙන් කළ හැක.
ඉල්ලීමක් අසාර්ථක වූ විට error object එකක් ලැබේ. එහි නොවෙනස් වන කෝඩ් එකක්, මිනිසුන්ට කියවිය හැකි පණිවිඩයක් සහ සමහර අවස්ථාවල අමතර විස්තර අඩංගුයි. තීරණ ගැනීමට කෝඩ් එක පමණක් භාවිත කරන්න. පණිවිඩය කිසිවිටෙක ඒ සඳහා යොදා නොගන්න.
මුදල් සෑම විටම USD වලින්, "0.950000" වැනි decimal string එකක් ලෙස එයි. සසඳන්නට හෝ එකතු කරන්නට පෙර එය binary float එකකට parse නොකරන්න.
ලැයිස්තුවක් ලබාදෙන සෑම එන්ඩ්පොයින්ට් එකක්ම පිටු තොරතුරු සහිත pagination වස්තුවක් ද ආපසු එවයි. එහි page, limit, total සහ total_pages යන ක්ෂේත්‍ර හතර ඇතුළත් වේ.
ඇණවුම් සෑදීම ඔබ ලබා දෙන order_id UUID එක මත idempotent වේ. එබැවින් retry එකකින් කිසි විටෙකත් දෙවරක් මුදල් අය නොවේ.

දෝෂ ප්‍රතිචාරය

{
  "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"
    }
  }
}

යොමු කොටස්

කැටලොග්කැටලොග් එක මට්ටම් තුනක ගසකි: ප්‍රධාන කාණ්ඩ තුළ කාණ්ඩ ඇති අතර, කාණ්ඩ තුළ උප කාණ්ඩ ඇත. ඔබ ඇත්තටම මිලදී ගන්නේ උප කාණ්ඩයයි. මෙම endpoints මගින් එම ගස ඔබේම database එකට පිටපත් කර ගැනීමටත්, ඇණවුම් කිරීමට මොහොතකට පෙර item එකක මිල බලා ගැනීමටත් හැකිය.ක්‍රීඩක තහවුරු කිරීමමුදල් හුවමාරුවක් සිදු වීමට පෙර ක්‍රීඩක තොරතුරු තහවුරු කිරීමෙන් ගේම් ගිණුම හඳුනා ගනී. ලබා දුන් හැඳුනුම අදාළ නිෂ්පාදනය සඳහා පවතින බව තහවුරු කර, ගැනුම්කරුට පරීක්ෂා කිරීමට ගේම් එකේ භාවිත වන නම ලබා දෙයි. ගිණුමේ කලාපයද පෙන්වන නිසා කලාපය නොගැළපෙන ඇණවුමක් ගෙවීමෙන් පසු අසාර්ථක වීමට පෙර මුල් අදියරේදීම ප්‍රතික්ෂේප කළ හැක.ඇණවුම්ඇණවුමක් සාදන්නේ ඔබ විසින්ම ජනනය කරන UUID එකකින්. එම UUID එක idempotency key එක ලෙස ක්‍රියා කරයි: එය නැවත යැවුවොත් දෙවරක් මුදල් අය නොකර මුල් ඇණවුමම ලැබේ. ඉන්පසු තත්ත්වය එක් එක් ඇණවුමට වෙන වෙනම, උපරිම 50 බැගින් batch වශයෙන්, හෝ පිටු වලට බෙදූ ලැයිස්තුවක් ලෙස කියවිය හැක.ගිණුම සහ සත්‍යාපනයසෑම request එකක් සමඟම යවන්නේ එක header එකක් පමණි. API key එක ක්‍රියා කරන බව තහවුරු කරගැනීමට, ඇණවුම් සඳහා මුදල් අඩු වන වොලට් ශේෂය බැලීමට සහ batch එකක් ආරම්භ කිරීමට පෙර ගිණුම සක්‍රිය දැයි පරීක්ෂා කිරීමට GET /account භාවිත කරන්න.දෝෂ කේතඅසාර්ථක වන සෑම request එකක්ම HTTP තත්ත්වය සමඟ, යන්ත්‍රයකට කියවිය හැකි ස්ථාවර කේතයක් ආපසු දෙයි. ඔබේ logic එක ගොඩනගන්න කේතය මතයි, පණිවිඩයේ පෙළ මත කිසිසේත් නොවේ. පණිවිඩ ලියා ඇත්තේ මිනිසුන්ට කියවීමට නිසා ඒවායේ වචන වෙනස් විය හැක. කේත නම් API ගිවිසුමේම කොටසකි.

ඉල්ලීම් සීමා

සීමා ගණනය කරන්නේ එක් එක් ගිණුමට, නොකඩවා ඉදිරියට යන කාල කවුළුවක් මතයි. කැටලොග්, ඇණවුම් සහ ගිණුම් එන්ඩ්පොයින්ට් X-RateLimit-Limit, X-RateLimit-Remaining සහ X-RateLimit-Reset හෙඩර් එවයි. සීමාව ඉක්මවූ ඉල්ලීමකට 429 ප්‍රතිචාරය Retry-After හෙඩරය සමඟ ලැබේ. ක්‍රීඩක තහවුරු කිරීම මනින්නේ ඒ වෙනුවට ඔබේ දෛනික ක්‍රීඩක පරීක්ෂා කෝටාවෙනි. එය X-RateLimit හෙඩර් එවන්නේ නැති අතර, කෝටාව වාර්තා කරන්නේ 429 ප්‍රතිචාරයේ බොඩි එක තුළයි.

රවුට්	ඉල්ලීම්	කාල පරාසය	ගණන් කරන්නේ
GET /catalog/* (පහම)	5000	තත්පර 60	ගිණුමකට
POST /orders/create	5000	තත්පර 60	ගිණුමකට
GET /orders/:orderId	3	තත්පර 60	ගිණුමකට + ඇණවුම් ID එකකට
POST /orders/batch	2	තත්පර 60	ගිණුමකට
GET /orders	2	තත්පර 60	ගිණුමකට
GET /account	60	තත්පර 60	ගිණුමකට
POST /player/validate	ක්‍රීඩකයන් පරීක්ෂා කිරීමේ දෛනික සීමාව	පැය 24	එක් එක් ගිණුමට වෙනම (මෙම සීමාව සඳහා X-RateLimit ශීර්ෂ ලැබෙන්නේ නැත)

වෙබ්හුක්

ඇණවුම්වල ප්‍රතිඵල අපි ඔබ ලියාපදිංචි කරන HTTPS එන්ඩ්පොයින්ට් එකකට යවමු. සෑම පණිවිඩයක්ම ඉල්ලීමේ raw body එක මත HMAC-SHA256 යොදා අත්සන් කර ඇත. සිදුවීම් ලැයිස්තුව, හෙඩර ලැයිස්තුව, payload ආකෘතිය සහ අත්සන තහවුරු කරන කේත නිදසුනක් API දළ විශ්ලේෂණ පිටුවේ විස්තර කර ඇත.

වෙබ්හුක් payload සහ අත්සන පිළිබඳ යොමු විස්තර කියවන්න

Platform එකට අලුත් නම් මුලින්ම රීසෙලර්ලා සඳහා ගේම් ටොප් අප් API හැඳින්වීම, නැතහොත් SHOP2TOPUP රීසෙලර් වැඩසටහනේ හැඳින්වීම කියවා පාර්ට්නර් ගිණුම ක්‍රියා කරන ආකාරය දැනගන්න.