មគ្គុទ្ទេសក៍ភ្ជាប់ REST API សម្រាប់ Resellers
ឯកសារបច្ចេកទេស និងកូដគំរូសម្រាប់ Developer យកទៅភ្ជាប់ប្រព័ន្ធស្វ័យប្រវត្តិជាមួយ Website, Telegram Mini App, Webhook ឬ Bot យ៉ាងងាយស្រួល និងរហ័ស។
ដំណើរការទូទៅ (How SakuraAPI Works)
របៀបដំណើរការប្រព័ន្ធ Top-up ហ្គេមស្វ័យប្រវត្តិតាមរយៈ API
SakuraAPI ផ្ដល់ជូននូវ Gateway សម្រាប់តំណាងចែកចាយ (Resellers) ធ្វើការកុម្ម៉ង់បញ្ចូលពេជ្រ និង UC ទៅក្នុងគណនីអតិថិជនដោយស្វ័យប្រវត្តិតាមរយៈ HTTP REST requests 100% គ្មានការរង់ចាំដោយដៃ។
- បង្កើត API Key៖ ចូលទៅកាន់ទំព័រ Settings (ការកំណត់ & API) ដើម្បីបង្កើត Production Live API Key ផ្ទាល់ខ្លួន។
- ផ្ទៀងផ្ទាត់ Player ID៖ ហៅ Endpoint
POST /api/v1/games/check-idដើម្បីបញ្ជាក់ឈ្មោះ In-game Name របស់អតិថិជន។ - បង្កើត Order Top-up៖ ហៅ Endpoint
POST /api/v1/ordersដើម្បីកាត់ទឹកប្រាក់ក្នុងកាបូប និងបញ្ជូនពេជ្រចូលភ្លាមៗ។
ការផ្ទៀងផ្ទាត់សិទ្ធិ (Authentication)
ប្រើប្រាស់ Bearer Token ក្នុង HTTP Header លើគ្រប់ API Requests
រាល់ API Request ទាំងអស់ដែលផ្ញើមកកាន់ SakuraAPI ត្រូវតែភ្ជាប់មកជាមួយ API Key របស់អ្នកនៅក្នុង HTTP Header Authorization៖
curl -X GET "https://sakuraapi.lol/api/v1/reseller/me" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"{
"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"
}
}ឆែក ID ហ្គេម (Check Game ID)
Auto Username Validator មុនពេលកុម្ម៉ង់ទិញ
ប្រើប្រាស់ Endpoint នេះដើម្បីឆែកស្វែងរកឈ្មោះ In-game Name របស់តួអង្គហ្គេម មុនពេលអតិថិជនចុចទិញ ដើម្បីកាត់បន្ថយបញ្ហាក្នុងការវាយខុស ID ឬ Server ID។
| Field | Type | Required | Description |
|---|---|---|---|
| game | string | Yes | កូដសម្គាល់ហ្គេម (ឧ. mobile-legends, free-fire) |
| userid | string | Yes | Player ID ឬ User ID របស់អ្នកលេង |
| serverid | string | Optional | Zone ID (តម្រូវការចាំបាច់សម្រាប់តែ Mobile Legends និង Genshin) |
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"
}'{
"status": "SUCCESS",
"data": {
"valid": true,
"username": "SakuraMaster99",
"region": "Cambodia (Asia)",
"game": "mobile-legends",
"userid": "1473883595",
"serverid": "14309",
"message": "Player ID verified successfully"
}
}បញ្ជាទិញពេជ្រ (Create Order)
Instant Top-up Gateway ជាមួយប្រព័ន្ធ Auto-Refund 100%
បង្កើត Order បញ្ចូលពេជ្រដោយស្វ័យប្រវត្តិ។ ប្រព័ន្ធនឹងកាត់ទឹកប្រាក់ក្នុងកាបូប Reseller Balance ភ្លាមៗ និងផ្ញើការបញ្ចូលទៅ Provider ក្នុងរយៈពេលក្រោម 3 វិនាទី។ ប្រសិនបើតួអង្គមិនត្រឹមត្រូវ ប្រព័ន្ធនឹង Auto-Refund បង្វិលលុយចូលគណនីវិញភ្លាមៗ 100%។
| Field | Type | Required | Description |
|---|---|---|---|
| game | string | Yes | កូដហ្គេម (ឧ. mobile-legends) |
| product | string | Yes | កូដកញ្ចប់ពេជ្រ (ឧ. mlbb-86) |
| player_id | string | Yes | Player ID របស់អតិថិជន |
| serverid | string | Optional | Zone ID (សម្រាប់ MLBB / Genshin) |
| reseller_order_id | string | Yes | លេខសម្គាល់ Order ផ្ទាល់ខ្លួនរបស់អ្នក (ការពារការបញ្ជាទិញស្ទួន Idempotency) |
| callback_url | string | Optional | Webhook URL ដោយឡែកសម្រាប់ទទួល Callback លទ្ធផលនៃ Order នេះ (HTTPS) |
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"
}'{
"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"
}
}បញ្ជីហ្គេម & ស្តុក (Games Catalog)
Live Stock, Product Codes & Reseller Pricing
ទាញយកបញ្ជីហ្គេម និងកញ្ចប់ពេជ្រទាំងអស់ដែលកំពុងដំណើរការ រួមទាំងតម្លៃ Reseller Cost ដើម្បីដាក់បញ្ចូលលើ Website ឬ Telegram Bot របស់អ្នកដោយស្វ័យប្រវត្តិ។
curl -X GET "https://sakuraapi.lol/api/v1/games" \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Accept: application/json"{
"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
}
]
}Webhook Callbacks (ដំណឹងស្វ័យប្រវត្តិ)
Real-time Outbound HTTP POST Callback (HMAC-SHA256)
SakuraAPI ផ្ញើ HTTP POST Callback ដោយស្វ័យប្រវត្តិនូវរាល់ពេលដែល Order របស់អ្នកត្រូវបានបញ្ចប់ដោយ Provider (ស្ថានភាព SUCCESS ឬ FAILED)។ អ្នកអាចកំណត់ Webhook URL និង Signing Secret នៅក្នុងទំព័រ Settings (API & Webhook)។
HTTP Headers ដែល SakuraAPI ផ្ញើទៅកាន់ Webhook របស់អ្នក៖
| Header Name | Value Format | Description |
|---|---|---|
| Content-Type | application/json | ទម្រង់ទិន្នន័យជា JSON |
| User-Agent | SakuraAPI-Callback/1.0 | កូដសម្គាល់ SakuraAPI Dispatcher |
| X-Sakura-Signature | sha256=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 });
});កូដកំហុសទូទៅ (Error Codes & Responses)
រចនាសម្ព័ន្ធនៃកំហុសស្តង់ដារដែលប្រព័ន្ធអាចបញ្ជូនត្រឡប់មកវិញ
SakuraAPI ប្រើប្រាស់ទម្រង់ JSON ស្តង់ដាររួមមួយសម្រាប់រាល់ Error Responses ដើម្បីងាយស្រួលចាប់ក្នុង Try/Catch block របស់អ្នក៖
| HTTP Status | Error Code | មូលហេតុ & ដំណោះស្រាយ (Khmer Explanation) |
|---|---|---|
| 401 Unauthorized | INVALID_API_KEY | API Key មិនត្រឹមត្រូវ ផុតកំណត់ ឬត្រូវបានលុបចោល (Revoked)។ |
| 402 Payment Required | INSUFFICIENT_BALANCE | សមតុល្យក្នុងកាបូប Reseller មិនគ្រប់គ្រាន់សម្រាប់កុម្ម៉ង់កញ្ចប់នេះឡើយ។ សូមបញ្ចូលសមតុល្យបន្ថែម។ |
| 409 Conflict | DUPLICATE_ORDER | លេខសម្គាល់ reseller_order_id នេះត្រូវបានដំណើរការរួចរាល់ហើយ មិនអាចបញ្ជូនស្ទួនបានទេ។ |
| 429 Too Many Requests | RATE_LIMITED | ចំនួន Requests លើសពីកូតាកំណត់ 100 requests / នាទី។ សូមពន្យារពេលបន្តិចមុនហៅម្ដងទៀត។ |
