# HƯỚNG DẪN KẾT NỐI RESELLER API - SIEUTHICLOUD247 - DịCH Vụ TREO MáY ẢO CLOUD PHONE

> **Phiên bản API**: v1.0 (RESTful JSON API)  
> **Base URL**: `https://www.sieuthicloud247.com/api/v1`  
> **Base URL thay thế**: `https://www.sieuthicloud247.com/api`  
> **Thời gian tạo**: 07/11/2026 12:34:03  
> **API Token của bạn**: `YOUR_API_TOKEN_HERE`

---

## 1. TỔNG QUAN & XÁC THỰC

Tất cả các API yêu cầu xác thực bằng **API Token** cá nhân của tài khoản đối tác. Bạn có thể truyền Token qua một trong các cách sau (ưu tiên truyền qua HTTP Header):

### Header xác thực (Khuyến nghị):
```http
Authorization: Bearer YOUR_API_TOKEN_HERE
```
hoặc:
```http
X-Api-Key: YOUR_API_TOKEN_HERE
```

### Định dạng dữ liệu:
- **Request**: `application/json` (hoặc form-data / x-www-form-urlencoded).
- **Response**: `application/json; charset=UTF-8`.
- **Chống trừ tiền 2 lần (Idempotency)**: Khi gọi API mua hàng, khuyến nghị gửi kèm `client_order_code` hoặc header `X-Idempotency-Key` (mã đơn duy nhất của Web Con). Nếu đường truyền mạng chập chờn, gọi lại cùng mã đơn này sẽ không bị trừ tiền thêm lần nữa.

---

## 2. DANH MỤC API

| Phương thức | Endpoint | Mô tả |
|---|---|---|
| `GET` | `/api/v1/profile` | Tra cứu số dư và trạng thái tài khoản |
| `GET` | `/api/v1/categories` | Lấy danh sách danh mục sản phẩm |
| `GET` | `/api/v1/products` | Lấy danh sách sản phẩm, tồn kho và giá bán |
| `GET` | `/api/v1/products/{id}` | Lấy chi tiết sản phẩm và các trường custom fields |
| `GET` | `/api/v1/genplay/plans` | Lấy danh sách gói Cloud Phone Genplay |
| `POST` | `/api/v1/genplay/buy` | Thuê máy ảo Android Cloud Phone Genplay |
| `GET` | `/api/v1/genplay/orders/{code}` | Tra cứu mã kích hoạt Cloud Phone theo mã đơn |
| `POST` | `/api/v1/buy` | Mua hàng (Giao tài khoản ngay hoặc đặt đơn dịch vụ Orders) |
| `GET` | `/api/v1/orders/{code}` | Tra cứu trạng thái và tài khoản đã bàn giao của đơn hàng |
| `POST` | `/api/callback/order` | Webhook nhận thông báo duyệt đơn / hoàn tiền từ Web Mẹ |

---

## 3. CHI TIẾT CÁC ENDPOINT

### 3.1. Tra cứu thông tin & Số dư (`GET /api/v1/profile`)

#### cURL:
```bash
curl -X GET "https://www.sieuthicloud247.com/api/v1/profile" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Accept: application/json"
```

#### Phản hồi thành công (HTTP 200):
```json
{
  "status": true,
  "id": 1,
  "username": "partner_reseller",
  "email": "partner@example.com",
  "balance": 500000,
  "status": "active"
}
```

---

### 3.2. Lấy danh sách sản phẩm & Tồn kho (`GET /api/v1/products`)

Tham số URL tùy chọn:
- `category_id`: Lọc theo ID danh mục.
- `search`: Từ khóa tìm kiếm tên sản phẩm.
- `limit`: Giới hạn kết quả (mặc định 50, tối đa 100).
- `page`: Trang phân trang.

#### cURL:
```bash
curl -X GET "https://www.sieuthicloud247.com/api/v1/products?limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Accept: application/json"
```

#### Phản hồi mẫu (HTTP 200):
```json
{
  "status": true,
  "data": [
    {
      "id": 10,
      "name": "Tài khoản Canva Pro Edu 1 Năm",
      "slug": "canva-pro-1-nam",
      "price": 45000,
      "price_raw": 45000,
      "stock": 150,
      "stock_raw": 150,
      "is_out_of_stock": false,
      "delivery_type": "instant",
      "is_manual": false
    },
    {
      "id": 25,
      "name": "Cloud Phone Treo Game 24/7",
      "slug": "cloud-phone-treo-game",
      "price": 120000,
      "price_raw": 120000,
      "stock": "Sẵn sàng",
      "stock_raw": 999999,
      "is_out_of_stock": false,
      "delivery_type": "manual",
      "is_manual": true,
      "custom_fields": [
        {
          "name": "os_type",
          "label": "Hệ điều hành (Android / iOS)",
          "type": "text",
          "required": true
        }
      ]
    }
  ]
}
```

---

### 3.3. Mua hàng & Đặt đơn (`POST /api/v1/buy`)

Endpoint dùng chung để mua cả:
1. **Sản phẩm có sẵn tài khoản (`delivery_type: instant`)**: Giao tài khoản ngay tức thì trong response.
2. **Sản phẩm dịch vụ chờ duyệt (`delivery_type: manual` / Orders)**: Nhận đơn, trừ tiền và chuyển trạng thái `pending`. Khi Web Mẹ duyệt, tài khoản hoặc nội dung bàn giao sẽ được bắn qua Webhook hoặc tra cứu qua API.

#### Tham số gửi lên (JSON body):
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| `product_id` | Integer | **Có** | ID sản phẩm cần mua |
| `quantity` | Integer | **Có** | Số lượng cần mua (tối thiểu 1) |
| `plan_id` | Mixed | Không | ID gói nếu sản phẩm có nhiều gói lựa chọn |
| `fields` | Object | Tùy sản phẩm | Dữ liệu thông tin nếu sản phẩm yêu cầu (ví dụ: `{"uid": "123456"}`) |
| `client_order_code` | String | **Khuyến nghị** | Mã đơn riêng của Web Con (chống trừ tiền trùng lặp) |
| `callback_url` | String | **Khuyến nghị** | Webhook URL của Web Con để nhận kết quả khi Web Mẹ duyệt / hủy |

#### Ví dụ cURL Mua tài khoản có sẵn:
```bash
curl -X POST "https://www.sieuthicloud247.com/api/v1/buy" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "product_id": 10,
    "quantity": 2,
    "client_order_code": "CON_ORDER_1001"
  }'
```

#### Phản hồi thành công (Giao tài khoản ngay):
```json
{
  "status": true,
  "message": "Mua hàng thành công!",
  "order": {
    "id": 850,
    "code": "DH91823",
    "quantity": 2,
    "total_amount": 90000,
    "status": "completed"
  },
  "accounts": [
    {
      "details": "canva01@gmail.com|pass123"
    },
    {
      "details": "canva02@gmail.com|pass456"
    }
  ]
}
```

#### Ví dụ cURL Đặt đơn dịch vụ / Dạng Orders:
```bash
curl -X POST "https://www.sieuthicloud247.com/api/v1/buy" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "product_id": 25,
    "quantity": 1,
    "client_order_code": "CON_ORDER_1002",
    "callback_url": "https://web-con-cua-ban.com/api/callback/order",
    "fields": {
      "os_type": "Android 13",
      "app_target": "Roblox"
    }
  }'
```

#### Phản hồi ghi nhận đơn dạng Orders (Chờ duyệt):
```json
{
  "status": true,
  "message": "Đặt hàng thành công! Đơn hàng đã được ghi nhận và đang chờ duyệt.",
  "is_pending_order": true,
  "order": {
    "id": 851,
    "code": "DH91824",
    "quantity": 1,
    "total_amount": 120000,
    "status": "pending"
  },
  "accounts": []
}
```

---

### 3.4. Tra cứu đơn hàng (`GET /api/v1/orders/{code}`)

Bạn có thể tra cứu bằng:
- Mã đơn Web Mẹ (ví dụ: `DH91824`).
- Mã đơn riêng của Web Con (`client_order_code` truyền lúc mua, ví dụ: `CON_ORDER_1002`).

#### cURL:
```bash
curl -X GET "https://www.sieuthicloud247.com/api/v1/orders/DH91824" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Accept: application/json"
```

#### Phản hồi mẫu (Khi đơn đã được duyệt hoàn thành):
```json
{
  "status": true,
  "data": {
    "id": 851,
    "code": "DH91824",
    "status": "completed",
    "delivery_type": "manual",
    "delivery_content": "IP: 103.142.20.15\nPort: 5555\nUser: admin / Pass: Cloud@2026",
    "refund_status": null,
    "total_amount": 120000,
    "items": [
      {
        "id": 1200,
        "product_name": "Cloud Phone Treo Game 24/7",
        "quantity": 1,
        "status": "delivered",
        "account_details": "IP: 103.142.20.15\nPort: 5555\nUser: admin / Pass: Cloud@2026"
      }
    ]
  }
}
```

---

### 3.5. Dịch vụ Cloud Phone Genplay API

#### 3.5.1. Lấy danh sách gói Cloud Phone (`GET /api/v1/genplay/plans`)
```bash
curl -X GET "https://www.sieuthicloud247.com/api/v1/genplay/plans" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Accept: application/json"
```

Phản hồi mẫu:
```json
{
  "status": true,
  "message": "Lấy danh sách gói Cloud Phone Genplay thành công.",
  "total": 2,
  "data": [
    {
      "price_id": 120,
      "plan_id": 15,
      "name": "Cloud Phone RAM 4GB - Android 10",
      "category": "Gói Tiêu Chuẩn",
      "days": 1,
      "price": 50000,
      "currency": "VND",
      "is_active": true,
      "specs": {
        "ram": "4GB",
        "rom": "32GB",
        "android": "10"
      }
    }
  ]
}
```

#### 3.5.2. Thuê Cloud Phone tự động (`POST /api/v1/genplay/buy`)
```bash
curl -X POST "https://www.sieuthicloud247.com/api/v1/genplay/buy" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "price_id": 120,
    "quantity": 1,
    "client_order_code": "GP_RESELLER_001"
  }'
```

Phản hồi mẫu:
```json
{
  "status": true,
  "message": "Thuê thiết bị Cloud Phone Genplay thành công!",
  "data": {
    "order_code": "GP261106A1B2C3",
    "invoice_code": "GP261106A1B2C3",
    "plan_name": "Cloud Phone RAM 4GB (1 ngày)",
    "price_id": 120,
    "quantity": 1,
    "total_amount": 50000,
    "status": "completed",
    "codes": [
      "GPCODE-4GB-9823-7182-9912"
    ],
    "balance_after": 450000,
    "created_at": "2026-11-06T12:00:00.000000Z"
  }
}
```

#### 3.5.3. Tra cứu hóa đơn & Mã kích hoạt Cloud Phone (`GET /api/v1/genplay/orders/{code}`)
```bash
curl -X GET "https://www.sieuthicloud247.com/api/v1/genplay/orders/GP261106A1B2C3" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Accept: application/json"
```

Phản hồi mẫu:
```json
{
  "status": true,
  "data": {
    "id": 189,
    "invoice_code": "GP261106A1B2C3",
    "order_code": "GP261106A1B2C3",
    "plan_name": "Cloud Phone RAM 4GB (1 ngày)",
    "price_id": 120,
    "quantity": 1,
    "amount": 50000,
    "status": "completed",
    "codes": [
      "GPCODE-4GB-9823-7182-9912"
    ],
    "created_at": "2026-11-06T12:00:00.000000Z"
  }
}
```

---

## 4. CƠ CHẾ ĐỒNG BỘ ĐƠN HÀNG (WEB MẸ & WEB CON)

Hệ thống hỗ trợ 2 chiều đồng bộ tự động 100%:

### 1. Web Mẹ duyệt đơn -> Web Con tự duyệt:
Khi Admin trên Web Mẹ duyệt đơn và điền nội dung bàn giao:
- Web Mẹ sẽ gửi một request `POST` tới `callback_url` của bạn:
  ```json
  {
    "event": "order.delivered",
    "order_id": 851,
    "order_code": "DH91824",
    "client_order_code": "CON_ORDER_1002",
    "status": "completed",
    "delivery_content": "Nội dung bàn giao key / acc / link..."
  }
  ```
- Web Con tự động chuyển trạng thái đơn hàng sang `Hoàn thành` và bàn giao ngay lập tức cho khách hàng của bạn!

### 2. Web Mẹ hủy đơn / từ chối -> Web Con tự hoàn tiền:
Nếu sản phẩm hết tài nguyên hoặc Admin Web Mẹ từ chối đơn:
- Web Mẹ sẽ gửi webhook:
  ```json
  {
    "event": "order.cancelled",
    "order_id": 851,
    "order_code": "DH91824",
    "client_order_code": "CON_ORDER_1002",
    "status": "refunded",
    "refund_amount": 120000,
    "refund_reason": "Sản phẩm tạm thời hết tài nguyên"
  }
  ```
- Web Con tự động **cộng lại số tiền đã trừ vào số dư ví của khách hàng**, tạo lịch sử biến động số dư và ghi chú lý do hủy rõ ràng.

### 3. Đối soát định kỳ (Fallback Cronjob):
Nếu webhook bị chặn bởi tường lửa hoặc mạng chập chờn, Web Con có thể cài cronjob gọi `php artisan supplier:reconcile` (mỗi 5 phút một lần). Hệ thống sẽ tự động đối soát tất cả các đơn hàng đang `pending` và tự động duyệt hoặc hoàn tiền tương ứng.

---

## 5. CODE MẪU TÍCH HỢP ĐA NGÔN NGỮ

### PHP (cURL):
```php
<?php
$token = 'YOUR_API_TOKEN_HERE';
$url = 'https://www.sieuthicloud247.com/api/v1/buy';

$data = [
    'product_id'        => 10,
    'quantity'          => 1,
    'client_order_code' => 'ORDER_' . time(),
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer ' . $token,
]);

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

$result = json_decode($response, true);
print_r($result);
```

### Python (Requests):
```python
import requests

url = "https://www.sieuthicloud247.com/api/v1/buy"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN_HERE",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

payload = {
    "product_id": 10,
    "quantity": 1,
    "client_order_code": "PYTHON_ORDER_001"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### Node.js (Axios):
```javascript
const axios = require('axios');

async function buyProduct() {
  try {
    const response = await axios.post('https://www.sieuthicloud247.com/api/v1/buy', {
      product_id: 10,
      quantity: 1,
      client_order_code: 'NODEJS_ORDER_001'
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN_HERE',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

buyProduct();
```

---

## 6. MÃ LỖI THƯỜNG GẶP (HTTP STATUS CODES)

| Mã HTTP | Tình trạng | Nguyên nhân & Cách xử lý |
|---|---|---|
| `200 OK` | Thành công | Giao dịch hoặc tra cứu thành công. |
| `400 Bad Request` | Tham số không hợp lệ | Thiếu `product_id`, `quantity` hoặc thông tin `fields` bắt buộc. |
| `401 Unauthorized` | Sai API Token | API Token không chính xác, thiếu hoặc tài khoản bị khóa. |
| `404 Not Found` | Không tìm thấy | Sản phẩm không tồn tại hoặc đã ngừng kinh doanh. |
| `422 Unprocessable` | Thất bại nghiệp vụ | Số dư tài khoản không đủ hoặc sản phẩm đã hết hàng trong kho. |
| `429 Too Many Requests` | Vượt tần suất gọi | Bạn đang gửi yêu cầu quá nhanh. Vui lòng thử lại sau ít giây. |
| `500 Server Error` | Lỗi hệ thống | Vui lòng liên hệ Admin để được hỗ trợ kiểm tra. |

---
*Tài liệu được phát hành tự động bởi SIEUTHICLOUD247 - Dịch Vụ Treo Máy Ảo Cloud Phone Reseller Gateway.*