ပြန်လည်ရောင်းချသူ API လမ်းညွှန်

SHOP2TOPUP ပြန်လည်ရောင်းချသူ API သည် JSON REST API တစ်ခုဖြစ်ပြီး ကိုယ်ပိုင်ဆိုင်၊ အွန်လိုင်းစတိုး သို့မဟုတ် bot မှတစ်ဆင့် ဂိမ်း Top Up၊ ဂိမ်းငွေဖြည့်ခြင်းနှင့် Voucher ကုဒ်များကို ရောင်းချနိုင်ပါသည်။ ဤလမ်းညွှန်တွင် အများသုံး API လမ်းကြောင်းတိုင်း၊ ၎င်းတို့၏ parameter များနှင့် တုံ့ပြန်မှုများကို ဖော်ပြထားပါသည်။

အခြေခံ URL နှင့် ဆက်သွယ်ပုံ

ဤလမ်းညွှန်ပါ လမ်းကြောင်းအားလုံးကို အောက်ပါ အခြေခံ URL နောက်တွင် ဆက်၍ အသုံးပြုရပါမည်။ တောင်းဆိုမှုနှင့် တုံ့ပြန်မှုအားလုံးကို HTTPS ပေါ်တွင် JSON ဖြင့် ပေးပို့ပါသည်။ float ဂဏန်းကြောင့် ဖြစ်တတ်သော ဒဿမ အနီးစပ်ယူမှု အမှား မဝင်စေရန် ငွေပမာဏများကို စာသား (string) အဖြစ် ပို့ပါသည်။ အချိန်တံဆိပ် (timestamp) အားလုံးသည် ISO 8601 ပုံစံဖြင့် UTC အချိန် ဖြစ်ပါသည်။

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

အထောက်အထား စစ်ဆေးခြင်း

တောင်းဆိုမှုတိုင်းတွင် ခေါင်းစီးတစ်ခု ပါရပါမည်။ Key တစ်စုံကို ပြန်လည်ရောင်းချသူ Panel ရှိ API Access စာမျက်နှာမှ ထုတ်ပေးပြီး ခွင့်ပြုထားသော IP စာရင်းဖြင့် ကန့်သတ်ထားနိုင်ပါသည်။ စာရင်းတွင်မပါသော လိပ်စာမှ ခေါ်ဆိုပါက လုပ်ငန်းဆိုင်ရာ လုပ်ဆောင်ချက်များသို့ မရောက်မီ IP_NOT_ALLOWED ဖြင့် ငြင်းပယ်ပါသည်။

တောင်းဆိုမှုတွင် ထည့်ရမည့် ခေါင်းစီး

Authorization: Bearer <keyId>.<secret>

ပထမဆုံး ခေါ်ဆိုမှု

ဘာမှ install လုပ်ရန် မလိုပါ။ နမူနာထဲရှိ key နေရာတွင် ကိုယ်ပိုင် key ကို ထည့်လိုက်ပါက လက်ရှိ catalog ဒေတာ အစစ်ကို ပြန်ရပါမည်။

တောင်းဆိုမှု နမူနာ - cURL

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

တုံ့ပြန်မှု စည်းမျဉ်းများ

တုံ့ပြန်မှုတိုင်းတွင် boolean success field ပါသဖြင့် စစ်ဆေးချက် တစ်ခုတည်းဖြင့် အောင်မြင်မှုကို မအောင်မြင်မှု အားလုံးမှ ခွဲခြားနိုင်ပါသည်။
မအောင်မြင်ပါက အမှား object တစ်ခု ပြန်ပေးပါသည်။ ၎င်းတွင် မပြောင်းလဲသော ကုဒ်၊ လူဖတ်ရန် စာသားနှင့် ပါနိုင်သော details တို့ ပါဝင်ပါသည်။ ကုဒ်ကို ကြည့်၍သာ ခွဲခြားဆောင်ရွက်ပါ။ စာသားကို အခြေခံ၍ မဆုံးဖြတ်ပါနှင့်။
ငွေပမာဏကို "0.950000" ကဲ့သို့ USD ဖြင့် decimal string အဖြစ် အမြဲ ပေးပါသည်။ နှိုင်းယှဉ်ခြင်း သို့မဟုတ် ပေါင်းခြင်း မပြုမီ binary float အဖြစ် parse မလုပ်ပါနှင့်။
စာရင်းအဖြစ် ပြန်ပေးသော API လမ်းကြောင်းများသည် စာမျက်နှာခွဲပြသရန် အချက်အလက်တစ်ခုကိုပါ ထည့်ပေးပါသည်။ ၎င်းတွင် 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"
    }
  }
}

လမ်းညွှန် အပိုင်းများ

ကုန်ပစ္စည်းစာရင်းကုန်ပစ္စည်းစာရင်းကို အဆင့်သုံးဆင့်ဖြင့် စီထားပါသည်။ ပင်မအမျိုးအစားအောက်တွင် အမျိုးအစားများ၊ အမျိုးအစားအောက်တွင် အမျိုးအစားခွဲများ ရှိပြီး အမျိုးအစားခွဲသည် အမှန်တကယ် ဝယ်ယူမည့် ပစ္စည်း ဖြစ်ပါသည်။ ဤလမ်းကြောင်းများဖြင့် ထိုအဆင့်ဆင့်ဖွဲ့စည်းပုံကို ကိုယ်ပိုင် database ထဲသို့ ကူးယူထားနိုင်ပြီး အော်ဒါမတင်မီ ပစ္စည်းတစ်ခု၏ ဈေးနှုန်းကို ချက်ချင်း စစ်ဆေးနိုင်ပါသည်။ကစားသူ စစ်ဆေးခြင်းPlayer စစ်ဆေးခြင်းဖြင့် ငွေမဖြတ်မီ ဂိမ်းအကောင့်ကို အရင်ရှာဖွေအတည်ပြုပါသည်။ ထိုထုတ်ကုန်အတွက် ID အမှန်တကယ် ရှိကြောင်း စစ်ပေးပြီး ဝယ်သူ ပြန်စစ်နိုင်ရန် ဂိမ်းထဲရှိ အမည်ကို ပြန်ပေးသည်။ Region ကိုပါ ပြသပေးသဖြင့် Region မကိုက်ညီသော အော်ဒါကို ငွေပေးချေပြီးမှ မအောင်မြင်ဖြစ်မည့်အစား အစောပိုင်းကပင် ပယ်ချနိုင်ပါသည်။အော်ဒါများအော်ဒါဖန်တီးရာတွင် ကိုယ်တိုင်ထုတ်ထားသော UUID ကို အသုံးပြုပါ။ ထို UUID သည် idempotency key ဖြစ်ပြီး တူညီသော UUID ဖြင့် ထပ်ပို့ပါက ငွေနှစ်ကြိမ်မဖြတ်ဘဲ မူလအော်ဒါကိုသာ ပြန်ပေးပါသည်။ ထို့နောက် အခြေအနေကို အော်ဒါတစ်ခုချင်း၊ တစ်ကြိမ်လျှင် အများဆုံး 50 ခုပါသော batch သို့မဟုတ် စာမျက်နှာခွဲထားသော စာရင်းဖြင့် ပြန်ဖတ်နိုင်သည်။အကောင့်နှင့် အတည်ပြုခြင်းRequest တိုင်းတွင် header တစ်ခု ပါဝင်ပါသည်။ API Key အလုပ်လုပ်ကြောင်း စစ်ရန်၊ အော်ဒါများအတွက် ငွေဖြတ်ယူမည့် Wallet လက်ကျန်ငွေကို ကြည့်ရန်နှင့် batch run မစတင်မီ အကောင့် ဖွင့်ထားကြောင်း အတည်ပြုရန် GET /account ကို ခေါ်ပါ။အမှားကုဒ်များမအောင်မြင်သည့်အခါတိုင်း HTTP status နှင့်အတူ ပရိုဂရမ်က ဖတ်ရှုနိုင်သော သတ်မှတ်ကုဒ်တစ်ခု ပြန်ပေးပါသည်။ ပရိုဂရမ်တွင် ဆက်လုပ်မည့်အဆင့်ကို ကုဒ်အပေါ် မူတည်၍ ဆုံးဖြတ်ပါ။ ရှင်းလင်းချက်စာသားကို အခြေခံ၍ မဆုံးဖြတ်ပါနှင့်။ ထိုစာသားများသည် လူဖတ်ရန် ရေးထားခြင်းဖြစ်၍ အသုံးအနှုန်း ပြောင်းနိုင်ပါသည်။ ကုဒ်များကတော့ API တွင် သတ်မှတ်သဘောတူထားသည့်အတိုင်း မပြောင်းလဲဘဲ ရှိနေပါမည်။

တောင်းဆိုနှုန်း ကန့်သတ်ချက်များ

ခေါ်ဆိုမှု ကန့်သတ်ချက်များကို အကောင့်တစ်ခုချင်းအလိုက် ရွေ့လျားနေသော အချိန်ကာလတစ်ခုအတွင်း တွက်ချက်ပါသည်။ ကုန်ပစ္စည်းစာရင်း၊ အော်ဒါနှင့် အကောင့်ဆိုင်ရာ ခေါ်ဆိုမှုများတွင် X-RateLimit-Limit၊ X-RateLimit-Remaining နှင့် X-RateLimit-Reset တို့ ပါဝင်ပြီး ကန့်သတ်ခံရသော ခေါ်ဆိုမှုကမူ Retry-After ခေါင်းစီး ပါဝင်သည့် 429 ဖြင့် ပြန်ဖြေပါသည်။ ကစားသူ စစ်ဆေးခြင်းကိုမူ နေ့စဉ် ကစားသူ စစ်ဆေးခွင့် အရေအတွက်ဖြင့်သာ တိုင်းတာပါသည်။ ၎င်းသည် X-RateLimit ခေါင်းစီးများ မပို့ဘဲ ထိုအရေအတွက်ကို 429 တုံ့ပြန်မှု၏ body ထဲတွင် ဖော်ပြပေးပါသည်။

လမ်းကြောင်း	တောင်းဆိုမှုများ	အချိန်ကာလ	ရေတွက်သည့် အခြေခံ
GET /catalog/* (5 ခုလုံး)	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 လိပ်စာသို့ ပို့ပေးပါသည်။ ပို့သည့် မူရင်းဒေတာ တစ်ခုလုံးကို HMAC-SHA256 ဖြင့် လက်မှတ်ထိုးထားပါသည်။ Event စာရင်း၊ ခေါင်းစီးစာရင်း၊ ပို့သည့်ဒေတာ (payload) ဖွဲ့စည်းပုံနှင့် လက်မှတ်စစ်ဆေးရန် နမူနာကုဒ်ကို API အကျဉ်းချုပ် စာမျက်နှာတွင် ဖော်ပြထားပါသည်။

Webhook မှ ပို့သည့် ဒေတာပုံစံနှင့် လက်မှတ်စစ်ဆေးပုံ အသေးစိတ်ကို ဖတ်ရန်

ပလက်ဖောင်းကို စတင်အသုံးပြုသူ ဖြစ်ပါက Reseller များအတွက် ဂိမ်း Top Up API အကျဉ်းချုပ်၊ သို့မဟုတ် SHOP2TOPUP Reseller အစီအစဉ် အကျဉ်းချုပ် ကို ဖတ်၍ ပါတနာအကောင့် မည်သို့ အလုပ်လုပ်သည်ကို လေ့လာပါ။