Tài liệu tích hợp API
Kết nối website hoặc hệ thống của bạn với Locket Gold để xem gói dịch vụ, tạo đơn nâng cấp và theo dõi kết quả tự động.
Đăng nhập đối tácBắt đầu tích hợp1. Xác thực API
Mỗi đối tác được Admin cấp một API Key riêng. Gửi API Key trong header X-API-Key hoặc Authorization: Bearer cho mọi request thuộc API V1.
X-API-Key: lgapi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Accept: application/jsonBase URL: https://dichvufast.id.vn/api
2. Quy tắc hoạt động và tính phí
- Admin tạo tài khoản đối tác; không có chức năng tự đăng ký.
- Đối tác nạp số dư bằng QR chuyển khoản, nội dung chuyển khoản được tạo riêng cho từng giao dịch.
- Phí từng gói do cấu hình website quyết định; API trả giá hiện hành tại endpoint danh sách gói.
- Số dư bị trừ khi tạo đơn. Nếu dịch vụ kích hoạt thất bại, hệ thống tự động hoàn lại số tiền đã trừ.
- Mỗi request tạo đơn bắt buộc có
referenceduy nhất để chống tạo trùng khi retry. - Đơn API chỉ được đối tác sở hữu xem/tra cứu bằng API Key của chính đối tác.
Đơn vị tiền tệ: VND. Trạng thái đơn thường gặp: processing, completed, activation_failed.
3. Thông tin tài khoản
GET/v1/meTrả về tên đối tác và số dư hiện tại.
{
"success": true,
"partner": {
"username": "partner01",
"balance": 150000
}
}4. Danh sách gói
GET/v1/plansTrả về mã gói, tên gói, thời hạn và giá API đang áp dụng. Không nên tự ghi cứng giá trong hệ thống đối tác; hãy đọc giá từ endpoint này.
{
"success": true,
"plans": [
{"id":"trial","name":"Locket Gold Trial","duration":"3 ngày","price":0},
{"id":"pro","name":"Locket Gold Pro","duration":"180 ngày","price":19000},
{"id":"premium","name":"Locket Gold Premium","duration":"365 ngày","price":27000},
{"id":"forever","name":"Locket Gold Forever","duration":"Trọn đời","price":69000}
]
}Giá trong ví dụ chỉ minh họa. Giá thực tế là dữ liệu trả về từ API tại thời điểm gọi.
5. Tạo đơn hàng
POST/v1/ordersRequest body
{
"username": "locket_username",
"plan": "premium",
"reference": "ORDER-2026-000123",
"activationDate": "2026-11-22"
}| Trường | Bắt buộc | Mô tả |
|---|---|---|
username | Có | Username hoặc link hồ sơ Locket hợp lệ. |
plan | Có | trial, pro, premium, forever. |
reference | Có | Mã đơn riêng từ hệ thống đối tác, 1–80 ký tự; dùng để chống tạo trùng. |
activationDate | Không | Ngày kích hoạt theo YYYY-MM-DD. |
Response thành công
{
"success": true,
"duplicate": false,
"order": {
"order_code": "LOCKET123456",
"username": "locket_username",
"plan": "premium",
"status": "completed",
"amount": 27000,
"install_url": "https://..."
},
"refunded": false
}Nếu cùng đối tác gửi lại cùng reference, API trả về đơn đã tạo trước đó và không trừ tiền lần nữa.
success: false và refunded: true, quá trình kích hoạt thất bại và hệ thống đã hoàn tiền vào ví API.6. Tra cứu đơn hàng
GET/v1/orders/{order_code}Ví dụ: GET /api/v1/orders/LOCKET123456. Chỉ trả về đơn thuộc tài khoản API đang xác thực. Đơn không thuộc đối tác sẽ trả về 404.
7. Ví dụ tích hợp PHP (cURL)
Đặt đoạn mã này ở backend website đối tác, không đặt trong JavaScript trình duyệt.
<?php
$apiKey = 'lgapi_THAY_BANG_API_KEY_CUA_BAN';
$baseUrl = 'https://dichvufast.id.vn/api';
$payload = [
'username' => 'locket_username',
'plan' => 'premium',
'reference' => 'ORDER-' . bin2hex(random_bytes(8))
];
$ch = curl_init($baseUrl . '/v1/orders');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . $apiKey,
'Content-Type: application/json',
'Accept: application/json'
],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_TIMEOUT => 60
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
$data = json_decode($response, true);
if ($httpCode < 200 || $httpCode >= 300 || !is_array($data)) {
throw new RuntimeException('API request failed');
}
print_r($data);Ví dụ cURL
curl -X GET 'https://dichvufast.id.vn/api/v1/plans' \\
-H 'X-API-Key: lgapi_YOUR_API_KEY' \\
-H 'Accept: application/json'8. Mã lỗi thường gặp
| HTTP | Ý nghĩa | Cách xử lý |
|---|---|---|
| 400 | Thiếu hoặc sai dữ liệu gửi lên. | Kiểm tra username, plan, reference, ngày. |
| 401 | API Key không hợp lệ hoặc tài khoản bị khóa. | Kiểm tra API Key và liên hệ Admin. |
| 402 | Số dư API không đủ. | Nạp thêm số dư. |
| 404 | Không tìm thấy đơn hoặc endpoint. | Kiểm tra mã đơn và quyền sở hữu. |
| 422 | Không xác minh được tài khoản Locket. | Kiểm tra lại username/link. |
| 503 | Dịch vụ xác minh hoặc cấu hình máy chủ tạm thời không sẵn sàng. | Thử lại sau; không tạo reference mới khi retry. |
Khi request timeout, hãy gửi lại đúng request với cùng reference để tránh tạo đơn trùng.