API V1 · SERVER TO SERVER

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ợp

1. 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/json
Giữ API Key ở máy chủ của bạn. Không nhúng API Key vào HTML, JavaScript frontend, ứng dụng công khai hoặc chia sẻ trong mã nguồn.

Base 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ó reference duy 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/me

Trả 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/plans

Trả 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/orders

Request body

{
  "username": "locket_username",
  "plan": "premium",
  "reference": "ORDER-2026-000123",
  "activationDate": "2026-11-22"
}
TrườngBắt buộcMô tả
usernameCóUsername hoặc link hồ sơ Locket hợp lệ.
planCótrial, pro, premium, forever.
referenceCóMã đơn riêng từ hệ thống đối tác, 1–80 ký tự; dùng để chống tạo trùng.
activationDateKhôngNgà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.

Nếu response báo 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ĩaCách xử lý
400Thiếu hoặc sai dữ liệu gửi lên.Kiểm tra username, plan, reference, ngày.
401API 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.
402Số dư API không đủ.Nạp thêm số dư.
404Không tìm thấy đơn hoặc endpoint.Kiểm tra mã đơn và quyền sở hữu.
422Không xác minh được tài khoản Locket.Kiểm tra lại username/link.
503Dị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.