v1.0OpenAPI 3.2.0SMS-Activate Compatible

Tải tài liệu OpenAPI Lấy API Key Của Bạn

Giao thức API nhận mã SMS (Tương thích chuẩn SMS-Activate)

Tích hợp tự động hóa thuê số nhận mã SMS OTP, cuộc gọi FlashCall và thuê hòm thư Email OTP vào bot Telegram, công cụ nuôi nick, tool MMO hoặc website của bạn.

Software Connection Guide

Chọn bất kỳ phần mềm/tool nào hỗ trợ dịch vụ nhận SMS theo chuẩn SMS-Activate.

Chọn dịch vụ SMS-Activate làm cổng nhận SMS trong cài đặt tool.

Thay đổi địa chỉ máy chủ từ https://api.sms-activate.ae thành https://hero-sms.com/stubs/handler_api.php trong cài đặt phần mềm.

https://hero-sms.com/stubs/handler_api.php

Nhập API Key từ trang hồ sơ tài khoản của bạn trên website.

Nếu gặp bất kỳ khó khăn nào, vui lòng liên hệ bộ phận hỗ trợ kỹ thuật. Chúng tôi sẽ giải quyết mọi vấn đề.

Máy chủ API

https://hero-sms.com/api

Xác thực API

x-api-key: your_api_key_here

#!/usr/bin/env bash
# OTP Activation Flow (SMS-Activate Compatible)
set -euo pipefail

BASE_URL="https://hero-sms.com/stubs/handler_api.php"
API_KEY="YOUR_API_KEY"
SERVICE="tg"   # Telegram service code
COUNTRY="0"    # Country ID (e.g. 0 = Russia, 10 = Vietnam)

echo "==> 1. Checking account balance..."
curl -s -H "x-api-key: ${API_KEY}" "${BASE_URL}?action=getBalance"
echo ""

echo "==> 2. Ordering a phone number..."
BUY_RES=$(curl -s -H "x-api-key: ${API_KEY}" "${BASE_URL}?action=getNumber&service=${SERVICE}&country=${COUNTRY}")
echo "Response: ${BUY_RES}"

# Expected format: ACCESS_NUMBER:$ACTIVATION_ID:$PHONE
if [[ "${BUY_RES}" != ACCESS_NUMBER* ]]; then
  echo "Error buying number: ${BUY_RES}"
  exit 1
fi

ACTIVATION_ID=$(echo "${BUY_RES}" | cut -d':' -f2)
PHONE_NUMBER=$(echo "${BUY_RES}" | cut -d':' -f3)
echo "Acquired number: +${PHONE_NUMBER} (Activation ID: ${ACTIVATION_ID})"

echo "==> 3. Polling for OTP code..."
MAX_ATTEMPTS=24 # 2 minutes (24 * 5 seconds)
OTP_CODE=""

for ((i=1; i<=MAX_ATTEMPTS; i++)); do
  sleep 5
  STATUS_RES=$(curl -s -H "x-api-key: ${API_KEY}" "${BASE_URL}?action=getStatus&id=${ACTIVATION_ID}")
  echo "Poll ${i}/${MAX_ATTEMPTS}: ${STATUS_RES}"

  if [[ "${STATUS_RES}" == STATUS_OK* ]]; then
    OTP_CODE=$(echo "${STATUS_RES}" | cut -d':' -f2)
    echo "Successfully received OTP: ${OTP_CODE}"
    break
  fi

  if [[ "${STATUS_RES}" == "STATUS_CANCEL" ]]; then
    echo "Activation was cancelled."
    exit 1
  fi
done

if [[ -n "${OTP_CODE}" ]]; then
  echo "==> 4. Finishing activation..."
  FINISH_RES=$(curl -s -H "x-api-key: ${API_KEY}" "${BASE_URL}?action=setStatus&id=${ACTIVATION_ID}&status=6")
  echo "Finish status: ${FINISH_RES}"
else
  echo "==> Timed out waiting for SMS. Requesting cancel/refund..."
  CANCEL_RES=$(curl -s -H "x-api-key: ${API_KEY}" "${BASE_URL}?action=setStatus&id=${ACTIVATION_ID}&status=8")
  echo "Cancel status: ${CANCEL_RES}"
fi

Cursor / Windsurf / Claude Code / Copilot

Prompt tích hợp Cursor / Windsurf / Claude Code

Tải openapi.json

Prompt AI tối ưu sẵn cho phép trợ lý code (Cursor, Windsurf, Claude Code) tích hợp API chỉ trong 1 lần yêu cầu.

Integration Prompt Excerpt

# OTP & SMS Gateway Integration Guide (SMS-Activate Compatible)

You are tasked with building a robust, production-grade integration with this SMS/OTP Verification Service.
This service is fully compatible with the standard **SMS-Activate** protocol and also exposes a standard REST API.

---

## 1. OpenAPI Specification Import
Before writing code, import or inspect the full OpenAPI specification at:
```
https://hero-sms.com/api/docs/openapi?download=1
```
Use this JSON specification in Cursor, Windsurf, Postman, or Claude to inspect all schemas, models, and endpoints.

---

## 2. Base Endpoint & Protocol Overview
- **Primary SMS-Activate Endpoint**: `https://hero-sms.com/stubs/handler_api.php`
- **Supported HTTP Methods**: `GET` (parameters via query string) and `POST` (supports JSON, multipart, or application/x-www-form-urlencoded).
- **Authentication**:
  - Query parameter: `?api_key=YOUR_API_KEY`
  - Or HTTP Header: `x-api-key: YOUR_API_KEY`
  - Or Authorization header: `Authorization: Bearer YOUR_API_KEY`

---

## 3. Complete Activation Lifecycle Steps

### Step 1: Check Account Balance (`getBalance`)
Query available USD balance before placing orders.
- **Request**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getBalance`
- **Success Response**:
  `ACCESS_BALANCE:15.50`
- **Error Responses**:
  `BAD_KEY` (invalid API key)

### Step 2: Rent / Buy Phone Number (`getNumber` or `getNumberV2`)
Request a temporary phone number for a target service and country.
- **Request (Plain Text)**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getNumber&service=tg&country=0`
- **Success Response**:
  `ACCESS_NUMBER:123456:84987654321`
  - Format: `ACCESS_NUMBER:<activationId>:<phoneNumber>`
- **Request (JSON Format - V2)**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getNumberV2&service=tg&country=0`
- **Success Response (V2 JSON)**:
  ```json
  {
    "activationId": "123456",
    "phoneNumber": "84987654321",
    "activationCost": 0.15,
    "currency": "USD"
  }
  ```
- **Common Error Responses**:
  - `NO_NUMBERS`: No numbers currently in stock for this service/country.
  - `NO_BALANCE`: Insufficient balance.
  - `BAD_SERVICE`: Invalid service or country parameter.

### Step 3: Poll for OTP Code (`getStatus` or `getStatusV2`)
Poll every 3–5 seconds until the SMS verification code is received.
- **Request (Plain Text)**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getStatus&id=123456`
- **Responses**:
  - `STATUS_WAIT_CODE`: Still waiting for SMS. Continue polling.
  - `STATUS_OK:987654`: OTP received! Code is `987654`.
  - `STATUS_CANCEL`: Activation was cancelled or refunded. Stop polling.
- **Request (JSON Format - V2)**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getStatusV2&id=123456`
- **Success Response (V2 JSON)**:
  ```json
  {
    "status": "OK",
    "smsCode": "987654",
    "smsText": "Your verification code is 987654",
    "receivedAt": "2026-10-07T10:00:00.000Z"
  }
  ```

### Step 4: Finish Activation (`setStatus=6`)
Call after receiving the OTP code and successfully verifying the user/service account.
- **Request**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=setStatus&id=123456&status=6`
- **Success Response**:
  `ACCESS_ACTIVATION`

### Step 5: Cancel & Refund Activation (`setStatus=8`)
Call if timed out or if no SMS was received and you wish to release the number and refund wallet.
- **Request**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=setStatus&id=123456&status=8`
- **Success Response**:
  `ACCESS_CANCEL`
- **Error**:
  `EARLY_CANCEL_DENIED` (cannot cancel within early cooldown period, wait a minute and retry).

### Step 6: Query Prices & Stock (`getPrices`)
Retrieve available stock count and pricing for a service and country.
- **Request**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getPrices&service=tg&country=0`
- **Success Response (JSON)**:
  ```json
  {
    "0": {
      "tg": {
        "cost": 0.15,
        "count": 420
      }
    }
  }
  ```

### Step 7: Query Countries List (`getCountries`)
List all supported country IDs and localized names.
- **Request**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getCountries`
- **Success Response (JSON Array)**:
  ```json
  [
    { "id": 0, "rus": "Россия", "eng": "Russia", "chn": "俄罗斯" },
    { "id": 10, "rus": "Вьетнам", "eng": "Vietnam", "chn": "越南" }
  ]
  ```

---

## 4. Coding Assistant Implementation Requirements
When implementing the client module for your project:
1. **Class-based architecture**: Create an `OtpClient` with methods: `getBalance()`, `rentNumber(service, country)`, `pollOtp(activationId, options)`, `finish(activationId)`, `cancel(activationId)`, `getPrices(service, country)`, and `getCountries()`.
2. **Polling logic**:
   - Interval: 3 to 5 seconds.
   - Timeout: 120 seconds default.
   - If timeout is reached, automatically call `setStatus=8` to refund the balance.
3. **Robust error handling**:
   - Parse plain text prefixes: `ACCESS_NUMBER:<id>:<phone>`, `STATUS_OK:<code>`, and `ACCESS_BALANCE:<amount>`.
   - Throw explicit typed errors on `NO_NUMBERS`, `NO_BALANCE`, and `BAD_KEY`.
4. **Environment variable configuration**: Read `OTP_API_KEY` and optional `OTP_API_BASE_URL` (defaults to `https://hero-sms.com/stubs/handler_api.php`).

API Chung & Ví

3 endpoints

GET/api/user/balance

API Chung & Ví

Kiểm Tra Số Dư Ví & Thông Tin Tài Khoản

Truy vấn số dư ví khả dụng (VNĐ & USD) và email liên kết của tài khoản hiện tại.

Headers

x-api-key

your_api_key_here

API Key của tài khoản bạn

Phản hồi mẫu (Response)

{
  "success": true,
  "email": "[email protected]",
  "balance": 250000,
  "balanceVnd": 250000,
  "balanceUsd": 9.47,
  "balanceUsdFormatted": "$9.47",
  "usdRate": 26400
}

GET/api/otp/loyalty

API Chung & Ví

Cấp Bậc VIP & Tỷ Lệ Chiết Khấu (Loyalty)

Xem cấp bậc VIP hiện tại, tỷ lệ giảm giá đang áp dụng khi thuê số, mức nạp 7 ngày gần nhất và chi tiêu cần thêm để lên cấp.

Headers

x-api-key

your_api_key_here

API Key của tài khoản

Phản hồi mẫu (Response)

{
  "success": true,
  "data": {
    "userStatus": {
      "userId": "user_2tX8849...",
      "currentTier": 2,
      "tierName": "VIP 2",
      "discountPercent": 5,
      "weeklySpending": 350000,
      "nextTierSpendingNeeded": 150000,
      "nextTier": 3
    },
    "tiers": [
      {
        "tier": 0,
        "name": "Thành viên",
        "minWeekly": 0,
        "discountPercent": 0
      },
      {
        "tier": 1,
        "name": "VIP 1",
        "minWeekly": 100000,
        "discountPercent": 3
      },
      {
        "tier": 2,
        "name": "VIP 2",
        "minWeekly": 300000,
        "discountPercent": 5
      },
      {
        "tier": 3,
        "name": "VIP 3",
        "minWeekly": 500000,
        "discountPercent": 8
      },
      {
        "tier": 4,
        "name": "VIP 4",
        "minWeekly": 1000000,
        "discountPercent": 12
      },
      {
        "tier": 5,
        "name": "VIP 5",
        "minWeekly": 2000000,
        "discountPercent": 15
      }
    ]
  }
}

GET/api/otp/tiers

API Chung & Ví

Bảng Cấp Bậc VIP & Tỷ Lệ Chiết Khấu (Công Khai)

Tra cứu toàn bộ danh sách các bậc VIP và tỷ lệ giảm giá phần trăm tương ứng, không yêu cầu API key.

Phản hồi mẫu (Response)

{
  "success": true,
  "data": {
    "tiers": [
      {
        "tier": 0,
        "name": "Thành viên",
        "minWeekly": 0,
        "discountPercent": 0
      },
      {
        "tier": 1,
        "name": "VIP 1",
        "minWeekly": 100000,
        "discountPercent": 3
      },
      {
        "tier": 2,
        "name": "VIP 2",
        "minWeekly": 300000,
        "discountPercent": 5
      },
      {
        "tier": 3,
        "name": "VIP 3",
        "minWeekly": 500000,
        "discountPercent": 8
      },
      {
        "tier": 4,
        "name": "VIP 4",
        "minWeekly": 1000000,
        "discountPercent": 12
      },
      {
        "tier": 5,
        "name": "VIP 5",
        "minWeekly": 2000000,
        "discountPercent": 15
      }
    ],
    "description": "Weekly deposit tier discount table. Tiers are evaluated based on 7-day deposit total."
  }
}

API Thuê số & Nhận mã

18 endpoints

GET/api/otp/countries

API Thuê số & Nhận mã

Danh Sách Quốc Gia Hỗ Trợ

Lấy toàn bộ danh sách quốc gia khả dụng kèm ID quốc gia, cờ, và mã gọi quốc tế.

Phản hồi mẫu (Response)

{
  "success": true,
  "data": [
    {
      "id": 10,
      "name": "Vietnam",
      "code": "vn",
      "prefix": "+84"
    },
    {
      "id": 1,
      "name": "United States",
      "code": "us",
      "prefix": "+1"
    },
    {
      "id": 6,
      "name": "Indonesia",
      "code": "id",
      "prefix": "+62"
    },
    {
      "id": 4,
      "name": "Philippines",
      "code": "ph",
      "prefix": "+63"
    },
    {
      "id": 0,
      "name": "Russia",
      "code": "ru",
      "prefix": "+7"
    }
  ]
}

GET/api/otp/services

API Thuê số & Nhận mã

Danh Sách Ứng Dụng & Dịch Vụ SMS

Lấy danh sách ứng dụng nhận mã OTP (Telegram, Google, TikTok, Facebook, WhatsApp...) kèm số lượng số khả dụng và giá khởi điểm.

Tham số (Parameters)

Field	Type	Required	Description
country	number \| string	Optional	Lọc theo ID quốc gia (Ví dụ: 10 là Việt Nam, 1 là Mỹ, 6 là Indonesia)

Phản hồi mẫu (Response)

{
  "success": true,
  "tier": 0,
  "data": [
    {
      "code": "tg",
      "name": "Telegram",
      "count": 350000,
      "icon": "/icons/services/tg.webp",
      "prices": {
        "sellingUsd": 0.15,
        "sellingVnd": 4000,
        "tier": 0,
        "discountPercent": 0
      }
    },
    {
      "code": "go",
      "name": "Google, YouTube, Gmail",
      "count": 500000,
      "icon": "/icons/services/go.webp",
      "prices": {
        "sellingUsd": 0.05,
        "sellingVnd": 1400,
        "tier": 0,
        "discountPercent": 0
      }
    }
  ]
}

GET/api/otp/prices

API Thuê số & Nhận mã

Bảng Giá & Sổ Lệnh Chi Tiết

Tra cứu giá chi tiết của một dịch vụ tại quốc gia cụ thể, hỗ trợ xem sổ lệnh giá sàn (offers) cho cả SMS và FlashCall.

Tham số (Parameters)

Field	Type	Required	Description
service	string	Required	Mã dịch vụ (ví dụ: tg, go, fb, wa, lf, dr...)
country	number \| string	Optional	ID quốc gia (ví dụ: 10, 1, 6...)
verificationType	string	Optional	'sms' (mặc định) hoặc 'call' (FlashCall cuộc gọi)

Phản hồi mẫu (Response)

{
  "success": true,
  "tier": 0,
  "data": [
    {
      "service": "tg",
      "country": "10",
      "count": 12500,
      "prices": {
        "sellingUsd": 0.15,
        "sellingVnd": 4000,
        "tier": 0,
        "discountPercent": 0
      },
      "offers": [
        {
          "sellingUsd": 0.15,
          "sellingVnd": 4000,
          "count": 500
        },
        {
          "sellingUsd": 0.18,
          "sellingVnd": 4800,
          "count": 2000
        }
      ]
    }
  ]
}

GET/api/otp/operators

API Thuê số & Nhận mã

Danh Sách Nhà Mạng Hỗ Trợ (Telco Operators)

Lấy danh sách các nhà mạng viễn thông (Viettel, Vinaphone, Mobifone...) khả dụng theo quốc gia và dịch vụ.

Tham số (Parameters)

Field	Type	Required	Description
country	number \| string	Optional	ID quốc gia (ví dụ: 10 cho Việt Nam)
service	string	Optional	Mã dịch vụ (ví dụ: tg, go, fb...)

Phản hồi mẫu (Response)

{
  "success": true,
  "data": [
    {
      "code": "any",
      "name": "Bất kỳ nhà mạng nào (Nhanh nhất)"
    },
    {
      "code": "viettel",
      "name": "Viettel"
    },
    {
      "code": "mobifone",
      "name": "Mobifone"
    },
    {
      "code": "vinaphone",
      "name": "Vinaphone"
    }
  ]
}

POST/api/otp/buy

API Thuê số & Nhận mã

Thuê Số Nhận OTP Ngắn Hạn (SMS / FlashCall)

Khởi tạo đơn thuê số ngắn hạn (~20 phút). Hỗ trợ chọn nhà mạng, đặt mức giá trần và thuê số lượng lớn cùng lúc. Trả về mã đơn nội bộ orderCode (ví dụ: ACT8K3N9).

Headers

x-api-key	your_api_key_here	API Key
Content-Type	application/json	application/json

Tham số (Parameters)

Field	Type	Required	Description
service	string	Required	Mã dịch vụ (ví dụ: tg, go, fb, wa, lf...)
country	number \| string	Required	ID quốc gia (ví dụ: 10 cho Việt Nam, 1 cho Mỹ)
verificationType	string	Optional	'sms' (mặc định) hoặc 'call' (cuộc gọi FlashCall)
operator	string	Optional	Nhà mạng mong muốn (ví dụ: 'viettel', 'mobifone', hoặc 'any' - nhanh nhất)
maxPrice	number	Optional	Mức giá tối đa sẵn sàng trả (VNĐ), đơn sẽ không mua nếu giá thị trường vượt mức này
amount	number	Optional	Số lượng số muốn thuê cùng một lúc (1 đến 10, mặc định: 1)

Request Body (JSON)

{
  "service": "tg",
  "country": 10,
  "verificationType": "sms",
  "operator": "any",
  "maxPrice": 5000,
  "amount": 1
}

Phản hồi mẫu (Response)

{
  "success": true,
  "tier": 0,
  "balanceAfter": 246000,
  "data": [
    {
      "id": "ACT8K3N9",
      "orderCode": "ACT8K3N9",
      "phone": "84931002233",
      "service": "tg",
      "country": "10",
      "status": "WAIT_CODE",
      "price": {
        "sellingUsd": 0.15,
        "sellingVnd": 4000,
        "tier": 0,
        "discountPercent": 0
      },
      "createdAt": "2026-10-06T08:00:00.000Z",
      "expiredAt": "2026-10-06T08:20:00.000Z"
    }
  ]
}

GET/api/otp/activations

API Thuê số & Nhận mã

Danh Sách Đơn Đang Chờ & Lịch Sử

Lấy danh sách các đơn thuê số đang active (đang chờ mã) hoặc toàn bộ lịch sử đơn hàng của bạn.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
status	string	Optional	'ACTIVE' (chỉ đơn đang chờ mã) hoặc 'FINISHED', 'CANCELLED', 'REFUNDED'
limit	number	Optional	Số lượng đơn mỗi trang (mặc định: 20)

Phản hồi mẫu (Response)

{
  "success": true,
  "data": [
    {
      "id": "ACT8K3N9",
      "orderCode": "ACT8K3N9",
      "phone": "84931002233",
      "service": "tg",
      "serviceName": "Telegram",
      "country": "10",
      "status": "WAIT_CODE",
      "otpCode": null,
      "createdAt": "2026-10-06T08:00:00.000Z"
    }
  ]
}

GET/api/otp/activations/{id}

API Thuê số & Nhận mã

Kiểm Tra Trạng Thái & Lấy Mã OTP

Truy vấn trạng thái đơn bằng mã orderCode hệ thống (ví dụ: ACT8K3N9). Khi có tin nhắn SMS hoặc cuộc gọi FlashCall, mã OTP sẽ được trả về tức thì.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string	Required	Mã đơn nội bộ hệ thống (orderCode, ví dụ: ACT8K3N9)

Phản hồi mẫu (Response)

{
  "success": true,
  "data": {
    "id": "ACT8K3N9",
    "orderCode": "ACT8K3N9",
    "status": "OK",
    "phone": "84931002233",
    "lastOtp": {
      "code": "891024",
      "text": "Telegram code: 891024"
    },
    "otpList": [
      {
        "code": "891024",
        "text": "Telegram code: 891024",
        "receivedAt": "2026-10-06T08:02:15.000Z"
      }
    ]
  }
}

POST/api/otp/activations/{id}/retry

API Thuê số & Nhận mã

Yêu Cầu Nhận Mã Tiếp Theo (Next OTP)

Chuyển đơn về trạng thái chờ mã mới cho dịch vụ gửi nhiều lần SMS trong thời gian thuê còn hiệu lực.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string	Required	Mã đơn nội bộ (orderCode)

Phản hồi mẫu (Response)

{
  "success": true,
  "status": "WAIT_CODE",
  "message": "Đã sẵn sàng nhận mã tiếp theo."
}

POST/api/otp/activations/{id}/replace

API Thuê số & Nhận mã

Đổi Sang Số Điện Thoại Mới (Sau 2 phút)

Đổi sang một số điện thoại mới miễn phí nếu số hiện tại không nhận được tin nhắn sau 2 phút chờ.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string	Required	Mã đơn nội bộ (orderCode)

Phản hồi mẫu (Response)

{
  "success": true,
  "data": {
    "id": "ACT9M2K8",
    "orderCode": "ACT9M2K8",
    "phone": "84912345678",
    "status": "WAIT_CODE"
  }
}

POST/api/otp/activations/{id}/cancel

API Thuê số & Nhận mã

Hủy Số & Hoàn 100% Tiền Vào Ví

Hủy đơn thuê số khi chưa nhận được mã OTP bằng orderCode. Toàn bộ tiền sẽ tự động hoàn trả vào ví ngay lập tức.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string	Required	Mã đơn nội bộ (orderCode)

Phản hồi mẫu (Response)

{
  "success": true,
  "status": "REFUNDED",
  "message": "Hủy kích hoạt thành công, số dư đã được hoàn lại.",
  "balanceAfter": 250000
}

POST/api/otp/activations/{id}/finish

API Thuê số & Nhận mã

Đánh Dấu Hoàn Tất Đơn Thuê Số

Đánh dấu hoàn thành đơn thuê số khi bạn đã nhận đủ mã OTP cần thiết, giải phóng số và kết thúc đơn.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string	Required	Mã đơn nội bộ (orderCode)

Phản hồi mẫu (Response)

{
  "success": true,
  "message": "Đơn hàng đã được đánh dấu hoàn tất thành công."
}

GET/api/otp/activations/{id}/reactivate/options

API Thuê số & Nhận mã

Kiểm Tra Khả Năng Mua Lại Số Cũ (Reactivate Options)

Kiểm tra xem số điện thoại của đơn cũ đã hoàn tất còn khả dụng trên hệ thống nhà cung cấp để nhận lại mã OTP mới hay không.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string	Required	Mã đơn nội bộ (orderCode) của đơn cũ

Phản hồi mẫu (Response)

{
  "success": true,
  "available": true,
  "phone": "84931002233",
  "service": "tg",
  "durations": [
    {
      "duration": 20,
      "price": {
        "sellingVnd": 4000,
        "sellingUsd": 0.15
      }
    }
  ]
}

POST/api/otp/activations/{id}/reactivate

API Thuê số & Nhận mã

Tái Kích Hoạt Số Cũ Đã Từng Thuê (Reactivate Number)

Tiến hành mua lại đúng số điện thoại của đơn cũ để nhận mã xác minh mới. Hệ thống sẽ tạo đơn kích hoạt mới cho số này.

Headers

x-api-key	your_api_key_here	API Key
Content-Type	application/json	application/json

Tham số (Parameters)

Field	Type	Required	Description
id	string	Required	Mã đơn nội bộ (orderCode) của đơn cũ (Path parameter)
duration	number	Optional	Thời gian kích hoạt lại tính bằng phút (mặc định: 20)

Request Body (JSON)

{
  "duration": 20
}

Phản hồi mẫu (Response)

{
  "success": true,
  "message": "Kích hoạt lại số thành công",
  "activation": {
    "id": "ACT7N1X2",
    "orderCode": "ACT7N1X2",
    "phone": "84931002233",
    "service": "tg",
    "status": "WAIT_CODE",
    "price": {
      "sellingVnd": 4000,
      "sellingUsd": 0.15
    },
    "createdAt": "2026-10-06T09:00:00.000Z"
  }
}

GET/api/otp/durations

API Thuê số & Nhận mã

Bảng Gói Thời Lượng Thuê Số Dài Hạn

Tra cứu các gói thời gian thuê số theo giờ và theo ngày (4 giờ, 1 ngày / 24h, 3 ngày / 72h, 7 ngày / 1 tuần...). Bao gồm số lượng số có sẵn và đơn giá chiết khấu theo VIP.

Tham số (Parameters)

Field	Type	Required	Description
service	string	Required	Mã dịch vụ (ví dụ: tg, wa, fb...)
country	number \| string	Required	ID quốc gia (ví dụ: 10, 1, 6...)
verificationType	string	Optional	'sms' (mặc định) hoặc 'call'

Phản hồi mẫu (Response)

{
  "success": true,
  "tier": 0,
  "data": [
    {
      "id": "4h",
      "durationMinutes": 240,
      "durationHours": 4,
      "label": "4 giờ",
      "type": "rent",
      "count": 1500,
      "prices": {
        "sellingUsd": 0.45,
        "sellingVnd": 12000,
        "tier": 0,
        "discountPercent": 0
      }
    },
    {
      "id": "24h",
      "durationMinutes": 1440,
      "durationHours": 24,
      "label": "1 ngày (24h)",
      "type": "rent",
      "count": 1200,
      "prices": {
        "sellingUsd": 0.8,
        "sellingVnd": 21000,
        "tier": 0,
        "discountPercent": 0
      }
    },
    {
      "id": "72h",
      "durationMinutes": 4320,
      "durationHours": 72,
      "label": "3 ngày (72h)",
      "type": "rent",
      "count": 800,
      "prices": {
        "sellingUsd": 2.2,
        "sellingVnd": 58000,
        "tier": 0,
        "discountPercent": 0
      }
    },
    {
      "id": "168h",
      "durationMinutes": 10080,
      "durationHours": 168,
      "label": "7 ngày (1 tuần)",
      "type": "rent",
      "count": 500,
      "prices": {
        "sellingUsd": 4.5,
        "sellingVnd": 118000,
        "tier": 0,
        "discountPercent": 0
      }
    }
  ]
}

POST/api/otp/buy

API Thuê số & Nhận mã

Thuê Số Điện Thoại Dài Hạn (Theo Giờ / Ngày)

Tạo đơn thuê số giữ số dài hạn theo thời gian chỉ định (duration tính theo phút, ví dụ: 1440 = 24h). Trong suốt thời gian thuê, bạn có thể nhận không giới hạn mã OTP từ dịch vụ.

Headers

x-api-key	your_api_key_here	API Key
Content-Type	application/json	application/json

Tham số (Parameters)

Field	Type	Required	Description
service	string	Required	Mã dịch vụ (ví dụ: tg, wa, fb...)
country	number \| string	Required	ID quốc gia (ví dụ: 10, 1, 6...)
duration	number	Required	Thời gian thuê tính bằng phút (ví dụ: 240 = 4 giờ, 1440 = 1 ngày, 4320 = 3 ngày, 10080 = 7 ngày)
verificationType	string	Optional	'sms' (mặc định) hoặc 'call'
operator	string	Optional	Nhà mạng mong muốn (mặc định: 'any')

Request Body (JSON)

{
  "service": "tg",
  "country": 10,
  "duration": 1440,
  "verificationType": "sms",
  "operator": "any"
}

Phản hồi mẫu (Response)

{
  "success": true,
  "tier": 0,
  "balanceAfter": 229000,
  "data": [
    {
      "id": "ACT9L0P1",
      "orderCode": "ACT9L0P1",
      "phone": "84988776655",
      "service": "tg",
      "country": "10",
      "status": "WAIT_CODE",
      "price": {
        "sellingUsd": 0.8,
        "sellingVnd": 21000,
        "tier": 0,
        "discountPercent": 0
      },
      "createdAt": "2026-10-06T08:00:00.000Z",
      "expiredAt": "2026-10-07T08:00:00.000Z"
    }
  ]
}

GET/api/otp/activations/{id}/prolong/options

API Thuê số & Nhận mã

Tra Cứu Gói Gia Hạn Cho Số Đang Thuê

Xem danh sách các gói thời gian gia hạn có thể mua thêm cho số điện thoại đang thuê trước khi hết hạn.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string	Required	Mã đơn nội bộ (orderCode) của đơn thuê dài hạn

Phản hồi mẫu (Response)

{
  "success": true,
  "orderCode": "ACT9L0P1",
  "phone": "84988776655",
  "currentExpiresAt": "2026-10-07T08:00:00.000Z",
  "options": [
    {
      "duration": 1440,
      "label": "Gia hạn thêm 1 ngày (24h)",
      "prices": {
        "sellingVnd": 21000,
        "sellingUsd": 0.8
      }
    },
    {
      "duration": 4320,
      "label": "Gia hạn thêm 3 ngày (72h)",
      "prices": {
        "sellingVnd": 58000,
        "sellingUsd": 2.2
      }
    }
  ]
}

POST/api/otp/activations/{id}/prolong

API Thuê số & Nhận mã

Thực Hiện Gia Hạn Số Điện Thoại Đang Thuê

Gia hạn thêm thời gian sử dụng cho số điện thoại đang thuê. Thời gian hết hạn mới (expiredAt) sẽ được cộng dồn tiếp.

Headers

x-api-key	your_api_key_here	API Key
Content-Type	application/json	application/json

Tham số (Parameters)

Field	Type	Required	Description
id	string	Required	Mã đơn nội bộ (orderCode) của đơn thuê dài hạn (Path parameter)
duration	number	Required	Thời gian gia hạn thêm tính theo phút (ví dụ: 1440 là 24h, 4320 là 3 ngày)

Request Body (JSON)

{
  "duration": 1440
}

Phản hồi mẫu (Response)

{
  "success": true,
  "message": "Gia hạn thời gian thuê số thành công",
  "data": {
    "id": "ACT9L0P1",
    "phone": "84988776655",
    "prolongMinutes": 1440,
    "newExpiredAt": "2026-10-08T08:00:00.000Z",
    "price": {
      "sellingVnd": 21000,
      "sellingUsd": 0.8
    },
    "balanceAfter": 208000
  }
}

GET/api/otp/activations/{id}/prolong/history

API Thuê số & Nhận mã

Lịch Sử Các Lần Gia Hạn Của Số

Tra cứu danh sách các lần đã gia hạn thành công của một số điện thoại thuê dài hạn.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string	Required	Mã đơn nội bộ (orderCode)

Phản hồi mẫu (Response)

{
  "success": true,
  "data": [
    {
      "id": "prolong_1",
      "duration": 1440,
      "priceVnd": 21000,
      "prolongedAt": "2026-10-06T12:00:00.000Z",
      "newExpiredAt": "2026-10-08T08:00:00.000Z"
    }
  ]
}

API thuê email

5 endpoints

GET/api/email-otp/offers

API thuê email

Danh Sách Domain Email & Bảng Giá

Lấy các đuôi tên miền email (gmail.com, outlook.com, mail.com,...) có sẵn cho website cần nhận mã OTP.

Tham số (Parameters)

Field	Type	Required	Description
site	string	Required	Tên website cần nhận thư (ví dụ: telegram.com, openai.com, google.com...)

Phản hồi mẫu (Response)

{
  "success": true,
  "site": "telegram.com",
  "tier": 0,
  "data": [
    {
      "domain": "email.com",
      "count": 617667,
      "price": {
        "sellingVnd": 200,
        "sellingUsd": 0.0075
      }
    },
    {
      "domain": "gmail.com",
      "count": 125000,
      "price": {
        "sellingVnd": 1500,
        "sellingUsd": 0.057
      }
    }
  ]
}

POST/api/email-otp/buy

API thuê email

Thuê Email Nhận OTP

Thuê một hòm thư email tạm thời để nhận mã xác nhận kích hoạt tài khoản. Hỗ trợ đặt mức giá trần maxPrice.

Headers

x-api-key	your_api_key_here	API Key
Content-Type	application/json	application/json

Request Body (JSON)

{
  "site": "telegram.com",
  "domain": "email.com",
  "maxPrice": 500
}

Phản hồi mẫu (Response)

{
  "success": true,
  "data": {
    "id": 774819,
    "email": "[email protected]",
    "status": "WAIT",
    "price": {
      "sellingVnd": 200,
      "sellingUsd": 0.0075,
      "tier": 0
    },
    "createdAt": "2026-10-06T08:30:00.000Z"
  }
}

GET/api/email-otp/activations/{id}

API thuê email

Lấy Mã OTP & Nội Dung Toàn Văn Email

Truy vấn tình trạng hòm thư email đã thuê. Khi thư đến, mã OTP (value) và toàn văn email (message) sẽ được trả về tức thì.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string \| number	Required	ID đơn thuê email (ví dụ: 774819)

Phản hồi mẫu (Response)

{
  "success": true,
  "data": {
    "id": 774819,
    "email": "[email protected]",
    "status": "SUCCESS",
    "value": "449102",
    "message": "Telegram code: 449102. You can also tap this link to log in...",
    "createdAt": "2026-10-06T08:30:00.000Z"
  }
}

POST/api/email-otp/activations/{id}/cancel

API thuê email

Hủy Email Chưa Nhận Mã & Hoàn 100% Tiền

Hủy đơn thuê email nếu chưa nhận được thư và nhận lại 100% tiền vào số dư ví ngay lập tức.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string \| number	Required	ID đơn thuê email

Phản hồi mẫu (Response)

{
  "success": true,
  "message": "Huỷ đơn thuê email thành công, số dư đã được hoàn lại.",
  "balanceAfter": 250000
}

POST/api/email-otp/activations/{id}/reorder

API thuê email

Thuê Lại / Gia Hạn Hòm Thư Email Đã Từng Dùng

Tiếp tục thuê lại chính xác địa chỉ email đã từng dùng trước đó để nhận thêm mã xác nhận cho cùng dịch vụ.

Headers

x-api-key

your_api_key_here

API Key

Tham số (Parameters)

Field	Type	Required	Description
id	string \| number	Required	ID đơn thuê email trước đó

Phản hồi mẫu (Response)

{
  "success": true,
  "message": "Gia hạn / Thuê lại email thành công",
  "data": {
    "id": 774825,
    "site": "telegram.com",
    "domain": "email.com",
    "email": "[email protected]",
    "status": "WAIT",
    "price": {
      "sellingVnd": 200,
      "sellingUsd": 0.0075,
      "tier": 0
    },
    "createdAt": "2026-10-06T09:15:00.000Z"
  }
}

API mua email

3 endpoints

GET/api/mail/products

API mua email

Mail: Danh Sách Sản Phẩm

API hệ thống lấy danh sách sản phẩm mail. Provider được xử lý nội bộ, client chỉ dùng API key của website.

Headers

x-api-key

your_website_api_key

API key của website

Tham số (Parameters)

Field	Type	Required	Description
status	1	Optional	Chỉ lấy sản phẩm hoạt động

Phản hồi mẫu (Response)

{
  "success": true,
  "data": [
    {
      "slug": "email-gmail",
      "name": "Gmail Fresh",
      "price": 15000,
      "stock": 50
    }
  ]
}

POST/api/mail/buy

API mua email

Mail: Mua Email

Mua mail qua API hệ thống. Số dư tài khoản website được trừ tự động.

Headers

x-api-key

your_website_api_key

API key của website

Tham số (Parameters)

Field	Type	Required	Description
product_slug	string	Required	Slug sản phẩm
quantity	1..10000	Required	Số lượng mail

Request Body (JSON)

{
  "product_slug": "email-gmail",
  "quantity": 1
}

Phản hồi mẫu (Response)

{
  "success": true,
  "data": {
    "order_code": "ORD-20251218-ABC123",
    "quantity": 1,
    "emails": [
      {
        "email": "[email protected]"
      }
    ]
  }
}

POST/api/mail/read

API mua email

Mail: Đọc Hộp Thư Outlook

Đọc inbox của mail đã mua qua API hệ thống. Provider và credential được xử lý nội bộ.

Headers

x-api-key

your_website_api_key

API key của website

Request Body (JSON)

{
  "hotmail": "[email protected]",
  "folder": "Inbox",
  "limit": 10,
  "unread_only": false
}

Phản hồi mẫu (Response)

{
  "success": true,
  "data": {
    "total": 1,
    "emails": [
      {
        "subject": "Your verification code",
        "sender_email": "[email protected]",
        "body_preview": "Your code is 312578..."
      }
    ]
  }
}

API proxy

4 endpoints

GET/api/proxy/download

API proxy

Tải Danh Sách Proxy

Tải proxy thuộc đơn hàng của bạn. Đăng nhập phiên Clerk hiện được yêu cầu.

Tham số (Parameters)

Field	Type	Required	Description
order_id	string	Required	ID hoặc mã đơn proxy
mode	direct \| backbone	Optional	Kiểu proxy, mặc định direct
format	string	Optional	ip:port:user:pass, user:pass@ip:port hoặc ip:port

Phản hồi mẫu (Response)

1.2.3.4:8080:username:password

GET/api/proxy/countries

API proxy

Danh Sách Quốc Gia Proxy

Lấy quốc gia khả dụng để mua proxy, kèm số IP còn lại nếu nhà cung cấp trả về.

Phản hồi mẫu (Response)

{
  "success": true,
  "data": [
    {
      "code": "US",
      "name": "United States",
      "proxyCount": 1200
    }
  ]
}

GET/api/proxy/prices?proxy_type=shared&proxy_count=10&countries=US,SG

API proxy

Kiểm Tra Giá Proxy

Tính giá bán theo loại proxy, số lượng, quốc gia, băng thông và cấp VIP. `countries` là danh sách mã ISO 2 ký tự, phân cách bằng dấu phẩy.

Headers

x-api-key

your_api_key_here

Không bắt buộc, dùng để áp dụng giá VIP

Tham số (Parameters)

Field	Type	Required	Description
proxy_type	string	Required	Loại proxy, ví dụ `shared` hoặc `dedicated`
proxy_count	integer	Required	Số IP, từ 1 đến 10.000
countries	string	Optional	Mã quốc gia phân cách bằng dấu phẩy
bandwidth_limit	integer	Optional	Giới hạn băng thông
term	`monthly` \| `yearly`	Optional	Chu kỳ thanh toán, mặc định `monthly`

Phản hồi mẫu (Response)

{
  "success": true,
  "tier": 0,
  "data": {
    "sellingVnd": 125000,
    "sellingUsd": 5,
    "proxyCount": 10
  }
}

POST/api/proxy/buy

API proxy

Mua Proxy

Mua gói Proxy và tự động trừ tiền từ số dư ví API Key.

Headers

x-api-key

your_api_key_here

API Key tài khoản

Request Body (JSON)

{
  "proxyType": "shared",
  "proxyCount": 10,
  "bandwidthLimit": 100,
  "countries": [
    "US",
    "SG"
  ]
}

Phản hồi mẫu (Response)

{
  "success": true,
  "data": {
    "orderCode": "PRX-ABC123",
    "proxyCount": 10,
    "balanceAfter": 750000
  }
}

API chuẩn SMS-Activate

18 endpoints

GET/stubs/handler_api.php?action=getBalance

API chuẩn SMS-Activate

SMS-Activate: Truy Vấn Số Dư Tài Khoản (getBalance)

Trả về số dư ví khả dụng quy đổi sang USD dưới dạng chuỗi thuần ACCESS_BALANCE:<amount>. Tương thích hoàn toàn với tất cả phần mềm tích hợp SMS-Activate.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API của tài khoản trên hệ thống
action	string	Required	Tên hành động: getBalance

Phản hồi mẫu (Response)

ACCESS_BALANCE:25.50

GET/stubs/handler_api.php?action=getNumber

API chuẩn SMS-Activate

SMS-Activate: Thuê Số Nhận Mã OTP (getNumber - Text)

Yêu cầu cấp 1 số điện thoại mới cho dịch vụ và quốc gia chỉ định. Trả về chuỗi thuần ACCESS_NUMBER:<activation_id>:<phone>. Tự động trừ tiền ví theo biểu giá và chiết khấu VIP của hệ thống.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getNumber
service	string	Required	Mã dịch vụ (ví dụ: tg, wa, ig, go, fb, vi, lf...)
country	number	Required	Mã quốc gia (ví dụ: 10 - Vietnam, 6 - Indonesia, 2 - Kazakhstan, 12 - USA...)
operator	string	Optional	Nhà mạng mong muốn (ví dụ: viettel, mobifone, vinaphone)
maxPrice	number	Optional	Mức giá tối đa bạn chấp nhận trả (USD). Nếu giá bán thực tế cao hơn sẽ tự động hủy và trả NO_NUMBERS.

Phản hồi mẫu (Response)

ACCESS_NUMBER:819284712:84981234567

GET/stubs/handler_api.php?action=getNumberV2

API chuẩn SMS-Activate

SMS-Activate: Thuê Số Nhận Mã (getNumberV2 - JSON)

Cấp số mới và trả về đối tượng JSON chi tiết gồm ID đơn, số điện thoại, giá tiền (USD), mã nước, thời gian hết hạn và cờ canGetAnotherSms.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getNumberV2
service	string	Required	Mã dịch vụ (tg, wa, fb, go...)
country	number	Required	Mã quốc gia

Phản hồi mẫu (Response)

{
  "activationId": "819284712",
  "phoneNumber": "84981234567",
  "activationCost": 0.45,
  "currency": 840,
  "countryCode": 10,
  "countryPhoneCode": 84,
  "canGetAnotherSms": true,
  "activationTime": "2026-04-01T10:00:00.000Z",
  "activationEndTime": "2026-04-01T10:20:00.000Z",
  "activationOperator": "any",
  "verificationType": "sms",
  "subtype": 1,
  "serviceCode": "tg",
  "status": 4
}

GET/stubs/handler_api.php?action=setStatus

API chuẩn SMS-Activate

SMS-Activate: Cập Nhật Trạng Thái Đơn (setStatus)

Điều khiển vòng đời kích hoạt: status=1 (ACCESS_READY: sẵn sàng), status=3 (ACCESS_RETRY_GET: yêu cầu mã tiếp theo), status=6 (ACCESS_ACTIVATION: hoàn tất đơn), status=8 (ACCESS_CANCEL: hủy và hoàn tiền 100%).

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: setStatus
id	string	Required	Mã kích hoạt activationId hoặc mã đơn orderCode
status	number	Required	1 (sẵn sàng), 3 (yêu cầu mã mới), 6 (hoàn tất), 8 (hủy & hoàn tiền)

Phản hồi mẫu (Response)

ACCESS_RETRY_GET

GET/stubs/handler_api.php?action=getStatus

API chuẩn SMS-Activate

SMS-Activate: Lấy Trạng Thái & Mã OTP (getStatus - Text)

Kiểm tra trạng thái đơn. Nếu đã có tin nhắn trả về STATUS_OK:<code>. Đang chờ tin nhắn trả về STATUS_WAIT_CODE. Đã hủy trả về STATUS_CANCEL. Tự động đồng bộ SMS mới nhất.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getStatus
id	string	Required	Mã kích hoạt activationId hoặc orderCode

Phản hồi mẫu (Response)

STATUS_OK:482910

GET/stubs/handler_api.php?action=getStatusV2

API chuẩn SMS-Activate

SMS-Activate: Lấy Trạng Thái & OTP Chi Tiết (getStatusV2 - JSON)

Trả về dữ liệu JSON chứa mã OTP, số điện thoại gửi đến, nội dung tin nhắn SMS đầy đủ và thời gian nhận.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getStatusV2
id	string	Required	Mã kích hoạt activationId

Phản hồi mẫu (Response)

{
  "verificationType": "sms",
  "data": {
    "id": "3416693217",
    "phoneFrom": "Telegram",
    "code": "482910",
    "text": "Telegram code 482910",
    "service": "tg",
    "date": "2026-04-01T10:02:15.000Z",
    "type": "sms"
  }
}

GET/stubs/handler_api.php?action=getActiveActivations

API chuẩn SMS-Activate

SMS-Activate: Danh Sách Đơn Đang Hoạt Động (getActiveActivations)

Lấy toàn bộ các đơn đang chờ nhận mã (WAIT_CODE) hoặc đã nhận được mã (OK) của tài khoản bạn theo cấu trúc chuẩn SMS-Activate.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getActiveActivations

Phản hồi mẫu (Response)

{
  "status": "success",
  "data": [
    {
      "activationId": "819284715",
      "serviceCode": "tg",
      "phoneNumber": "84981234567",
      "activationCost": 0.45,
      "activationStatus": "4",
      "smsCode": "482910",
      "smsText": "Telegram code 482910",
      "activationTime": "2026-04-01 10:00:00",
      "countryCode": "10",
      "canGetAnotherSms": "1",
      "currency": 840,
      "verificationType": "sms",
      "subtype": 1
    }
  ]
}

GET/stubs/handler_api.php?action=getHistory

API chuẩn SMS-Activate

SMS-Activate: Lịch Sử Kích Hoạt (getHistory)

Truy vấn danh sách lịch sử các đơn thuê số gần nhất kèm thông tin tin nhắn OTP, giá bán và trạng thái.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getHistory

Phản hồi mẫu (Response)

[
  {
    "id": "819284715",
    "date": "2026-04-01 10:00:00",
    "phone": "84981234567",
    "sms": {
      "code": "482910",
      "text": "Telegram code 482910",
      "date": "2026-04-01T10:02:15.000Z"
    },
    "cost": 0.45,
    "status": "OK",
    "currency": 840
  }
]

GET/stubs/handler_api.php?action=getCountries

API chuẩn SMS-Activate

SMS-Activate: Danh Sách Quốc Gia (getCountries)

Trả về toàn bộ danh sách quốc gia khả dụng kèm ID, tên tiếng Nga, Anh, Trung. Tự động ẩn các quốc gia bị tắt trong cấu hình hệ thống.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getCountries

Phản hồi mẫu (Response)

[
  {
    "id": 10,
    "rus": "Вьетнам",
    "eng": "Vietnam",
    "chn": "越南",
    "visible": 1,
    "retry": 1
  },
  {
    "id": 6,
    "rus": "Индонезия",
    "eng": "Indonesia",
    "chn": "印度尼西亚",
    "visible": 1,
    "retry": 1
  },
  {
    "id": 2,
    "rus": "Казахстан",
    "eng": "Kazakhstan",
    "chn": "哈萨克斯坦",
    "visible": 1,
    "retry": 1
  }
]

GET/stubs/handler_api.php?action=getServicesList

API chuẩn SMS-Activate

SMS-Activate: Danh Sách Dịch Vụ (getServicesList)

Truy vấn danh mục mã dịch vụ (code) và tên dịch vụ tương ứng (name). Tự động loại bỏ các dịch vụ bị tắt (DISABLE_SERVICES).

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getServicesList
country	number	Optional	Mã quốc gia lọc dịch vụ (tùy chọn)

Phản hồi mẫu (Response)

{
  "status": "success",
  "services": [
    {
      "code": "tg",
      "name": "Telegram"
    },
    {
      "code": "wa",
      "name": "WhatsApp"
    },
    {
      "code": "go",
      "name": "Google, YouTube, Gmail"
    },
    {
      "code": "fb",
      "name": "Facebook"
    },
    {
      "code": "ig",
      "name": "Instagram"
    }
  ]
}

GET/stubs/handler_api.php?action=getOperators

API chuẩn SMS-Activate

SMS-Activate: Danh Sách Nhà Mạng (getOperators)

Lấy danh sách các nhà mạng viễn thông hỗ trợ cho từng quốc gia chỉ định.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getOperators
country	number	Required	Mã quốc gia (ví dụ: 10 cho Vietnam)

Phản hồi mẫu (Response)

{
  "status": "success",
  "countryOperators": {
    "10": [
      "viettel",
      "vinaphone",
      "mobifone",
      "vietnamobile",
      "itelecom"
    ]
  }
}

GET/stubs/handler_api.php?action=getPrices

API chuẩn SMS-Activate

SMS-Activate: Ma Trận Bảng Giá & Số Lượng Tồn (getPrices)

Trả về bảng giá bán và số lượng số khả dụng theo từng quốc gia và dịch vụ. Giá bán (cost) đã tự động tính toán theo tỷ lệ lợi nhuận và chiết khấu VIP Loyalty Tier của tài khoản bạn.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getPrices
country	number	Optional	Mã quốc gia cần xem giá (tùy chọn)
service	string	Optional	Mã dịch vụ cần xem giá (tùy chọn)

Phản hồi mẫu (Response)

{
  "6": {
    "tg": {
      "cost": 0.38,
      "count": 5400
    },
    "wa": {
      "cost": 0.42,
      "count": 2100
    }
  },
  "10": {
    "tg": {
      "cost": 0.45,
      "count": 1250
    },
    "wa": {
      "cost": 0.55,
      "count": 820
    },
    "go": {
      "cost": 0.35,
      "count": 3400
    }
  }
}

GET/stubs/handler_api.php?action=getTopCountriesByService

API chuẩn SMS-Activate

SMS-Activate: Top Quốc Gia Có Nhiều Số Nhất (getTopCountriesByService)

Truy vấn danh sách các quốc gia có lượng số dồi dào nhất và giá bán tối ưu nhất cho một dịch vụ cụ thể.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getTopCountriesByService
service	string	Required	Mã dịch vụ (ví dụ: tg)

Phản hồi mẫu (Response)

[
  {
    "country": 6,
    "count": 5477,
    "price": 0.38,
    "retail_price": 0.38
  },
  {
    "country": 10,
    "count": 1250,
    "price": 0.45,
    "retail_price": 0.45
  },
  {
    "country": 2,
    "count": 980,
    "price": 0.52,
    "retail_price": 0.52
  }
]

GET/stubs/handler_api.php?action=getAllSms

API chuẩn SMS-Activate

SMS-Activate: Lấy Toàn Bộ Tin Nhắn Của Đơn (getAllSms)

Lấy mảng toàn bộ các tin nhắn SMS và cuộc gọi xác minh FlashCall đã gửi đến số điện thoại trong suốt thời gian kích hoạt.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getAllSms
id	string	Required	Mã kích hoạt activationId

Phản hồi mẫu (Response)

{
  "data": [
    {
      "id": "3416693217",
      "phoneFrom": "Telegram",
      "code": "123456",
      "text": "Telegram code 123456",
      "service": "tg",
      "date": "2026-04-01T10:02:15.000Z",
      "type": "sms"
    },
    {
      "id": "3416693218",
      "phoneFrom": "Telegram",
      "code": "654321",
      "text": "Telegram code 654321",
      "service": "tg",
      "date": "2026-04-01T10:05:30.000Z",
      "type": "sms"
    }
  ]
}

GET/stubs/handler_api.php?action=serviceCountRent

API chuẩn SMS-Activate

SMS-Activate: Bảng Giá Thuê Số Dài Hạn (serviceCountRent)

Tra cứu các gói thời gian thuê dài hạn (2h, 4h, 24h, 72h, 168h...) kèm số lượng tồn và giá chiết khấu VIP của hệ thống.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: serviceCountRent
country	number	Optional	Mã quốc gia cần kiểm tra

Phản hồi mẫu (Response)

{
  "10": {
    "4": {
      "count": 850,
      "price": 0.85,
      "retail_price": 0.85
    },
    "24": {
      "count": 620,
      "price": 1.5,
      "retail_price": 1.5
    },
    "72": {
      "count": 310,
      "price": 3.2,
      "retail_price": 3.2
    },
    "168": {
      "count": 180,
      "price": 6,
      "retail_price": 6
    }
  }
}

GET/stubs/handler_api.php?action=getRentNumber

API chuẩn SMS-Activate

SMS-Activate: Thuê Số Dài Hạn (getRentNumber)

Thuê số theo chu kỳ giờ hoặc ngày (duration: 4, 24, 72, 168...). Trong suốt chu kỳ, số có thể nhận không giới hạn nhiều mã OTP liên tục.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: getRentNumber
service	string	Required	Mã dịch vụ (ví dụ: tg)
country	number	Required	Mã quốc gia
duration	number	Required	Thời gian thuê tính bằng giờ (ví dụ: 24 cho 1 ngày, 168 cho 7 ngày)

Phản hồi mẫu (Response)

{
  "activationId": "819284720",
  "phoneNumber": "84985556677",
  "activationCost": 1.5,
  "currency": 840,
  "countryCode": 10,
  "countryPhoneCode": 84,
  "canGetAnotherSms": true,
  "activationTime": "2026-04-01T10:00:00.000Z",
  "activationEndTime": "2026-04-02T10:00:00.000Z",
  "activationOperator": "any",
  "verificationType": "sms",
  "subtype": 2,
  "serviceCode": "tg",
  "status": 4
}

POST/stubs/handler_api.php?action=prolong

API chuẩn SMS-Activate

SMS-Activate: Gia Hạn Số Thuê Dài Hạn (prolong)

Gia hạn thêm thời gian thuê cho số đang hoạt động trước khi hết hạn. Phí gia hạn được tự động trừ từ ví tài khoản.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: prolong
id	string	Required	Mã kích hoạt activationId
duration	number	Required	Số giờ muốn gia hạn thêm (ví dụ: 24)

Phản hồi mẫu (Response)

{
  "activationId": "819284725",
  "phoneNumber": "84985556677",
  "activationCost": 1.5,
  "currency": 840,
  "countryCode": 10,
  "countryPhoneCode": 84,
  "canGetAnotherSms": true,
  "activationTime": "2026-04-01T10:00:00.000Z",
  "activationEndTime": "2026-04-03T10:00:00.000Z",
  "activationOperator": "any",
  "verificationType": "sms",
  "subtype": 2,
  "serviceCode": "tg",
  "status": 4
}

POST/stubs/handler_api.php?action=reactivate

API chuẩn SMS-Activate

SMS-Activate: Kích Hoạt Lại Số Cũ (reactivate)

Thuê lại chính số điện thoại của đơn cũ đã hoàn tất trước đó để nhận thêm mã OTP mới nếu số vẫn còn trong kho của nhà mạng.

Tham số (Parameters)

Field	Type	Required	Description
api_key	string	Required	Khóa API tài khoản
action	string	Required	Tên hành động: reactivate
id	string	Required	Mã kích hoạt activationId của đơn cũ

Phản hồi mẫu (Response)

{
  "activationId": "819284730",
  "phoneNumber": "84985556677",
  "activationCost": 0.45,
  "currency": 840,
  "countryCode": 10,
  "countryPhoneCode": 84,
  "canGetAnotherSms": true,
  "activationTime": "2026-04-01T15:00:00.000Z",
  "activationEndTime": "2026-04-01T15:20:00.000Z",
  "activationOperator": "any",
  "verificationType": "sms",
  "subtype": 1,
  "serviceCode": "tg",
  "status": 4
}

Bảng Mã Trạng Thái Đơn Hàng

Quy ước ý nghĩa các trạng thái đơn hàng OTP & Email

WAIT_CODEĐang chờ nhà mạng / dịch vụ gửi mã OTP về số điện thoại hoặc email

OK / SUCCESSNhận mã OTP thành công, có kèm mã code và tin nhắn toàn văn

REFUNDEDĐơn hàng đã được huỷ bỏ và hoàn lại 100% tiền vào số dư ví

FINISHEDĐơn hàng đã sử dụng xong và hoàn tất chu kỳ thuê

Mã Phản Hồi HTTP & Xử Lý Lỗi

JSON format: { "success": false, "error": "..." }

200 OKYêu cầu thành công, dữ liệu được trả về trong trường data.

400 Bad RequestTham số không hợp lệ, thiếu trường bắt buộc hoặc dịch vụ tạm thời hết số.

401 UnauthorizedThiếu API Key hoặc API Key không hợp lệ. Vui lòng kiểm tra header x-api-key.

402 Payment RequiredSố dư trong ví không đủ để thanh toán đơn hàng. Vui lòng nạp thêm tiền.