v1.0OpenAPI 3.2.0SMS-Activate Compatible

SMS 接码工作协议（完全兼容 SMS-Activate）

通过 REST API 将 SMS OTP 短信接码、FlashCall 来电认证与临时邮箱接码无缝集成至 Telegram 机器人、脚本工具与网站系统中。

Software Connection Guide

选择任何在接码服务列表中包含 SMS-Activate 的软件或脚本。

在软件设置中选择 SMS-Activate 作为接收短信的服务。

将软件设置中的服务器地址从 https://api.sms-activate.ae 替换为 https://hero-sms.com/stubs/handler_api.php。

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

输入个人资料中的 API Key（在网站账号中心申请或复制）。

如遇到任何困难，请联系技术支持，我们将竭诚为您解决。

API 服务器

https://hero-sms.com/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

Cursor / Windsurf / Claude Code 集成提示词

下载 openapi.json

专为 AI 编程助手（Cursor、Windsurf、Claude Code）优化的零摩擦一键集成 Prompt。

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

3 endpoints

GET/api/user/balance

通用 API

查询钱包余额与账户信息

查询账户可用钱包余额（越南盾与美元）及关联邮箱。

请求头 (Headers)

x-api-key

your_api_key_here

您的账户 API Key

响应示例 (Response)

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

GET/api/otp/loyalty

通用 API

VIP 等级与专属折扣率

获取账户当前 VIP 级别、接码自动享受的折扣率、近 7 日消费总额及升级所需金额。

请求头 (Headers)

x-api-key

your_api_key_here

您的账户 API Key

响应示例 (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

VIP 等级与折扣率标准表（公开）

查询所有 VIP 等级及其对应的折扣百分比标准，无需 API 密钥。

响应示例 (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

18 endpoints

GET/api/otp/countries

购买号码与接码 API

支持的国家列表

获取所有可用国家列表，包括国家 ID、国旗及国际电话区号。

响应示例 (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

短信接码服务与应用列表

获取支持接码的应用列表（Telegram、Google、TikTok、Facebook、WhatsApp 等），包含可用号码数量与底价。

请求参数 (Parameters)

Field	Type	Required	Description
country	number \| string	Optional	按国家 ID 筛选（10 为越南，1 为美国，6 为印度尼西亚）

响应示例 (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

详细价格与订单簿

查询指定国家某服务的详细价格，支持查看短信与语音来电（FlashCall）的底价订单簿。

请求参数 (Parameters)

Field	Type	Required	Description
service	string	Required	服务代码（例如：tg, go, fb, wa, lf, dr...）
country	number \| string	Optional	国家 ID（例如：10, 1, 6...）
verificationType	string	Optional	'sms'（默认）或 'call'（语音来电认证）

响应示例 (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

支持的电信运营商列表

获取指定国家和服务可用的电信运营商列表。

请求参数 (Parameters)

Field	Type	Required	Description
country	number \| string	Optional	国家 ID（例如：10 代表越南）
service	string	Optional	服务代码（例如：tg, go, fb...）

响应示例 (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

短期租号接收验证码 (SMS / FlashCall)

创建短期接码订单（约20分钟）。支持指定运营商、最高接受价格及批量订购。返回系统 orderCode。

请求头 (Headers)

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

请求参数 (Parameters)

Field	Type	Required	Description
service	string	Required	服务代码（例如：tg, go, fb, wa, lf...）
country	number \| string	Required	国家 ID（例如：10 代表越南，1 代表美国）
verificationType	string	Optional	'sms'（默认）或 'call'（FlashCall 语音来电）
operator	string	Optional	指定运营商（例如：'viettel', 'mobifone', 或 'any' 默认最快）
maxPrice	number	Optional	最高出价上限（越南盾），超出则不购买
amount	number	Optional	批量租号数量（1 到 10，默认：1）

请求体 (JSON Body)

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

响应示例 (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

当前进行中订单与历史记录

获取正在等待验证码的有效订单列表或完整的历史接码记录。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
status	string	Optional	'ACTIVE'（仅查接码中）或 'FINISHED', 'CANCELLED', 'REFUNDED'
limit	number	Optional	每页条数（默认：20）

响应示例 (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

查询订单状态并获取验证码

使用系统内部订单号 orderCode（例如 ACT8K3N9）查询订单。短信到达后将立即返回验证码。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string	Required	系统内部订单代码 orderCode（例如 ACT8K3N9）

响应示例 (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

请求接收下一条验证码

在租期内将状态重设为等待下一条短信验证码（适用于多次发送）。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string	Required	系统订单代码 orderCode

响应示例 (Response)

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

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

购买号码与接码 API

更换新手机号码 (2分钟未收到码)

如果当前号码在等待2分钟后未收到短信，可免费更换新号码。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string	Required	系统订单代码 orderCode

响应示例 (Response)

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

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

购买号码与接码 API

取消号码并 100% 自动退款

在未收到验证码时通过 orderCode 取消号码，系统将自动全额退款至钱包。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string	Required	系统订单代码 orderCode

响应示例 (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

标记订单已完成

在成功收到所需验证码后，标记该租号订单为已完成。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string	Required	系统订单代码 orderCode

响应示例 (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

检查旧号码二次接码可用性

检查已完成历史订单中的手机号码是否仍可在服务商处重新启用接码。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string	Required	前一笔订单的系统订单号 orderCode

响应示例 (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

二次启用旧号码接码

重新租用上一单相同的手机号码接收新的验证码，系统将为该号码生成新订单。

请求头 (Headers)

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

请求参数 (Parameters)

Field	Type	Required	Description
id	string	Required	前一笔订单的系统订单号 orderCode（路径参数）
duration	number	Optional	二次接码时长（分钟，默认：20）

请求体 (JSON Body)

{
  "duration": 20
}

响应示例 (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

长期租号时长套餐列表

查询按小时与按天（4小时、24小时、3天、7天等）长期租用套餐，含实时库存及折扣价格。

请求参数 (Parameters)

Field	Type	Required	Description
service	string	Required	服务代码（例如：tg, wa, fb...）
country	number \| string	Required	国家 ID（例如：10, 1, 6...）
verificationType	string	Optional	'sms'（默认）或 'call'

响应示例 (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

按时长租用独享号码 (按小时 / 按天)

创建指定时长的长期租号订单（duration 单位为分钟，例如 1440 代表 24 小时）。租期内支持多次无限接收该服务的验证码。

请求头 (Headers)

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

请求参数 (Parameters)

Field	Type	Required	Description
service	string	Required	服务代码（例如：tg, wa, fb...）
country	number \| string	Required	国家 ID（例如：10, 1, 6...）
duration	number	Required	租号时长（单位：分钟，例如 240 为 4 小时，1440 为 1 天，4320 为 3 天，10080 为 7 天）
verificationType	string	Optional	'sms'（默认）或 'call'
operator	string	Optional	指定运营商（默认：'any'）

请求体 (JSON Body)

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

响应示例 (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

查询在租号码可续费时长与价格

查询当前未到期的租用号码可延长的续期套餐及对应价格。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string	Required	租号订单的系统内部订单号 orderCode

响应示例 (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

为在租号码执行续费

为正在租用的号码续期，新到期时间将在现有到期时间上累计延长。

请求头 (Headers)

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

请求参数 (Parameters)

Field	Type	Required	Description
id	string	Required	系统内部订单代码 orderCode（路径参数）
duration	number	Required	续期时长（分钟，例如 1440 为 24 小时，4320 为 3 天）

请求体 (JSON Body)

{
  "duration": 1440
}

响应示例 (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

号码续费历史记录

查看某长期租号订单过往的所有成功续费记录。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string	Required	系统内部订单代码 orderCode

响应示例 (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

5 endpoints

GET/api/email-otp/offers

邮箱租用 API

邮箱域名列表与价格

获取目标网站可用的临时邮箱域名后缀（gmail.com、outlook.com、mail.com 等）及价格。

请求参数 (Parameters)

Field	Type	Required	Description
site	string	Required	目标网站名称（例如：telegram.com, openai.com...）

响应示例 (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

租用临时邮箱接码

租用临时邮箱以接收第三方账号激活验证码，支持设置价格上限 maxPrice。

请求头 (Headers)

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

请求体 (JSON Body)

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

响应示例 (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

获取邮箱验证码与邮件全文

查询邮箱状态。邮件到达后，返回提取的验证码（value）及完整邮件内容（message）。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string \| number	Required	邮箱接码订单 ID（例如：774819）

响应示例 (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

取消邮箱并 100% 退款

在未收到邮件前取消邮箱租用，全额原路退还至钱包。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string \| number	Required	邮箱接码订单 ID

响应示例 (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

再次租用已用过的历史邮箱

重新租用此前使用过的同一邮箱地址，以便为同一网站接收后续验证码。

请求头 (Headers)

x-api-key

your_api_key_here

API Key

请求参数 (Parameters)

Field	Type	Required	Description
id	string \| number	Required	此前的邮箱订单 ID

响应示例 (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

3 endpoints

GET/api/mail/products

邮箱购买 API

邮箱：产品列表

系统 API，用于获取邮箱产品。Provider 细节保持内部，客户端只使用本站 API 密钥。

请求头 (Headers)

x-api-key

your_website_api_key

网站 API 密钥

请求参数 (Parameters)

Field	Type	Required	Description
status	1	Optional	仅活动产品

响应示例 (Response)

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

POST/api/mail/buy

邮箱购买 API

邮箱：购买邮箱

通过系统 API 购买邮箱，自动扣除网站钱包余额。

请求头 (Headers)

x-api-key

your_website_api_key

网站 API 密钥

请求参数 (Parameters)

Field	Type	Required	Description
product_slug	string	Required	产品 slug
quantity	1..10000	Required	邮箱数量

请求体 (JSON Body)

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

响应示例 (Response)

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

POST/api/mail/read

邮箱购买 API

邮箱：读取 Outlook 收件箱

通过系统 API 读取已购买邮箱。Provider 和凭据保持内部处理。

请求头 (Headers)

x-api-key

your_website_api_key

网站 API 密钥

请求体 (JSON Body)

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

响应示例 (Response)

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

代理 API

4 endpoints

GET/api/proxy/download

代理 API

下载代理列表

下载您订单中的代理。目前需要 Clerk 登录会话。

请求参数 (Parameters)

Field	Type	Required	Description
order_id	string	Required	代理订单 ID 或编号
mode	direct \| backbone	Optional	代理类型，默认 direct
format	string	Optional	ip:port:user:pass、user:pass@ip:port 或 ip:port

响应示例 (Response)

1.2.3.4:8080:username:password

GET/api/proxy/countries

代理 API

代理国家列表

获取可购买代理的国家列表；供应商返回时包含可用 IP 数量。

响应示例 (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

查询代理价格

按代理类型、数量、国家、带宽和 VIP 等级计算售价。`countries` 为逗号分隔的 ISO 两位代码。

请求头 (Headers)

x-api-key

your_api_key_here

可选，用于应用 VIP 价格

请求参数 (Parameters)

Field	Type	Required	Description
proxy_type	string	Required	代理类型，例如 `shared` 或 `dedicated`
proxy_count	integer	Required	IP 数量，范围为 1 至 10,000
countries	string	Optional	逗号分隔的国家代码
bandwidth_limit	integer	Optional	带宽限制
term	`monthly` \| `yearly`	Optional	计费周期，默认为 `monthly`

响应示例 (Response)

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

POST/api/proxy/buy

代理 API

购买代理

购买代理套餐，并从 API Key 所属账户余额中扣款。

请求头 (Headers)

x-api-key

your_api_key_here

账户 API Key

请求体 (JSON Body)

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

响应示例 (Response)

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

SMS-Activate 兼容 API

18 endpoints

GET/stubs/handler_api.php?action=getBalance

SMS-Activate 兼容 API

SMS-Activate: 查询账户余额 (getBalance)

以纯文本 ACCESS_BALANCE:<amount> 格式返回折算为美元的可用钱包余额。完全兼容所有已接入 SMS-Activate 的软件。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	系统账户 API Key
action	string	Required	操作指令：getBalance

响应示例 (Response)

ACCESS_BALANCE:25.50

GET/stubs/handler_api.php?action=getNumber

SMS-Activate 兼容 API

SMS-Activate: 租用接码手机号 (getNumber - Text)

为指定服务和国家申请新手机号。返回纯文本 ACCESS_NUMBER:<activation_id>:<phone>。根据系统售价及 VIP 优惠自动扣减钱包余额。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getNumber
service	string	Required	服务代码（如 tg、wa、ig、go、fb、vi、lf 等）
country	number	Required	国家代码 ID（例如：10 - 越南，6 - 印尼，2 - 哈萨克斯坦，12 - 美国等）
operator	string	Optional	指定运营商（例如 viettel、mobifone、vinaphone）
maxPrice	number	Optional	可接受的最高价格（美元）。若实际售价高于此上限，系统将自动取消并返回 NO_NUMBERS。

响应示例 (Response)

ACCESS_NUMBER:819284712:84981234567

GET/stubs/handler_api.php?action=getNumberV2

SMS-Activate 兼容 API

SMS-Activate: 租用接码手机号 (getNumberV2 - JSON)

申请新号码并返回包含订单ID、手机号、价格（美元）、国家代码、到期时间及 canGetAnotherSms 标识的结构化 JSON。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getNumberV2
service	string	Required	服务代码（tg、wa、fb、go等）
country	number	Required	国家代码 ID

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 更新订单状态 (setStatus)

生命周期控制：status=1 (ACCESS_READY: 号码就绪)，status=3 (ACCESS_RETRY_GET: 请求下一次验证码)，status=6 (ACCESS_ACTIVATION: 完成订单)，status=8 (ACCESS_CANCEL: 取消并全额退款)。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：setStatus
id	string	Required	激活订单 activationId 或 orderCode
status	number	Required	1（就绪），3（请求新码），6（完成），8（取消与退款）

响应示例 (Response)

ACCESS_RETRY_GET

GET/stubs/handler_api.php?action=getStatus

SMS-Activate 兼容 API

SMS-Activate: 获取订单状态与验证码 (getStatus - Text)

查询订单状态。收到验证码返回 STATUS_OK:<code>。等待中返回 STATUS_WAIT_CODE。已取消返回 STATUS_CANCEL。自动同步最新验证码。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getStatus
id	string	Required	订单 ID (activationId / orderCode)

响应示例 (Response)

STATUS_OK:482910

GET/stubs/handler_api.php?action=getStatusV2

SMS-Activate 兼容 API

SMS-Activate: 获取详细验证码与状态 (getStatusV2 - JSON)

返回包含验证码、发件人标识、短信完整文本内容及接收时间的结构化 JSON 数据。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getStatusV2
id	string	Required	激活订单 ID

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 查询活跃订单列表 (getActiveActivations)

获取当前账户下所有正在等待验证码或已接收到验证码的活跃订单列表。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getActiveActivations

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 激活历史记录 (getHistory)

查询近期所有租号订单的历史记录，包含接收到的验证码短信、消费金额及最终状态。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getHistory

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 支持的国家列表 (getCountries)

返回所有可用国家列表及其 ID、俄语、英语、中文名称。系统配置中禁用的国家将自动被排除。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getCountries

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 可用服务列表 (getServicesList)

查询所有服务代码及其对应名称。已禁用的服务将自动过滤。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getServicesList
country	number	Optional	按国家 ID 筛选（可选）

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 运营商列表 (getOperators)

获取指定国家支持的电信运营商代码列表。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getOperators
country	number	Required	国家代码 ID（如 10 为越南）

响应示例 (Response)

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

GET/stubs/handler_api.php?action=getPrices

SMS-Activate 兼容 API

SMS-Activate: 价格与库存矩阵 (getPrices)

返回各国家及服务的实时售价与可用库存数。售价（cost）已自动包含系统利润率并扣减您的 VIP 会员专属折扣。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getPrices
country	number	Optional	指定筛选的国家 ID（可选）
service	string	Optional	指定筛选的服务代码（可选）

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 号码库存最多的国家榜单 (getTopCountriesByService)

查询特定服务下号码库存最充裕、性价比最高的顶级国家列表。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getTopCountriesByService
service	string	Required	服务代码（如 tg）

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 获取订单全部接收到的短信 (getAllSms)

获取该订单在租用期间接收到的所有短信文本及语音验证码记录。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getAllSms
id	string	Required	激活订单 ID

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 长期租号库存与价格表 (serviceCountRent)

查询长期租号时长套餐（如 2小时、4小时、24小时、72小时、168小时等）的可用库存与 VIP 折扣价格。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：serviceCountRent
country	number	Optional	查询的国家 ID

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 订购长期租用手机号 (getRentNumber)

按小时或天数长期租用手机号（duration：4、24、72、168等）。租期内可无限制连续接收多条验证码短信。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：getRentNumber
service	string	Required	服务代码（如 tg）
country	number	Required	国家代码 ID
duration	number	Required	租用时长（小时数，例如 24 为1天，168 为7天）

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 延长长期租用时间 (prolong)

在当前租期到期前延长该手机号的租用时长。续费费用将自动从钱包余额中扣除。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：prolong
id	string	Required	激活订单 ID
duration	number	Required	续租小时数（如 24）

响应示例 (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

SMS-Activate 兼容 API

SMS-Activate: 重新激活历史号码 (reactivate)

重新租用之前已完成订单的同一手机号以接收新验证码（需该号码在运营商端仍可用）。

请求参数 (Parameters)

Field	Type	Required	Description
api_key	string	Required	账户 API Key
action	string	Required	操作指令：reactivate
id	string	Required	历史订单的 activationId

响应示例 (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
}

订单状态码字典

短信与邮箱租用全流程状态说明

WAIT_CODE等待运营商或服务商发送验证码至手机或邮箱

OK / SUCCESS成功接收验证码，包含提取代码与完整短信内容

REFUNDED订单已取消，款项已 100% 全额原路退还至钱包

FINISHED订单已使用完毕并正常结束

HTTP 响应状态码与错误处理

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

200 OK请求成功，数据返回在 data 字段中。

400 Bad Request参数无效、缺少必填字段或服务暂时缺货。

401 Unauthorized缺少 API Key 或 API Key 无效。请检查 x-api-key 请求头。

402 Payment Required钱包余额不足以支付订单。请充值。