|
Trung tâm thông báo
0 mới

Vui lòng đăng nhập để xem thông báo

Vui lòng đăng nhập để xem nhật ký

Xem chi tiết lịch sử
user-image
Số Dư: 0đ
TÀI KHOẢN
Profile Đổi mật khẩu Giỏ hàng
Log Out

Tài Liệu Tích Hợp API Đối Tác (v1)

Quản lý API Key Bắt đầu ngay
v1.0.0 RESTful JSON API • Production Ready • Auto Deploy Worker

Kết nối và tự động hóa toàn bộ dịch vụ Viweb vào hệ thống của bạn

API v1 cung cấp giải pháp mở toàn diện cho đại lý và lập trình viên: Tự động khởi tạo Shop Game qua Subdomain hoặc Addon Domain riêng, đăng ký tên miền & tra cứu Whois trực tuyến, đồng bộ số dư thời gian thực.

Base URL
https://www.viweb.vn/api/v1
API Key của bạn
Chưa có key [Lấy ngay]
HTTP 200 OK 
{
  "success": true,
  "code": 200,
  "service": "VIWEB_PARTNER_API",
  "worker_status": "ONLINE",
  "version": "1.0.0"
}
Mục Lục Tài Liệu
Hỗ trợ tích hợp: Zalo: 0865807979
1. Khởi Động & Xác Thực (Authentication)

Tất cả các API yêu cầu API Key của đối tác để định danh người dùng và trừ tiền dịch vụ. API Key là một chuỗi mã hoá bí mật duy nhất gắn liền với tài khoản của bạn.

Cách lấy API Key: Truy cập vào trang Thông tin cá nhân (Profile) > Mục Khóa API Cá Nhân để sao chép. Nếu bị rò rỉ mã, hãy bấm Tạo Mới (Đổi Key) ngay lập tức.
Cách truyền API Key vào Request:
Khuyên dùng (Chuẩn nhất)
HTTP Header (X-API-KEY)
X-API-KEY: YOUR_API_KEY
Chuẩn OAuth2 / Bearer
Authorization Header
Authorization: Bearer YOUR_API_KEY
Query Param (Test nhanh)
URL Parameter
?api_key=YOUR_KEY
2. Định Dạng Chuẩn & Mã Lỗi
Cấu trúc phản hồi thành công (JSON)
application/json • HTTP 200/201 
{
  "success": true,
  "code": 200,
  "message": "Mô tả kết quả thao tác",
  "timestamp": 1794484260,
  "data": {
    "key": "value"
  }
}
Cấu trúc phản hồi thất bại (JSON)
application/json • HTTP 4xx/5xx 
{
  "success": false,
  "code": 422,
  "error_code": "INSUFFICIENT_BALANCE",
  "message": "Số dư tài khoản không đủ để thanh toán",
  "timestamp": 1794484260}
Bảng mã lỗi thông dụng:
HTTP Code Mã lỗi (error_code) Ý nghĩa & Hướng xử lý
200 / 201 - Yêu cầu thành công / Tài nguyên mới được khởi tạo hoàn tất.
401 API_KEY_REQUIRED / INVALID_API_KEY Chưa gửi API Key hoặc Key không đúng/đã bị huỷ đổi mới.
422 INSUFFICIENT_BALANCE Số dư ví Viweb không đủ để trừ tiền đơn hàng. Cần nạp thêm tiền.
422 VALIDATION_ERROR Thiếu tham số bắt buộc hoặc định dạng không hợp lệ (ví dụ tên miền sai).
404 ORDER_NOT_FOUND / ENDPOINT_NOT_FOUND Không tìm thấy mã đơn hàng cần tra cứu hoặc sai đường dẫn API.
500 SERVER_ERROR Lỗi kết nối CSDL hoặc máy chủ nội bộ. Hãy liên hệ admin hỗ trợ.
3. Tài Khoản & Số Dư (Account)
GET /profile Lấy thông tin tài khoản đối tác & số dư

Dùng để kiểm tra số dư hiện tại trước khi tạo đơn hàng mới hoặc hiển thị trên bảng điều khiển đại lý.

Response Mẫu 
{
  "success": true,
  "code": 200,
  "message": "Thông tin tài khoản đối tác",
  "data": {
    "username": "partner_vip",
    "email": "partner@viweb.vn",
    "balance": 500000,
    "total_deposit": 5000000,
    "created_at": "2026-01-15 10:20:30"
  }
}
4. Tên Miền & Tra Cứu Whois (Domains)
GET /domains/pricing Bảng giá tên miền

Trả về danh sách các đuôi tên miền (TLD) đang mở bán và mức giá theo năm.

{
  "success": true,
  "code": 200,
  "message": "Bảng giá tên miền",
  "data": {
    "pricing": [
      { "id": 1, "tld": ".com", "price": 280000 },
      { "id": 2, "tld": ".vn", "price": 550000 },
      { "id": 3, "tld": ".net", "price": 290000 }
    ]
  }
}
GET /domains/check?domain=shopgiare.com Tra cứu Whois tên miền

Kiểm tra tên miền đã có ai đăng ký hay chưa để cho phép khách mua.

{
  "success": true,
  "code": 200,
  "message": "Kết quả kiểm tra tên miền",
  "data": {
    "domain": "shopgiare.com",
    "tld": ".com",
    "available": true,
    "price_per_year": 280000
  }
}
POST /domains/buy Đăng ký mua tên miền mới

Đăng ký mua tên miền và tự động trừ số dư tài khoản đối tác.

Request Body (JSON)
{
  "domain": "shopgameacc.com",
  "years": 1,
  "nameservers": [
    "ns1.viweb.vn",
    "ns2.viweb.vn"
  ],
  "ip": "103.145.63.12"
}
Response (HTTP 201)
{
  "success": true,
  "code": 201,
  "message": "Đăng ký mua tên miền thành công",
  "data": {
    "order_id": 58,
    "domain": "shopgameacc.com",
    "years": 1,
    "amount_charged": 280000,
    "status": "xuly"
  }
}
GET /domains/order/{id} Tra cứu trạng thái đơn tên miền

Trả về thông tin chi tiết, trạng thái kích hoạt và thời hạn của đơn tên miền `{id}`.

5. Tự Động Khởi Tạo Shop Game (Shops Automation)
GET /shops/templates Danh sách mẫu source code shop game

Lấy các mã nguồn shop game đang được hỗ trợ tạo tự động.

{
  "success": true,
  "code": 200,
  "message": "Danh sách mẫu shop game",
  "data": {
    "templates": [
      {
        "id": 12,
        "name": "Mẫu Shop Bán Acc Free Fire V4",
        "price_per_month": 80000,
        "image": "https://viweb.vn/anh/demo12.png",
        "demo_url": "https://demo12.viweb.vn"
      }
    ]
  }
}
GET /shops/subdomain-roots Đuôi miền máy chủ Subdomain

Lấy danh sách các domain gốc (ví dụ: `viweb.vn`) để chọn làm đuôi miền cho shop subdomain.

POST /shops/create-subdomain Tạo shop Subdomain tự động

Khởi tạo nhanh shop game chạy dưới tên miền phụ (VD: `accvip.viweb.vn`).

Request Body (JSON)
{
  "template_id": 12,
  "subdomain": "accvip",
  "server_id": 1,
  "months": 1
}
Response (HTTP 201)
{
  "success": true,
  "code": 201,
  "message": "Tạo shop subdomain thành công.",
  "data": {
    "order_id": 1045,
    "full_domain": "accvip.viweb.vn",
    "amount_charged": 80000,
    "status": "xuly"
  }
}
POST /shops/create-addon Tạo shop tên miền riêng (Addon Domain)

Tạo shop game chạy trên tên miền riêng của khách hàng.

Request Body (JSON)
{
  "template_id": 12,
  "domain": "shopaccgiare.com",
  "server_id": 1,
  "months": 1
}
Response (HTTP 201)
{
  "success": true,
  "code": 201,
  "message": "Tạo shop addon domain thành công.",
  "data": {
    "order_id": 1046,
    "domain": "shopaccgiare.com",
    "amount_charged": 80000,
    "status": "xuly",
    "note": "Trỏ bản ghi A về IP máy chủ."
  }
}
GET /shops/order/{id} Tra cứu tiến độ cài đặt shop

Tiến trình Worker tự động giải nén source, cài CSDL và cấp phát SSL mất khoảng 30 - 90 giây. Gọi API này để kiểm tra xem shop đã sẵn sàng hay chưa. 

{
  "success": true,
  "code": 200,
  "message": "Thông tin đơn hàng website",
  "data": {
    "order": {
      "order_id": 1045,
      "domain": "accvip.viweb.vn",
      "type": "subdomain",
      "amount": 80000,
      "status": "hoantat",
      "note": "Thanh Cong!",
      "created_at": "2026-10-18 11:35:00",
      "expire_at": "2026-11-18 11:35:00"
    }
  }
}
6. Code Mẫu Tích Hợp (SDK / Code Snippets)
php-curl-example.php 
<?php
$apiKey = 'YOUR_API_KEY_HERE';
$endpoint = 'https://www.viweb.vn/api/v1/shops/create-subdomain';

$payload = [
    'template_id' => 12,
    'subdomain'   => 'shopvip' . random_int(100, 999),
    'server_id'   => 1,
    'months'      => 1,
];

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'X-API-KEY: ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
python-example.py 
import requests

API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://www.viweb.vn/api/v1"

headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
}

# 1. Kiểm tra số dư tài khoản
profile = requests.get(f"{BASE_URL}/profile", headers=headers).json()
print("Số dư hiện tại:", profile['data']['balance'])

# 2. Tạo shop game Subdomain
payload = {
    "template_id": 12,
    "subdomain": "shoptest88",
    "server_id": 1,
    "months": 1
}
res = requests.post(f"{BASE_URL}/shops/create-subdomain", json=payload, headers=headers).json()
print("Kết quả tạo shop:", res)
nodejs-example.js 
const axios = require('axios');

const client = axios.create({
  baseURL: 'https://www.viweb.vn/api/v1',
  headers: {
    'X-API-KEY': 'YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  }
});

async function run() {
  try {
    const res = await client.post('/shops/create-subdomain', {
      template_id: 12,
      subdomain: 'gameacc88',
      server_id: 1,
      months: 1
    });
    console.log('Tạo shop thành công:', res.data);
  } catch (error) {
    console.error('Lỗi API:', error.response ? error.response.data : error.message);
  }
}

run();
7. Lưu Ý Kỹ Thuật & Cơ Chế Hoàn Tiền Tự Động
Worker Bất Đồng Bộ

Lệnh tạo shop trả về ngay với mã 201 và status = "xuly". Hệ thống mất 30 - 90s để tạo vhost, SSL và giải nén source ngầm. Bạn nên cấu hình polling mỗi 5-10s gọi vào /shops/order/{id}.

Tự Động Hoàn Tiền 100%

Nếu quá trình cài đặt lỗi do tên miền chưa trỏ hoặc máy chủ gặp sự cố, Worker sẽ tự động chuyển đơn sang trạng thái huy và hoàn tiền ngay 100% vào tài khoản đối tác.

Bảo Mật Tuyệt Đối

Tuyệt đối không lưu và gửi API Key từ phía Frontend Javascript của trình duyệt người dùng. Mọi cuộc gọi API cần đi qua máy chủ Backend của bạn để bảo mật số dư.