SMS-Activate compatible

Документация API

API совместимый с SMS-Activate

Получить API-ключProductionСовместимо с клиентами SMS-Activate

Обзор

Базовый URL совместимости — /stubs/handler_api.php. Операция задаётся параметром action. Цены в USD, баланс VirtualSim, каталог тот же, что в веб-интерфейсе.

Base URL

https://virtualsim.io/stubs/handler_api.php

Alternate

https://virtualsim.io/api/stubs/handler_api.php

Авторизация

Ключ включается в профиле. Передавайте его одним из способов:

Query-параметр?api_key=YOUR_API_KEY
HTTP-заголовокAuthorization: Bearer YOUR_API_KEY

Не публикуйте ключ в открытых репозиториях и клиентском коде браузера.

Быстрый старт

Типичный сценарий: баланс → заказ номера → опрос статуса → завершение.

getBalance
getNumber → ACCESS_NUMBER:id:phone
getStatus until STATUS_OK:code
setStatus&status=6 or finishActivation

curl 'https://virtualsim.io/stubs/handler_api.php?action=getNumber&service=tg&country=0&api_key=YOUR_API_KEY'

Коды ответов

Текстовые ошибки SMS-Activate и HTTP-статусы.

BAD_KEY / 401	Неверный или отсутствующий API-ключ
NO_BALANCE / 402	Недостаточно средств
NO_NUMBERS	Нет доступных номеров
BAD_ACTION / 400	Неизвестный action или плохие параметры
WRONG_MAX_NUMBERS	Достигнут лимит активных номеров
STATUS_CANCEL	Активация отменена
204	Успех без тела (finish/cancel)

Аккаунт

GET

getBalance

— Баланс аккаунта

Возвращает текущий баланс в формате ACCESS_BALANCE:<amount>.

Ответ

Текстовая строка ACCESS_BALANCE:100.50

ACCESS_BALANCE:100.50

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getBalance&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getBalance&api_key=YOUR_API_KEY'

Активации

GET

getNumber

— Заказать номер

Заказывает номер для сервиса и страны. Ответ: ACCESS_NUMBER:<id>:<number>.

Параметры

Name	Type	Параметры
serviceобяз.	string	Код сервиса (tg, wa, go…)
countryобяз.	number	ID страны
maxPrice	number	Максимальная цена USD
fixedPrice	string	true — строго по maxPrice

Ответ

ACCESS_NUMBER:123456789:79001234567

ACCESS_NUMBER:123456789:79001234567

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getNumber&service=tg&country=0&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getNumber&service=tg&country=0&api_key=YOUR_API_KEY'

GET

getNumberV2

— Заказать номер (V2 JSON)

То же, что getNumber, но ответ — JSON с деталями активации.

Параметры

Name	Type	Параметры
serviceобяз.	string	Код сервиса
countryобяз.	number	ID страны

Ответ

JSON-объект активации

{
  "activationId": "635468024",
  "phoneNumber": "79001234567",
  "activationCost": 0.35,
  "currency": 840,
  "countryCode": 0,
  "canGetAnotherSms": true
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getNumberV2&service=tg&country=0&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getNumberV2&service=tg&country=0&api_key=YOUR_API_KEY'

GET

getActiveActivations

— Активные активации

Список текущих активных заказов.

Параметры

Name	Type	Параметры
start	integer	Offset (по умолчанию 0)
limit	integer	Лимит (макс. 100)

Ответ

JSON { status, data[] }

{
  "status": "success",
  "data": [
    {
      "activationId": "635468021",
      "serviceCode": "tg",
      "phoneNumber": "79001234567",
      "activationCost": 0.35,
      "activationStatus": "1",
      "currency": 840
    }
  ]
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getActiveActivations&start=0&limit=20&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getActiveActivations&start=0&limit=20&api_key=YOUR_API_KEY'

GET

getHistory

— История активаций

История за период (Unix timestamp).

Параметры

Name	Type	Параметры
start	integer	Начало периода
end	integer	Конец периода
offset	integer	Offset
size	integer	Лимит (макс. 100)

Ответ

JSON-массив

[
  {
    "id": "635468024",
    "date": "2026-02-18 16:11:33",
    "phone": "79001234567",
    "cost": 0.35,
    "status": "4",
    "currency": 840
  }
]

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getHistory&start=1700000000&end=1800000000&offset=0&size=50&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getHistory&start=1700000000&end=1800000000&offset=0&size=50&api_key=YOUR_API_KEY'

POST

reactivate

— Реактивация номера

Повторный заказ ранее использованного номера.

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации
duration	number	Срок в часах (опционально)

Ответ

JSON активации

{
  "activationId": "123456",
  "serviceCode": "tg",
  "phoneNumber": "79991234567",
  "activationCost": 15.5,
  "currency": 840,
  "countryCode": 2,
  "canGetAnotherSms": true,
  "status": 4
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=reactivate&id=123456789&duration=24&api_key=YOUR_API_KEY

curl -X POST 'https://virtualsim.io/stubs/handler_api.php?action=reactivate&id=123456789&duration=24&api_key=YOUR_API_KEY'

GET

reactivateOptions

— Стоимость реактивации

Цена повторной активации номера.

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации

Ответ

JSON options

{
  "data": {
    "options": [
      { "price": 0.42, "duration": { "unit": "hour", "value": 24 } }
    ]
  }
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=reactivateOptions&id=123456789&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=reactivateOptions&id=123456789&api_key=YOUR_API_KEY'

Статус и SMS

GET

setStatus

— Сменить статус активации

3 — запросить ещё SMS, 6 — завершить, 8 — отменить (возврат).

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации
statusобяз.	integer	3 \| 6 \| 8

Ответ

ACCESS_RETRY_GET / ACCESS_ACTIVATION / ACCESS_CANCEL

ACCESS_RETRY_GET

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=setStatus&id=123456789&status=8&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=setStatus&id=123456789&status=8&api_key=YOUR_API_KEY'

GET

getStatus

— Статус активации

STATUS_WAIT_CODE, STATUS_OK:<code>, STATUS_CANCEL и др.

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации

Ответ

Текстовый статус

STATUS_OK:12345

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getStatus&id=123456789&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getStatus&id=123456789&api_key=YOUR_API_KEY'

GET

getStatusV2

— Статус активации V2

Структурированный JSON со SMS/звонком.

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации

Ответ

JSON со статусом

{
  "verificationType": 2,
  "sms": {
    "dateTime": "2026-02-18T16:11:33+00:00",
    "code": "12345",
    "text": "Your code is 12345"
  }
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getStatusV2&id=123456789&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getStatusV2&id=123456789&api_key=YOUR_API_KEY'

GET

getAllSms

— Все SMS по активации

Все полученные SMS/OTP по ID активации.

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации

Ответ

JSON { data, meta }

{
  "data": [
    {
      "code": "12345",
      "text": "Your code is 12345",
      "service": "tg",
      "type": "sms"
    }
  ],
  "meta": { "total": 1, "service": "tg" }
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getAllSms&id=123456789&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getAllSms&id=123456789&api_key=YOUR_API_KEY'

GET

finishActivation

— Завершить активацию

Завершает работу с активацией (HTTP 204).

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации

Ответ

204 No Content

(empty body)

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=finishActivation&id=123456789&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=finishActivation&id=123456789&api_key=YOUR_API_KEY'

GET

cancelActivation

— Отменить активацию

Отмена покупки с возвратом, если SMS ещё не получено (HTTP 204).

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации

Ответ

204 No Content

(empty body)

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=cancelActivation&id=123456789&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=cancelActivation&id=123456789&api_key=YOUR_API_KEY'

Каталог

GET

getCountries

— Список стран

Все доступные страны каталога.

Ответ

JSON-массив стран

[
  { "id": 0, "eng": "Russia", "rus": "Россия", "visible": 1 }
]

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getCountries&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getCountries&api_key=YOUR_API_KEY'

GET

getServicesList

— Список сервисов

Сервисы для выбранной страны.

Параметры

Name	Type	Параметры
country	number	ID страны
lang	string	en \| ru \| …

Ответ

JSON { status, services }

{
  "status": "success",
  "services": [
    { "code": "tg", "name": "Telegram" }
  ]
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getServicesList&country=0&lang=en&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getServicesList&country=0&lang=en&api_key=YOUR_API_KEY'

GET

getPrices

— Цены и наличие

Цены и количество номеров по стране/сервису.

Параметры

Name	Type	Параметры
service	string	Код сервиса
country	number	ID страны

Ответ

JSON с cost/count

{
  "0": {
    "tg": { "cost": 0.35, "count": 1200, "physicalCount": 800 }
  }
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getPrices&service=tg&country=0&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getPrices&service=tg&country=0&api_key=YOUR_API_KEY'

GET

getTopCountriesByService

— Топ стран по сервису

Рейтинг стран по наличию и цене для сервиса.

Параметры

Name	Type	Параметры
serviceобяз.	string	Код сервиса

Ответ

JSON-массив

[{ "tg": [{ "country": 0, "price": 0.35, "count": 1200 }] }]

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getTopCountriesByService&service=tg&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getTopCountriesByService&service=tg&api_key=YOUR_API_KEY'

Аренда

GET

serviceCountRent

— Цены аренды

Цены и количество для аренды (service=full) по срокам.

Параметры

Name	Type	Параметры
serviceобяз.	string	Обычно full
country	number	ID страны

Ответ

JSON country → duration → price

{
  "0": {
    "24": { "count": 120, "price": 1.2, "retail_price": 1.2 },
    "48": { "count": 80, "price": 2.1, "retail_price": 2.1 }
  }
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=serviceCountRent&service=full&country=0&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=serviceCountRent&service=full&country=0&api_key=YOUR_API_KEY'

GET

getRentServicesAndCountries

— Аренда: сервисы страны

Цены аренды для страны и срока.

Параметры

Name	Type	Параметры
countryобяз.	number	ID страны
durationобяз.	number	Срок в часах

Ответ

JSON services

{
  "services": {
    "full": { "quantity": 120, "price": 1.2, "retail_price": 1.2 }
  }
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getRentServicesAndCountries&country=0&duration=24&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getRentServicesAndCountries&country=0&duration=24&api_key=YOUR_API_KEY'

GET

getRentNumber

— Арендовать номер

Заказ номера в аренду на указанный срок (часы).

Параметры

Name	Type	Параметры
serviceобяз.	string	full — универсальный номер
countryобяз.	number	ID страны
durationобяз.	number	2,4,12,24,48,72,96,120,144,168

Ответ

JSON активации аренды

{
  "activationId": "123456",
  "phoneNumber": "79001234567",
  "activationCost": 1.2,
  "currency": 840,
  "countryCode": 0,
  "canGetAnotherSms": true
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=getRentNumber&service=full&country=0&duration=24&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=getRentNumber&service=full&country=0&duration=24&api_key=YOUR_API_KEY'

GET

prolongOptions

— Стоимость продления

Тарифы продления аренды.

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации

Ответ

JSON options

{
  "data": {
    "options": [
      { "price": 1.43, "duration": { "unit": "hour", "value": 24 } }
    ]
  }
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=prolongOptions&id=123456789&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=prolongOptions&id=123456789&api_key=YOUR_API_KEY'

POST

prolong

— Продлить аренду

Продлевает аренду на указанное число часов.

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации
durationобяз.	number	Часы продления

Ответ

JSON активации

{
  "activationId": "123456",
  "phoneNumber": "79001234567",
  "activationCost": 1.43,
  "currency": 840
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=prolong&id=123456789&duration=24&api_key=YOUR_API_KEY

curl -X POST 'https://virtualsim.io/stubs/handler_api.php?action=prolong&id=123456789&duration=24&api_key=YOUR_API_KEY'

GET

prolongHistory

— История продлений

История продлений аренды по активации.

Параметры

Name	Type	Параметры
idобяз.	integer	ID активации

Ответ

JSON data[]

{
  "data": [
    {
      "userPrice": 1.43,
      "hours": 24,
      "createDate": "2026-02-19T10:37:46+00:00",
      "payerType": "client"
    }
  ]
}

Пример запроса

https://virtualsim.io/stubs/handler_api.php?action=prolongHistory&id=123456789&api_key=YOUR_API_KEY

curl 'https://virtualsim.io/stubs/handler_api.php?action=prolongHistory&id=123456789&api_key=YOUR_API_KEY'

Webhooks

Входящие SMS можно получать push-ом без polling. Настройка — REST /api/v1/setSmsWebhook. Рекомендуется отвечать HTTP 200.

Method: POST, Content-Type: application/json
Configure: POST https://virtualsim.io/api/v1/setSmsWebhook
Read: GET https://virtualsim.io/api/v1/getSmsWebhook

Пример тела webhook

{
  "activationId": "635468024",
  "phoneNumber": "79001234567",
  "service": "tg",
  "text": "Your code is 12345",
  "code": "12345"
}

REST API /api/v1

Современный JSON-интерфейс с той же бизнес-логикой. Bearer API key или cookie-сессия.

GET /getBalancehttps://virtualsim.io/api/v1/getBalance

POST /orderNumberhttps://virtualsim.io/api/v1/orderNumber

GET /getStatushttps://virtualsim.io/api/v1/getStatus?id=ACTIVATION_ID

POST /setStatushttps://virtualsim.io/api/v1/setStatus

GET /getPriceshttps://virtualsim.io/api/v1/getPrices?service=tg&country=0

GET /getCountrieshttps://virtualsim.io/api/v1/getCountries

GET /getServiceshttps://virtualsim.io/api/v1/getServices

GET /getActiveActivationshttps://virtualsim.io/api/v1/getActiveActivations

GET /getSmsWebhookhttps://virtualsim.io/api/v1/getSmsWebhook

POST /setSmsWebhookhttps://virtualsim.io/api/v1/setSmsWebhook