Tài Liệu & Quản Lý API Tool Việt Nam

Xác Thực (Authentication)

Mọi yêu cầu đến API cần được xác thực. Có hai cách chính:

1. Header Authorization (Khuyến nghị): Thêm header Authorization: Bearer YOUR_API_KEY vào mỗi request. Đây là phương thức an toàn và chuẩn nhất.
2. Tham số Query/POST: Bạn có thể gửi key qua tham số key=YOUR_API_KEY trong URL (cho GET) hoặc trong body (cho POST). Phương thức này ít an toàn hơn header.

Copy# Ví dụ Header
Authorization: Bearer TOOLVN-V1-XXXXXXXXXXXXXXXX

# Ví dụ Tham số GET
https://tool.vn/api/user/info?key=TOOLVN-V1-XXXXXXXXXXXXXXXX

Base URL & Endpoint

Địa chỉ gốc cho tất cả API là https://tool.vn/api. Mỗi chức năng sẽ có một đường dẫn (endpoint) riêng, ví dụ /user/info, /facebook/get_comment.

Ví dụ URL đầy đủ để lấy thông tin người dùng: https://tool.vn/api/user/info.

Lấy Thông Tin Tài Khoản (User Info)

Endpoint này cho phép bạn kiểm tra thông tin liên kết với API Key, bao gồm email, số dư credit và hạn sử dụng credit gần nhất. Rất hữu ích để kiểm tra số dư trước khi thực hiện các lệnh tốn credit khác.

Endpoint: /user/info (Chấp nhận GET hoặc POST)

Tham số bắt buộc:

• key: API Key của bạn.

Ví dụ Request (GET):

Copy//tool.vn/api/user/info?key=TOOLVN-V1-XXXXXXXXXXXXXXXX

Phản hồi thành công (JSON):

Copy{
  "status": "success",
  "message": "Lấy thông tin thành công.",
  "data": {
    "user_id": "172...",
    "email": "[email protected]",
    "status": "active", // Trạng thái của API Key
    "created_at": "2024-07-28 10:00:00", // Thời gian tạo key
    "last_used_at": "2024-07-28 11:25:10", // Lần dùng cuối (gần nhất) của key (có thể null)
    "available_credits": 12345,
    "next_credit_expiry_date": "2025-08-15 10:30:00" // Thời hạn hết hạn gần nhất của credits (ví dụ: nếu bạn có 200k credits hết hạn vào 31/12/2025 tuy nhiên trong 200k credit đó có 10k credit sẽ hết hạn vào 01/12/2025 thì thời gian hiển thị của next_credit_expiry_date là 01/12/2025)
  }
}

Chi Phí & Credit

Hầu hết các yêu cầu API (trừ /user/info) đều tiêu tốn Credit AI. Chi phí cụ thể cho từng hành động được liệt kê tại trang chức năng, hoặc tham khảo một phần bảng giá tại trang Credit AI. Luôn đảm bảo bạn có đủ credit và số dư tối thiểu (N/A credits) trước khi gọi API.

Xử Lý Lỗi Phổ Biến

• 401 Unauthorized: Thiếu API Key hoặc định dạng `Authorization` sai.
• 403 Forbidden: API Key không hợp lệ, không tồn tại, hoặc đã bị vô hiệu hóa (inactive/revoked).
• 402 Payment Required: Không đủ Credit để thực hiện yêu cầu hoặc số dư dưới mức tối thiểu.
• 400 Bad Request: Thiếu tham số bắt buộc hoặc giá trị tham số không hợp lệ.
• 429 Too Many Requests: Vượt quá giới hạn tần suất gọi API.
• 500 Internal Server Error: Lỗi từ phía server Tool Việt Nam.

Phản hồi lỗi sẽ đi kèm thông báo chi tiết trong trường `message` của JSON.

Ví Dụ Lấy Thông Tin User (PHP cURL)

Đây là ví dụ đầy đủ hơn về cách gọi endpoint /user/info bằng cả GET và POST (với header).

Copy<?php
$apiKey = 'TOOLVN-V1-XXXXXXXXXXXXXXXX'; // <-- Thay bằng API Key của bạn
$apiUrl = 'https://tool.vn/api/user/info'; // Endpoint mới

// Cách 1: Dùng GET (đơn giản hơn)
$urlWithParams = $apiUrl . '?key=' . urlencode($apiKey);

$ch_get = curl_init();
curl_setopt($ch_get, CURLOPT_URL, $urlWithParams);
curl_setopt($ch_get, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch_get, CURLOPT_TIMEOUT, 10);
$response_get = curl_exec($ch_get);
$httpCode_get = curl_getinfo($ch_get, CURLINFO_HTTP_CODE);
curl_close($ch_get);

echo "--- Kết quả GET ---<br>";
if ($httpCode_get == 200) {
    $result_get = json_decode($response_get, true);
    print_r($result_get);
} else {
    echo "Lỗi HTTP GET: " . $httpCode_get . "<br>";
    echo $response_get;
}

echo "<hr>";

// Cách 2: Dùng POST với Authorization Header (khuyến nghị cho mục đích bảo mật)
$ch_post = curl_init();
curl_setopt($ch_post, CURLOPT_URL, $apiUrl); // URL không cần key
curl_setopt($ch_post, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch_post, CURLOPT_POST, true); // Sử dụng POST (dù endpoint chấp nhận cả GET)
curl_setopt($ch_post, CURLOPT_POSTFIELDS, http_build_query(['action' => 'get_info'])); 
curl_setopt($ch_post, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/x-www-form-urlencoded'
]);
curl_setopt($ch_post, CURLOPT_TIMEOUT, 10);
$response_post = curl_exec($ch_post);
$httpCode_post = curl_getinfo($ch_post, CURLINFO_HTTP_CODE);
curl_close($ch_post);

echo "--- Kết quả POST (với Header Auth) ---<br>";
if ($httpCode_post == 200) {
     $result_post = json_decode($response_post, true);
     print_r($result_post);
} else {
     echo "Lỗi HTTP POST: " . $httpCode_post . "<br>";
     echo $response_post;
}

?>

Cần Hỗ Trợ?

Chúng tôi luôn sẵn lòng hỗ trợ bạn. Hãy truy cập trang liên hệ hoặc gửi email đến [email protected].