HTTP & JSON API

VirtualSim API

API для автоматизации получения SMS на виртуальные номера. Все запросы возвращают JSON. Цены в USD.

Production ready 2 req/sec per API key 180+ стран, тысячи сервисов

Аутентификация

Во всех запросах должен присутствовать ваш персональный API-ключ. Получите его в профиле, включив API-доступ.

Способ 1 — Query-параметр (рекомендуется)

Передайте ключ в параметре api_key любого запроса. Самый простой и надёжный способ.

https://virtualsim.io/api/v1/getBalance?api_key=YOUR_API_KEY

Способ 2 — HTTP-заголовок

Передайте ключ в заголовке Authorization с префиксом Bearer.

Authorization: Bearer YOUR_API_KEY

Оба способа равнозначны. Если указаны оба — приоритет у query-параметра. При неверном ключе сервер вернёт 401 Unauthorized.

Лимиты запросов

Ограничение: 2 запроса в секунду на API-ключ. При превышении сервер вернёт 429 Too Many Requests.

Устаревший API

Совместимость с SMS-Activate

Один адрес, тип операции задаётся параметром action. Ответ — одна текстовая строка (например, ACCESS_BALANCE:12.3) или JSON, в зависимости от вызова. Используйте тот же API-ключ, что и для запросов к /api/v1/... (см. аутентификация).

Базовый адрес

Поддерживаются GET и POST. Параметры передавайте в query-строке (как в примере) или, для POST, в теле формы — по смыслу то же, что в разделе «Аутентификация» для api_key.

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

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

Для POST те же action и ключ — в query или в теле запроса.

Общие query-параметры

Параметр	Тип	Обяз.	Описание
action	string	да	Имя операции, например `getBalance` или `getNumber`.
api_key	string	нет	Персональный ключ. Можно не указывать, если передан заголовок `Authorization: Bearer` (см. ниже).

Вместо api_key в строке запроса можно передать ключ в заголовке (как в разделе «Аутентификация»):

Authorization: Bearer YOUR_API_KEY

Если указаны и query, и заголовок, приоритет у api_key в URL — как для /api/v1/....

Методы (`action`)

Во втором и третьем столбцах — смысл вызова и формат ответа. Дополнительные поля подбирайте по описанию этой же операции в справочнике SMS-Activate: для заказа номера укажите service и country, для проверки статуса — id активации и т.д. В VirtualSim это те же сценарии, что в личном кабинете и в JSON API, собранные в одном пути как action=… плюс параметры в query или в теле POST.

action	Назначение	Заметки
`getBalance`	Текущий баланс	Строка `ACCESS_BALANCE:…`
`getNumber`	Заказ номера	Обязательны `service` и `country`; ответ `ACCESS_NUMBER:…`
`getNumberV2`	Заказ номера (JSON)	Те же параметры, в ответе — расширенный объект
`getStatus` / `getStatusV2`	Статус активации / getStatusV2	Параметр `id` (activation id); V2 — JSON
`setStatus`	Смена статуса (1, 3, 6, 8, …)	Параметры `id` и `status`
`getCountries`	Список стран	JSON-массив
`getServicesList`	Список сервисов	По желанию `country`, `lang`
`getPrices`	Цены и остатки	Параметр `country` обязателен (каталог VirtualSim).
`getActiveActivations`	Активные активации	JSON
`getHistory`	История	Период — `start` / `end` (Unix), пагинация
`reactivationPrice` / `reactivate`	Цена и повторная активация	Параметр `id` — прошлая активация; реактивация доступна не для всех заказов. Подробнее: JSON API.
`getAllSms`	SMS по активации	Обязателен `id`; из истории SMS по этой активации
`finishActivation` / `cancelActivation`	Завершить / отменить	При успехе — `204` без тела, где применимо

Пример ответа (баланс)

Текст в ответ на getBalance:

ACCESS_BALANCE:100.50

API активации

POST Заказ номера

Покупает виртуальный номер для указанного сервиса и страны. Средства списываются с баланса.

https://virtualsim.io/api/v1/orderNumber

Параметр	Тип	Обяз.	Описание
service	string	да	Код сервиса (tg, wa, vk, ...)
country	number	да	ID страны из каталога

Возможные ошибки: service и country обязательны, Недостаточно средств, Достигнут максимум активных номеров

GET Получить статус активации

Возвращает текущий статус активации и полученный код SMS.

https://virtualsim.io/api/v1/getStatus?id=$id

Параметр	Тип	Обяз.	Описание
id	string	да	ID активации (activationId), полученный при заказе

POST Изменение статуса активации

Управляет жизненным циклом активации: подтверждение готовности, запрос повторной SMS, завершение или отмена.

https://virtualsim.io/api/v1/setStatus

Параметр	Тип	Обяз.	Описание
id	string	да	ID активации
status	number	да	Код статуса (см. ниже)

Коды статусов:
1 — готовность номера (SMS отправлена);
3 — запросить повторную SMS;
6 — завершить активацию;
8 — отменить активацию.

GET Все активные активации

Возвращает список всех текущих активаций пользователя с полученными SMS.

https://virtualsim.io/api/v1/getActiveActivations

GET Стоимость повторной активации

Возвращает расчётную стоимость повторной активации (с наценкой сервиса) по идентификатору ранее оформленного заказа. Если для этого заказа реактивация недоступна, вернётся код 400.

https://virtualsim.io/api/v1/reactivationPrice?id=$ACTIVATION_ID

Параметр	Тип	Обяз.	Описание
id	string / number	да	Идентификатор прошлой активации, готовой к повтору (тот же, что `activationId` в заказе).

При успехе тело ответа: { "data": { "price": …, "currency": 840 } } — привычный формат ответа «цена/валюта».

POST Повторная активация

Списывает с баланса согласованную сумму и создаёт новую активацию по тому же сценарию, что и исходный заказ. В ответе — новый activationId и номер телефона.

https://virtualsim.io/api/v1/reactivate

Тело: JSON, например

{ "id": "635468024" }

Вместо id можно передать tzid с тем же значением (как в личном кабинете).

Параметр	Тип	Обяз.	Описание
id / tzid	string / number	да	Исходный идентификатор активации: укажите либо `id`, либо `tzid`.

Возможные ответы: 402 при недостаточном балансе, 404 если заказ не найден, 400 если для этого заказа реактивация недоступна, 502 при ошибке расчёта / выполнения.

Каталог и баланс

GET Получить актуальные цены

Возвращает цены и количество доступных номеров. Можно фильтровать по сервису и/или стране.

https://virtualsim.io/api/v1/getPrices?service=$service&country=$country

Параметр	Тип	Обяз.	Описание
service	string	нет	Код сервиса для фильтрации
country	number	нет	ID страны для фильтрации

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

Возвращает полный список поддерживаемых стран с их ID и именами.

https://virtualsim.io/api/v1/getCountries

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

Возвращает полный список поддерживаемых сервисов с кодами и названиями.

https://virtualsim.io/api/v1/getServices

GET Проверка баланса

Возвращает текущий баланс аккаунта.

https://virtualsim.io/api/v1/getBalance

POST SMS Webhook

Настройте URL, куда VirtualSim будет отправлять webhook при получении SMS по вашим активациям.

https://virtualsim.io/api/v1/setSmsWebhook

Параметр	Тип	Обяз.	Описание
enabled	boolean	да	Включить или выключить отправку webhook
url	string	нет	URL вашего обработчика (обязателен, если enabled=true)
secret	string	нет	Signing secret для подписи X-Signature (если не передать — останется прежний)

https://virtualsim.io/api/v1/getSmsWebhook

Подпись: заголовок X-Signature = HMAC-SHA256(raw_body) в hex. Принимающая сторона должна ответить 200 OK.

{\n  \"event\": \"sms.received\",\n  \"activationId\": \"123456\",\n  \"service\": \"tg\",\n  \"country\": 2,\n  \"phoneNumber\": \"79990001122\",\n  \"text\": \"Sms text\",\n  \"code\": \"12345\",\n  \"receivedAt\": \"2026-03-17 12:00:00 UTC\"\n}

python_example.py

import requests

API = "https://virtualsim.io/api/v1"
KEY = "YOUR_API_KEY"

# --- Method 1: api_key in URL (recommended) ---

prices = requests.get(
  f"{API}/getPrices",
  params={"service": "tg", "api_key": KEY}
).json()

order = requests.post(
  f"{API}/orderNumber",
  params={"api_key": KEY},
  json={"service": "tg", "country": 0}
).json()

status = requests.get(
  f"{API}/getStatus",
  params={"id": order["activationId"],
          "api_key": KEY}
).json()

# --- Method 2: Bearer header ---

H = {"Authorization": f"Bearer {KEY}"}
balance = requests.get(
  f"{API}/getBalance", headers=H
).json()
# {"balance": 10.00, "currency": "USD"}

getPrices response

{
  "0": {
    "tg": { "cost": 0.42, "count": 11540 },
    "wa": { "cost": 0.18, "count": 8230 },
    "vk": { "cost": 0.12, "count": 5700 }
  },
  "6": {
    "tg": { "cost": 0.21, "count": 4500 }
  }
}

orderNumber response

{
  "activationId": 38496653,
  "phoneNumber": "79001234567",
  "cost": 0.42,
  "currency": "USD",
  "balance": 9.58
}

getBalance response

{
  "balance": 10.00,
  "currency": "USD"
}

getCountries response

{
  "countries": [
    { "id": 0, "rus": "Россия", "eng": "Russia" },
    { "id": 1, "rus": "Украина", "eng": "Ukraine" },
    { "id": 6, "rus": "Индонезия", "eng": "Indonesia" }
  ]
}

getActiveActivations response

{
  "activations": [
    {
      "activationId": "38496653",
      "service": "tg",
      "country": 0,
      "phoneNumber": "79001234567",
      "cost": 0.42,
      "currency": "USD",
      "smsReceived": true,
      "messages": [
        {
          "text": "Code: 12345",
          "receivedAt": "2026-03-09 14:30:00"
        }
      ]
    }
  ]
}