🔌 Tài liệu Tích hợp API Đối tác (Partner API)

1. Xác thực (Authorization)

Mọi request gửi lên hệ thống bắt buộc phải gửi kèm Token trong HTTP Header:

Authorization: Bearer vicstar_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Accept: application/json

* Toàn bộ dữ liệu trả về ở định dạng JSON chuẩn. Token sai, bị khoá hoặc thiếu header sẽ nhận lỗi 401 Unauthorized.

2. Kiểm tra số dư ví đại lý

Trả về số dư ví hiện tại của đối tác. Khuyến nghị hệ thống của bạn kiểm tra số dư trước khi kích hoạt gói để chủ động nạp thêm tiền khi ví sắp hết.

{
  "success": true,
  "balance": 2500000
}

3. Danh sách gói SIM vật lý & Đơn giá

Trả về danh sách các gói cước SIM vật lý đã được Quản trị viên cấp quyền tích hợp cho tài khoản đối tác của bạn. Giá trả về (price) đã tự động trừ chiết khấu riêng của tài khoản.

{
  "success": true,
  "count": 2,
  "plans": [
    {
      "plan_id": 9,
      "name": "Nhật Bản Softbank 1GB/ngày",
      "country": "Nhật Bản",
      "operator": "Softbank",
      "data_amount": "1GB/ngày",
      "validity_days": 1,
      "is_daily": true,
      "price": 9000,
      "min_days": 1,
      "max_days": 30,
      "price_day_1": 18000,
      "price_day_30": 270000,
      "note": "Gói tính theo ngày: truyền tham số days (1-30). Đơn giá ngày giảm dần theo số ngày nạp."
    },
    {
      "plan_id": 15,
      "name": "Thái Lan TrueMove 15GB 8 ngày",
      "country": "Thái Lan",
      "operator": "TrueMove",
      "data_amount": "Tổng 15GB",
      "validity_days": 8,
      "is_daily": false,
      "price": 115000,
      "note": "Gói trọn gói: tính theo giá cố định của gói."
    }
  ]
}

4. Kích hoạt SIM vật lý theo ngày (1 – 30 ngày)

Nạp cước cho 1 số thẻ SIM (ICCID). Hệ thống sẽ tự động trừ số dư ví đại lý theo đơn giá đã chiết khấu, tự động gửi lệnh kích hoạt sang nhà mạng và tự động hoàn tiền 100% về ví trong tích tắc nếu thẻ SIM bị lỗi.

{
  "plan_id": 9,
  "iccid": "8984040000000000001",
  "days": 7,
  "partner_ref": "MY-ACT-2026-001",
  "dry_run": false
}

{
  "success": true,
  "activation_id": 105,
  "status": "pending",
  "partner_ref": "MY-ACT-2026-001",
  "days": 7,
  "fee": 79000,
  "balance": 2421000,
  "message": "Yêu cầu nạp SIM đã được gửi thành công tới nhà mạng."
}

{
  "success": true,
  "dry_run": true,
  "plan_id": 9,
  "plan_name": "Nhật Bản Softbank 1GB/ngày",
  "is_daily": true,
  "iccid": "8984040000000000001",
  "days": 7,
  "fee": 79000,
  "balance": 2500000,
  "has_sufficient_balance": true,
  "message": "Dữ liệu hợp lệ. Số dư ví đủ (2.500.000đ >= 79.000đ). Sẵn sàng kích hoạt thật."
}

5. Tra cứu trạng thái đơn kích hoạt SIM

Tra cứu kết quả xử lý của đơn nạp. Tham số {ref} có thể là partner_ref của phía bạn hoặc activation_id do hệ thống trả về.

{
  "success": true,
  "activation_id": 105,
  "iccid": "8984040000000000001",
  "status": "completed",
  "partner_ref": "MY-ACT-2026-001",
  "days": 7,
  "fee": 79000,
  "error": null,
  "created_at": "2026-10-05 01:15:00"
}

6. Tra cứu lưu lượng & Hạn dùng số thẻ ICCID

Kiểm tra thông tin tình trạng thẻ SIM, lưu lượng dữ liệu đã tiêu thụ, ngày bắt đầu và kết thúc sử dụng gói cước.

{
  "success": true,
  "found": true,
  "iccid": "8984040000000000001",
  "status_label": "Đang hoạt động (Active)",
  "plan_start": "2026-10-01 08:30:00",
  "plan_end": "2026-10-08 08:30:00",
  "data_used_label": "2.45 GB",
  "usage_history": []
}

7. Mã nguồn mẫu tích hợp

curl -X POST 'https://esim.vicstar.vn/api/v1/sim-activations' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "plan_id": 9,
    "iccid": "8984040000000000001",
    "days": 7,
    "partner_ref": "REF-ORDER-001",
    "dry_run": false
  }'

<?php
$token = 'YOUR_API_TOKEN';
$data = [
    'plan_id'     => 9,
    'iccid'       => '8984040000000000001',
    'days'        => 7,
    'partner_ref' => 'REF-' . time(),
    'dry_run'     => false,
];

$ch = curl_init('https://esim.vicstar.vn/api/v1/sim-activations');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($ch);
$resData = json_decode($response, true);
curl_close($ch);

if (!empty($resData['success'])) {
    echo "Kích hoạt thành công đơn: " . $resData['partner_ref'];
} else {
    echo "Lỗi: " . ($resData['error'] ?? 'Không rõ lỗi');
}

const axios = require('axios');

async function activateSim() {
  try {
    const res = await axios.post('https://esim.vicstar.vn/api/v1/sim-activations', {
      plan_id: 9,
      iccid: '8984040000000000001',
      days: 7,
      partner_ref: 'REF-' + Date.now(),
      dry_run: false
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    console.log('Thành công:', res.data);
  } catch (err) {
    console.error('Lỗi gọi API:', err.response ? err.response.data : err.message);
  }
}

activateSim();

8. Bảng mã phản hồi & Xử lý lỗi