SakuraAPI
✨ SakuraAPI Official Documentation v1.2

មគ្គុទ្ទេសក៍ភ្ជាប់ REST API សម្រាប់ Resellers

ឯកសារបច្ចេកទេស និងកូដគំរូសម្រាប់ Developer យកទៅភ្ជាប់ប្រព័ន្ធស្វ័យប្រវត្តិជាមួយ Website, Telegram Mini App, Webhook ឬ Bot យ៉ាងងាយស្រួល និងរហ័ស។

ទទួលយក API Key
Base URL
https://sakuraapi.lol/api/v1
ល្បឿនបញ្ចូល
< 3.0 វិនាទី (Instant Auto)
សុវត្ថិភាពទិន្នន័យ
SHA-256 Bearer Token
Rate Limit
100 Requests / នាទី
1

ដំណើរការទូទៅ (How SakuraAPI Works)

របៀបដំណើរការប្រព័ន្ធ Top-up ហ្គេមស្វ័យប្រវត្តិតាមរយៈ API

SakuraAPI ផ្ដល់ជូននូវ Gateway សម្រាប់តំណាងចែកចាយ (Resellers) ធ្វើការកុម្ម៉ង់បញ្ចូលពេជ្រ និង UC ទៅក្នុងគណនីអតិថិជនដោយស្វ័យប្រវត្តិតាមរយៈ HTTP REST requests 100% គ្មានការរង់ចាំដោយដៃ។

ជំហានទាំង ៣ ដើម្បីចាប់ផ្ដើមសមាហរណកម្ម (Integration Steps)៖
  1. បង្កើត API Key៖ ចូលទៅកាន់ទំព័រ Settings (ការកំណត់ & API) ដើម្បីបង្កើត Production Live API Key ផ្ទាល់ខ្លួន។
  2. ផ្ទៀងផ្ទាត់ Player ID៖ ហៅ Endpoint POST /api/v1/games/check-id ដើម្បីបញ្ជាក់ឈ្មោះ In-game Name របស់អតិថិជន។
  3. បង្កើត Order Top-up៖ ហៅ Endpoint POST /api/v1/orders ដើម្បីកាត់ទឹកប្រាក់ក្នុងកាបូប និងបញ្ជូនពេជ្រចូលភ្លាមៗ។
2

ការផ្ទៀងផ្ទាត់សិទ្ធិ (Authentication)

ប្រើប្រាស់ Bearer Token ក្នុង HTTP Header លើគ្រប់ API Requests

GET/api/v1/reseller/me

រាល់ API Request ទាំងអស់ដែលផ្ញើមកកាន់ SakuraAPI ត្រូវតែភ្ជាប់មកជាមួយ API Key របស់អ្នកនៅក្នុង HTTP Header Authorization៖

Authorization: Bearer sk_live_your_api_key_hereStandard Header
CODE EXAMPLES
curl -X GET "https://sakuraapi.lol/api/v1/reseller/me" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
EXAMPLE JSON RESPONSE
{
  "status": "SUCCESS",
  "user": {
    "id": 1,
    "telegram_id": "8821434690",
    "username": "DemoUser",
    "balance": 98.9,
    "status": "active",
    "role": "reseller",
    "total_orders": 9,
    "total_spent": 0.65,
    "created_at": "2026-06-18 13:42:58",
    "updated_at": "2026-09-30 10:30:15"
  }
}
3

ឆែក ID ហ្គេម (Check Game ID)

Auto Username Validator មុនពេលកុម្ម៉ង់ទិញ

POST/api/v1/games/check-id

ប្រើប្រាស់ Endpoint នេះដើម្បីឆែកស្វែងរកឈ្មោះ In-game Name របស់តួអង្គហ្គេម មុនពេលអតិថិជនចុចទិញ ដើម្បីកាត់បន្ថយបញ្ហាក្នុងការវាយខុស ID ឬ Server ID។

ប៉ារ៉ាម៉ែត្រក្នុង Request Body (JSON)៖
FieldTypeRequiredDescription
gamestringYesកូដសម្គាល់ហ្គេម (ឧ. mobile-legends, free-fire)
useridstringYesPlayer ID ឬ User ID របស់អ្នកលេង
serveridstringOptionalZone ID (តម្រូវការចាំបាច់សម្រាប់តែ Mobile Legends និង Genshin)
CODE EXAMPLES
curl -X POST "https://sakuraapi.lol/api/v1/games/check-id" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "game": "mobile-legends",
    "userid": "1473883595",
    "serverid": "14309"
  }'
EXAMPLE JSON RESPONSE
{
  "status": "SUCCESS",
  "data": {
    "valid": true,
    "username": "SakuraMaster99",
    "region": "Cambodia (Asia)",
    "game": "mobile-legends",
    "userid": "1473883595",
    "serverid": "14309",
    "message": "Player ID verified successfully"
  }
}
4

បញ្ជាទិញពេជ្រ (Create Order)

Instant Top-up Gateway ជាមួយប្រព័ន្ធ Auto-Refund 100%

POST/api/v1/orders

បង្កើត Order បញ្ចូលពេជ្រដោយស្វ័យប្រវត្តិ។ ប្រព័ន្ធនឹងកាត់ទឹកប្រាក់ក្នុងកាបូប Reseller Balance ភ្លាមៗ និងផ្ញើការបញ្ចូលទៅ Provider ក្នុងរយៈពេលក្រោម 3 វិនាទី។ ប្រសិនបើតួអង្គមិនត្រឹមត្រូវ ប្រព័ន្ធនឹង Auto-Refund បង្វិលលុយចូលគណនីវិញភ្លាមៗ 100%។

FieldTypeRequiredDescription
gamestringYesកូដហ្គេម (ឧ. mobile-legends)
productstringYesកូដកញ្ចប់ពេជ្រ (ឧ. mlbb-86)
player_idstringYesPlayer ID របស់អតិថិជន
serveridstringOptionalZone ID (សម្រាប់ MLBB / Genshin)
reseller_order_idstringYesលេខសម្គាល់ Order ផ្ទាល់ខ្លួនរបស់អ្នក (ការពារការបញ្ជាទិញស្ទួន Idempotency)
callback_urlstringOptionalWebhook URL ដោយឡែកសម្រាប់ទទួល Callback លទ្ធផលនៃ Order នេះ (HTTPS)
CODE EXAMPLES
curl -X POST "https://sakuraapi.lol/api/v1/orders" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "game": "mobile-legends",
    "product": "mlbb-86",
    "player_id": "1473883595",
    "serverid": "14309",
    "reseller_order_id": "ORD-20260930-001"
  }'
EXAMPLE JSON RESPONSE
{
  "status": "SUCCESS",
  "data": {
    "order_id": "SK-20260930-8849",
    "reseller_order_id": "ORD-20260930-001",
    "game": "mobile-legends",
    "product_code": "mlbb-86",
    "amount": 1.45,
    "currency": "USD",
    "player_id": "1473883595 (14309)",
    "status": "PROCESSING",
    "created_at": "2026-09-30T13:40:00.000Z"
  }
}
5

បញ្ជីហ្គេម & ស្តុក (Games Catalog)

Live Stock, Product Codes & Reseller Pricing

GET/api/v1/games

ទាញយកបញ្ជីហ្គេម និងកញ្ចប់ពេជ្រទាំងអស់ដែលកំពុងដំណើរការ រួមទាំងតម្លៃ Reseller Cost ដើម្បីដាក់បញ្ចូលលើ Website ឬ Telegram Bot របស់អ្នកដោយស្វ័យប្រវត្តិ។

CODE EXAMPLES
curl -X GET "https://sakuraapi.lol/api/v1/games" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Accept: application/json"
EXAMPLE JSON RESPONSE
{
  "status": "SUCCESS",
  "count": 2,
  "data": [
    {
      "id": "mobile-legends",
      "name": "Mobile Legends: Bang Bang",
      "status": "ONLINE",
      "server_required": true,
      "products_count": 15
    },
    {
      "id": "free-fire",
      "name": "Garena Free Fire",
      "status": "ONLINE",
      "server_required": false,
      "products_count": 19
    }
  ]
}
6

Webhook Callbacks (ដំណឹងស្វ័យប្រវត្តិ)

Real-time Outbound HTTP POST Callback (HMAC-SHA256)

POST[Your Webhook URL]

SakuraAPI ផ្ញើ HTTP POST Callback ដោយស្វ័យប្រវត្តិនូវរាល់ពេលដែល Order របស់អ្នកត្រូវបានបញ្ចប់ដោយ Provider (ស្ថានភាព SUCCESS ឬ FAILED)។ អ្នកអាចកំណត់ Webhook URL និង Signing Secret នៅក្នុងទំព័រ Settings (API & Webhook)។

HTTP Headers ដែល SakuraAPI ផ្ញើទៅកាន់ Webhook របស់អ្នក៖

Header NameValue FormatDescription
Content-Typeapplication/jsonទម្រង់ទិន្នន័យជា JSON
User-AgentSakuraAPI-Callback/1.0កូដសម្គាល់ SakuraAPI Dispatcher
X-Sakura-Signaturesha256=HMAC_SHA256(secret, rawBody)ហត្ថលេខាសុវត្ថិភាពសម្រាប់ផ្ទៀងផ្ទាត់ថា Request មកពី SakuraAPI ពិតប្រាកដ

គំរូ JSON Callback Payload (ពេល Order ជោគជ័យ)៖

{
  "event": "order.success",         // "order.success" ឬ "order.failed"
  "order_id": "SK-20261105-824277", // លេខ Order ក្នុង SakuraAPI
  "reseller_order_id": "ORDER-100234", // លេខសម្គាល់ដើមរបស់ Reseller
  "status": "SUCCESS",              // ស្ថានភាពចុងក្រោយ: "SUCCESS" ឬ "FAILED"
  "game": "Garena Free Fire",       // ឈ្មោះហ្គេម
  "game_code": "free-fire",         // កូដហ្គេម
  "product": "Weekly Diamond Pass", // ឈ្មោះកញ្ចប់
  "product_code": "weeklylite",     // កូដកញ្ចប់
  "player_id": "7529178137",        // Player ID / UID
  "server_id": null,                // Zone / Server ID (បើមាន)
  "amount": "0.30",                 // តម្លៃដែលបានកាត់ប្រាក់ ($ USD)
  "currency": "USD",
  "failure_reason": null,           // មូលហេតុប្រសិនបើបរាជ័យ (e.g. "Player ID not found")
  "timestamp": "2026-11-05T03:30:56.593Z"
}

របៀបផ្ទៀងផ្ទាត់ HMAC-SHA256 Signature (Node.js Express)៖

const crypto = require('crypto');

app.post('/api/webhooks/sakura', express.json(), (req, res) => {
  const signature = req.headers['x-sakura-signature'];
  const secret = process.env.SAKURA_WEBHOOK_SECRET;

  const expectedSig = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expectedSig) {
    return res.status(401).send('Invalid signature');
  }

  const { order_id, status, reseller_order_id } = req.body;
  if (status === 'SUCCESS') {
    // ផ្ដល់ទំនិញ ឬសម្គាល់ Order ថាបានជោគជ័យ
  }

  res.status(200).json({ ok: true });
});
7

កូដកំហុសទូទៅ (Error Codes & Responses)

រចនាសម្ព័ន្ធនៃកំហុសស្តង់ដារដែលប្រព័ន្ធអាចបញ្ជូនត្រឡប់មកវិញ

SakuraAPI ប្រើប្រាស់ទម្រង់ JSON ស្តង់ដាររួមមួយសម្រាប់រាល់ Error Responses ដើម្បីងាយស្រួលចាប់ក្នុង Try/Catch block របស់អ្នក៖

HTTP StatusError Codeមូលហេតុ & ដំណោះស្រាយ (Khmer Explanation)
401 UnauthorizedINVALID_API_KEYAPI Key មិនត្រឹមត្រូវ ផុតកំណត់ ឬត្រូវបានលុបចោល (Revoked)។
402 Payment RequiredINSUFFICIENT_BALANCEសមតុល្យក្នុងកាបូប Reseller មិនគ្រប់គ្រាន់សម្រាប់កុម្ម៉ង់កញ្ចប់នេះឡើយ។ សូមបញ្ចូលសមតុល្យបន្ថែម។
409 ConflictDUPLICATE_ORDERលេខសម្គាល់ reseller_order_id នេះត្រូវបានដំណើរការរួចរាល់ហើយ មិនអាចបញ្ជូនស្ទួនបានទេ។
429 Too Many RequestsRATE_LIMITEDចំនួន Requests លើសពីកូតាកំណត់ 100 requests / នាទី។ សូមពន្យារពេលបន្តិចមុនហៅម្ដងទៀត។