Thử nghiệm trực tiếp các endpoint trên hệ thống Subgiare3s. Kết nối thời gian thực qua máy chủ api.subgiare3s.com.
Giới thiệu v1
Subgiare3s API v1 là RESTful API hiện đại — định dạng JSON-first, xác thực qua Bearer Token, phản hồi chuẩn HTTP status codes. Phù hợp tuyệt đối khi bạn xây dựng hệ thống mới, ứng dụng di động iOS/Android, hoặc tích hợp trực tiếp vào website thương mại điện tử.
Xác thực (Authentication)
Mọi yêu cầu gửi đến API v1 phải đính kèm API Key trong Header HTTP Authorization dưới dạng Bearer Token. Bạn có thể lấy hoặc tạo mới API Key tại Trang Quản Lý Tài Khoản.
Authorization: Bearer sub_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 Content-Type: application/json Accept: application/json Accept-Currency: VND // Tùy chọn: VND | USD (mặc định VND)
Tiền tệ & Quy đổi (Currency Support)
Hệ thống hỗ trợ cả đối tác trong nước và quốc tế. Mặc định mọi trường số tiền (balance, rate, charge, refund_amount) trả về số nguyên VND. Nếu bạn gửi kèm header Accept-Currency: USD hoặc tham số ?currency=USD, hệ thống sẽ tự động quy đổi sang USD theo tỷ giá ngoại tệ thực (25.400 đ = 1 USD).
Mã lỗi & HTTP Status Codes
API v1 sử dụng các mã HTTP chuẩn theo chuẩn RFC 7231. Phản hồi lỗi luôn có định dạng JSON { "success": false, "code": "...", "message": "..." }.
| Mã HTTP | Mã định danh (Code) | Ý nghĩa & Cách xử lý |
|---|---|---|
| 200 | OK / ORDER_CREATED | Yêu cầu thành công, dữ liệu được trả về trong body. |
| 400 | INVALID_PARAM | Tham số gửi lên bị thiếu hoặc sai định dạng (ví dụ: số lượng nhỏ hơn min). |
| 401 | UNAUTHORIZED | API key bị thiếu, không chính xác hoặc tài khoản đã bị tạm khóa. |
| 402 | INSUFFICIENT_BALANCE | Số dư ví không đủ thanh toán. Vui lòng nạp thêm tiền qua Ngân hàng / SePay. |
| 404 | NOT_FOUND | Gói dịch vụ hoặc mã đơn hàng không tồn tại trong hệ thống. |
| 429 | RATE_LIMITED | Đã vượt quá giới hạn 120 request / phút. Xem header Retry-After. |
| 500 | INTERNAL_ERROR | Lỗi hệ thống máy chủ, đơn hàng được bảo vệ không bị trừ tiền oan. |
Giới hạn tần suất (Rate Limit)
Hạn ngạch áp dụng là 120 lượt gọi / phút và tối đa 20.000 lượt gọi / ngày cho mỗi API Key. Mọi phản hồi đều trả về các HTTP Header thông báo quota:
X-RateLimit-Limit: 120 // Số request tối đa trong cửa sổ 1 phút X-RateLimit-Remaining: 119 // Số request khả dụng còn lại X-RateLimit-Reset: 1747387260 // Thời điểm tính bằng timestamp reset lại hạn mức
1. Danh sách Platforms GET
Trả về toàn bộ 24 nền tảng mạng xã hội đang hoạt động (Facebook, TikTok, Instagram, YouTube, Telegram, Twitter, Spotify...) kèm số lượng dịch vụ khả dụng.
curl -X GET "https://api.subgiare3s.com/api/v1/platforms" \ -H "Accept: application/json"
<?php
$response = file_get_contents('https://api.subgiare3s.com/api/v1/platforms');
$data = json_decode($response, true);
print_r($data['platforms']);
import requests
res = requests.get('https://api.subgiare3s.com/api/v1/platforms')
print(res.json())
const res = await fetch('https://api.subgiare3s.com/api/v1/platforms');
const data = await res.json();
console.log(data.platforms);
{
"success": true,
"count": 24,
"platforms": [
{ "code": "facebook", "name": "Facebook", "services_count": 15, "icon": "facebook", "color": "#1877F2" },
{ "code": "tiktok", "name": "TikTok", "services_count": 10, "icon": "tiktok", "color": "#000000" },
{ "code": "youtube", "name": "YouTube", "services_count": 10, "icon": "youtube", "color": "#FF0000" }
]
}
2. Danh sách Dịch vụ (Services) GET
Lấy danh sách hơn 150 gói dịch vụ mạng xã hội kèm thông tin giá (rate/1000), số lượng tối thiểu, tối đa, tốc độ và bảo hành.
| Tham số Query | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
| platform Tùy chọn | string | all | Lọc theo nền tảng: facebook, tiktok, youtube, instagram, v.v. |
| search Tùy chọn | string | - | Từ khóa tìm kiếm theo tên hoặc mô tả gói dịch vụ. |
| limit Tùy chọn | integer | 200 | Số lượng gói tối đa trả về (tối đa 500). |
curl -X GET "https://api.subgiare3s.com/api/v1/services?platform=youtube&limit=3" \ -H "Accept: application/json"
<?php
$url = 'https://api.subgiare3s.com/api/v1/services?platform=youtube';
$services = json_decode(file_get_contents($url), true);
foreach ($services['services'] as $svc) {
echo "{$svc['name']} - Giá 1000 lượt: {$svc['rate_per_1000']} đ\n";
}
import requests
res = requests.get('https://api.subgiare3s.com/api/v1/services?platform=youtube')
data = res.json()
for s in data['services']:
print(s['id'], s['name'], s['rate_per_1000'])
const res = await fetch('https://api.subgiare3s.com/api/v1/services?platform=youtube');
const data = await res.json();
console.log(data.services);
{
"success": true,
"count": 1,
"currency": "VND",
"services": [
{
"id": "youtube-1",
"platform": "youtube",
"name": "Tăng Lượt Thích Video YouTube (Likes)",
"rate_per_1000": 18000,
"rate_per_unit": 18,
"min": 50,
"max": 100000,
"speed": "1 - 15 phút",
"warranty": "Bảo hành 30 ngày",
"description": "Tăng like video YouTube thật, giữ tỉ lệ like/dislike hoàn hảo.",
"active": true,
"currency": "VND"
}
]
}
3. Chi tiết Gói Dịch vụ GET
Tra cứu chi tiết một gói dịch vụ theo ID định danh: GET /api/v1/services/{id}.
curl -X GET "https://api.subgiare3s.com/api/v1/services/youtube-1"
4. Tạo Đơn Hàng Mới (Create Order) POST
Khởi tạo đơn hàng dịch vụ mạng xã hội vào hệ thống. Số tiền thanh toán sẽ được trừ trực tiếp vào số dư ví của tài khoản thông qua Database Transaction an toàn tuyệt đối chống race condition.
| Tham số Body (JSON) | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| service_id | string | Bắt buộc | Mã định danh gói dịch vụ (ví dụ: youtube-1, facebook-4). |
| link | string | Bắt buộc | Đường link bài viết, video, fanpage hoặc trang cá nhân mục tiêu. |
| quantity | integer | Bắt buộc | Số lượng muốn tăng (phải nằm trong khoảng min và max của gói). |
| comments | array | string | Tùy chọn | Danh sách bình luận mẫu (chỉ áp dụng đối với các gói tăng comment). |
curl -X POST "https://api.subgiare3s.com/api/v1/orders" \
-H "Authorization: Bearer sub_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"service_id": "youtube-1",
"link": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"quantity": 100
}'
<?php
$apiKey = 'sub_live_your_api_key_here';
$payload = json_encode([
'service_id' => 'youtube-1',
'link' => 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
'quantity' => 100
]);
$ch = curl_init('https://api.subgiare3s.com/api/v1/orders');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));
import requests
url = "https://api.subgiare3s.com/api/v1/orders"
headers = {
"Authorization": "Bearer sub_live_your_api_key_here",
"Content-Type": "application/json"
}
payload = {
"service_id": "youtube-1",
"link": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"quantity": 100
}
res = requests.post(url, json=payload, headers=headers)
print(res.status_code, res.json())
const res = await fetch('https://api.subgiare3s.com/api/v1/orders', {
method: 'POST',
headers: {
'Authorization': 'Bearer sub_live_your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
service_id: 'youtube-1',
link: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
quantity: 100
})
});
const data = await res.json();
console.log(data);
{
"success": true,
"code": "ORDER_CREATED",
"order_id": "ORD-496546",
"service_id": "youtube-1",
"service_name": "Tăng Lượt Thích Video YouTube (Likes)",
"link": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"quantity": 100,
"charge": 1800,
"balance": 50367973,
"currency": "VND",
"status": "Pending",
"message": "Đơn hàng đã được tạo thành công và bắt đầu chạy!"
}
5. Danh sách Đơn hàng GET
Lấy danh sách các đơn hàng của tài khoản kèm phân trang: GET /api/v1/orders?page=1&limit=20.
curl -X GET "https://api.subgiare3s.com/api/v1/orders?limit=10" \ -H "Authorization: Bearer sub_live_your_api_key_here"
6. Chi tiết & Trạng thái Đơn hàng GET
Kiểm tra trạng thái thời gian thực và số lượng còn lại của đơn: GET /api/v1/orders/{id}.
{
"success": true,
"order": {
"id": "ORD-496546",
"service_id": "youtube-1",
"service_name": "Tăng Lượt Thích Video YouTube (Likes)",
"link": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"quantity": 100,
"charge": 1800,
"currency": "VND",
"start_count": 0,
"remains": 0,
"status": "Completed",
"progress": 100,
"created_at": "2026-09-21 00:30:47"
}
}
7. Hủy Đơn Hàng & Hoàn Tiền POST
Hủy đơn hàng đang chờ xử lý (status pending). Hệ thống sẽ tự động hoàn 100% số tiền đơn vào số dư tài khoản: POST /api/v1/orders/{id}/cancel.
curl -X POST "https://api.subgiare3s.com/api/v1/orders/ORD-496546/cancel" \ -H "Authorization: Bearer sub_live_your_api_key_here"
8. Yêu cầu Bảo Hành / Refill Bù Tụt POST
Gửi yêu cầu kiểm tra bù tụt đối với các đơn hàng có chính sách bảo hành 30 ngày: POST /api/v1/orders/{id}/refill.
curl -X POST "https://api.subgiare3s.com/api/v1/orders/ORD-496546/refill" \ -H "Authorization: Bearer sub_live_your_api_key_here"
9. Thông tin Tài khoản (Profile) GET
Lấy thông tin tài khoản hiện tại, mã người dùng, họ tên và số dư: GET /api/v1/user/me.
curl -X GET "https://api.subgiare3s.com/api/v1/user/me" \ -H "Authorization: Bearer sub_live_your_api_key_here"
10. Tra cứu Số Dư Ví GET
Lấy nhanh số dư khả dụng của tài khoản: GET /api/v1/balance.
curl -X GET "https://api.subgiare3s.com/api/v1/balance" \ -H "Authorization: Bearer sub_live_your_api_key_here" \ -H "Accept-Currency: USD"
11. Cấu hình Webhooks
Khi trạng thái đơn hàng thay đổi (ví dụ hoàn tất completed hoặc hủy canceled), hệ thống Subgiare3s sẽ tự động gửi một thông báo HTTP POST đến URL Webhook bạn đã cấu hình.
{
"event": "order.completed",
"order_id": "ORD-496546",
"service_id": "youtube-1",
"status": "completed",
"remains": 0,
"timestamp": 1747387260
}