API для разработчиков

Публичный API — один эндпоинт и только GET-запросы: имя метода передаётся параметром action. Формат совместим с популярными площадками, поэтому готовый код начинает работать после смены базового URL.

Ключ доступаПолучить ключ
Ключ выпускается в личном кабинете — войдите или зарегистрируйтесь, чтобы получить его.Строка ключа показывается один раз — в момент выпуска. Потерян ключ — выпустите новый, старый отзовите.
Базовый URL
GEThttps://sim-aggregator.org/stubs/handler_api.php
Все методы вызываются по этому адресу; отличается только параметр action.
Порядок работы
1getPrices · getServicesListУзнайте цену и наличие по нужному сервису и стране.
2getNumber · getNumberV2Закажите номер — в ответе придут id активации и сам номер.
3getStatusОпрашивайте статус, пока не придёт код.
4setStatus · 6Завершите активацию, когда код принят сервисом.
—setStatus · 3 · 8Нужен ещё один код — 3; номер не пригодился — 8, деньги вернутся.
Сводка методов
МетодКлючПараметры
getPricesнужен ключaction, api_key, [country], [service]
getCountriesнужен ключaction, api_key
getServicesListнужен ключaction, api_key, [country]
getBalanceнужен ключaction, api_key
getNumberнужен ключaction, api_key, country, service, [duration], [maxPrice], [softId]
getNumberV2нужен ключaction, api_key, country, service, [duration], [maxPrice], [softId]
getStatusнужен ключaction, api_key, id
getCurrentActivationsListнужен ключaction, api_key
setStatusнужен ключaction, api_key, id, status

getPrices

нужен ключ

Цены и наличие по стране и сервису — сколько номеров есть и по какой цене.

Параметры
ПараметрТипОбязательныйОписание
actionstringобязательныйНазвание метода: getPrices
api_keystringобязательныйКлюч доступа из кабинета
countrystringнетИдентификатор страны, например 43
servicestringнетКод сервиса, например wa
Запрос
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getPrices&api_key=YOUR_API_KEY&country=43
Ответ
{
  "43": {
    "wa": { "cost": 0.5, "count": 100 },
    "tg": { "cost": 0.71, "count": 250 }
  }
}
Без параметров метод отдаёт весь прайс — ответ большой, поэтому запрашивайте нужную страну и сервис.
Что может ответить
BAD_COUNTRYСтрана не найдена
BAD_SERVICEСервис не найден
BAD_KEYКлюч не подошёл: не существует или отозван

getCountries

нужен ключ

Справочник стран: идентификатор, названия и то, какие режимы в стране доступны.

Параметры
ПараметрТипОбязательныйОписание
actionstringобязательныйНазвание метода: getCountries
api_keystringобязательныйКлюч доступа из кабинета
Запрос
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getCountries&api_key=YOUR_API_KEY
Ответ
{
  "43": { "id": 43, "rus": "DE", "eng": "DE", "chn": "DE",
         "visible": 1, "retry": 1, "rent": 0, "multiService": 0 }
}
В полях rus, eng и chn сейчас приходит двухбуквенный ISO-код страны, а не её название.
Что может ответить
BAD_KEYКлюч не подошёл: не существует или отозван

getServicesList

нужен ключ

Справочник сервисов: код сервиса и его название.

Параметры
ПараметрТипОбязательныйОписание
actionstringобязательныйНазвание метода: getServicesList
api_keystringобязательныйКлюч доступа из кабинета
countrystringнетИдентификатор страны, например 43
Запрос
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getServicesList&api_key=YOUR_API_KEY
Ответ
{
  "status": "success",
  "services": [
    { "code": "tg", "name": "Telegram" },
    { "code": "wa", "name": "WhatsApp" }
  ]
}
С параметром country список сужается до сервисов, которые в этой стране действительно продаются.
Что может ответить
BAD_COUNTRYСтрана не найдена
BAD_KEYКлюч не подошёл: не существует или отозван

getBalance

нужен ключ

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

Параметры
ПараметрТипОбязательныйОписание
actionstringобязательныйНазвание метода: getBalance
api_keystringобязательныйКлюч доступа из кабинета
Запрос
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getBalance&api_key=YOUR_API_KEY
Ответ
ACCESS_BALANCE:12.50
Ответ — строка, а не JSON: сумма стоит после двоеточия.
Что может ответить
BAD_KEYКлюч не подошёл: не существует или отозван

getNumber

нужен ключ

Заказать номер. В ответе — id активации и сам номер.

Параметры
ПараметрТипОбязательныйОписание
actionstringобязательныйНазвание метода: getNumber
api_keystringобязательныйКлюч доступа из кабинета
countrystringобязательныйИдентификатор страны, например 43
servicestringобязательныйКод сервиса, например wa
durationstringнетСрок заказа: activation — разовая активация (по умолчанию), d1, d3, d7 — аренда номера на 1, 3 или 7 дней
maxPricestringнетПотолок цены за номер. Дороже не купим: вместо заказа придёт WRONG_MAX_PRICE или NO_NUMBERS
softIdstringнетИдентификатор софта, до 255 символов
Запрос
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getNumber&api_key=YOUR_API_KEY&country=43&service=wa
Ответ
ACCESS_NUMBER:12345:380991234567
Ответ — строка ACCESS_NUMBER:id:номер. Id понадобится для getStatus и setStatus. Без duration заказывается разовая активация. С duration=d1, d3 или d7 номер берётся в аренду и виден в getCurrentActivationsList, пока аренда не закончилась. Если такого срока у сервиса нет — ответ BAD_SERVICE. Если указан maxPrice, а аренда дороже потолка, — ответ NO_NUMBERS, без минимальной цены: WRONG_MAX_PRICE:цена приходит только для activation.
Что может ответить
NO_BALANCEНа балансе не хватает денег на заказ
NO_NUMBERSСвободных номеров по этой паре сейчас нет
BAD_COUNTRYСтрана не найдена
BAD_SERVICEСервис не найден
BAD_DURATIONНеизвестное значение duration
WRONG_MAX_PRICE:PRICEЦена выше maxPrice; после двоеточия — самая низкая цена по этой паре (только для разовой активации)
BAD_MAX_PRICEmaxPrice не число или не больше нуля
BAD_KEYКлюч не подошёл: не существует или отозван
CHANNEL_LIMITДостигнут лимит одновременных активаций
BAD_SOFTWARE_IDНекорректный softId
ERROR_APIНепредвиденная ошибка на стороне сервиса

getNumberV2

нужен ключ

Заказать номер — то же, что getNumber, но успешный ответ приходит в JSON с ценой, страной и временем активации.

Параметры
ПараметрТипОбязательныйОписание
actionstringобязательныйНазвание метода: getNumberV2
api_keystringобязательныйКлюч доступа из кабинета
countrystringобязательныйИдентификатор страны, например 43
servicestringобязательныйКод сервиса, например wa
durationstringнетСрок заказа: activation — разовая активация (по умолчанию), d1, d3, d7 — аренда номера на 1, 3 или 7 дней
maxPricestringнетПотолок цены за номер. Дороже не купим: вместо заказа придёт WRONG_MAX_PRICE или NO_NUMBERS
softIdstringнетИдентификатор софта, до 255 символов
Запрос
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getNumberV2&api_key=YOUR_API_KEY&country=43&service=wa
Ответ
{
  "activationId": 12345,
  "phoneNumber": "380991234567",
  "activationCost": 0.50,
  "currency": 840,
  "countryCode": "43",
  "canGetAnotherSms": "1",
  "activationTime": "2026-07-31 12:00:00",
  "activationOperator": "any"
}
Отличается от getNumber только успешным ответом. activationTime — время UTC. Отказы приходят так же, как у getNumber, — текстовой строкой, а не JSON.
Что может ответить
NO_BALANCEНа балансе не хватает денег на заказ
NO_NUMBERSСвободных номеров по этой паре сейчас нет
BAD_COUNTRYСтрана не найдена
BAD_SERVICEСервис не найден
BAD_DURATIONНеизвестное значение duration
WRONG_MAX_PRICE:PRICEЦена выше maxPrice; после двоеточия — самая низкая цена по этой паре (только для разовой активации)
BAD_MAX_PRICEmaxPrice не число или не больше нуля
BAD_KEYКлюч не подошёл: не существует или отозван
CHANNEL_LIMITДостигнут лимит одновременных активаций
BAD_SOFTWARE_IDНекорректный softId
ERROR_APIНепредвиденная ошибка на стороне сервиса

getStatus

нужен ключ

Статус активации: ждём код или код уже пришёл.

Параметры
ПараметрТипОбязательныйОписание
actionstringобязательныйНазвание метода: getStatus
api_keystringобязательныйКлюч доступа из кабинета
idstringобязательныйИдентификатор активации из getNumber
Запрос
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getStatus&api_key=YOUR_API_KEY&id=12345
Ответ
STATUS_OK:123456
Что может ответить
STATUS_WAIT_CODEНомер выдан, кода ещё нет
STATUS_OK:CODEКод получен, в хвосте — код из SMS
STATUS_WAIT_RETRY:CODEЖдём следующий код; в хвосте — предыдущий код
STATUS_CANCELАктивация уже закрыта: отменена или завершена
NO_ACTIVATIONАктивация не найдена или уже закрыта
BAD_KEYКлюч не подошёл: не существует или отозван

getCurrentActivationsList

нужен ключ

Активные заказы по ключу: номера, которые ещё ждут код или уже его получили.

Параметры
ПараметрТипОбязательныйОписание
actionstringобязательныйНазвание метода: getCurrentActivationsList
api_keystringобязательныйКлюч доступа из кабинета
Запрос
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=getCurrentActivationsList&api_key=YOUR_API_KEY
Ответ
[
  {
    "numberid": 12345,
    "number": "380991234567",
    "status": 0
  }
]
Плоский JSON-массив. status: 0 — ждём код, 3 — код получен; закрытые заказы в список не попадают. Нет активных заказов — пустой массив [].
Что может ответить
BAD_KEYКлюч не подошёл: не существует или отозван
ERROR_APIНепредвиденная ошибка на стороне сервиса

setStatus

нужен ключ

Изменить состояние активации: запросить ещё код, завершить или отменить.

Параметры
ПараметрТипОбязательныйОписание
actionstringобязательныйНазвание метода: setStatus
api_keystringобязательныйКлюч доступа из кабинета
idstringобязательныйИдентификатор активации из getNumber
statusstringобязательныйНовое состояние активации: 3, 6 или 8
Запрос
GET https://sim-aggregator.org/stubs/handler_api.php
  ?action=setStatus&api_key=YOUR_API_KEY&id=12345&status=6
Ответ
ACCESS_ACTIVATION
Завершайте активацию явно: закрытый заказ освобождает слот, а отмена возвращает деньги на баланс.
Значения status
3запросить ещё один код на тот же номер
6завершить активацию: код принят
8отменить активацию, деньги вернутся на баланс
Что может ответить
ACCESS_ACTIVATIONАктивация завершена
ACCESS_CANCELАктивация отменена, деньги вернулись
ACCESS_RETRY_GETЗапрос принят: ждём следующий код на этот же номер
NO_ACTIVATIONАктивация не найдена или уже закрыта
EARLY_CANCEL_DENIEDОтменять ещё рано — повторите запрос позже
BAD_STATUSНельзя: заказ уже закрыт или код уже выдан — отменить нельзя
BAD_KEYКлюч не подошёл: не существует или отозван
ERROR_APIНепредвиденная ошибка на стороне сервиса
Общие ошибки
BAD_ACTIONНеизвестное имя метода в action
BAD_KEYКлюч не подошёл: не существует или отозван
NO_BALANCEНа балансе не хватает денег на заказ
NO_NUMBERSСвободных номеров по этой паре сейчас нет
BAD_COUNTRYСтрана не найдена
BAD_SERVICEСервис не найден
CHANNEL_LIMITДостигнут лимит одновременных активаций
REQUEST_LIMITПревышен лимит запросов на ключ — подождите и повторите
BAD_SOFTWARE_IDНекорректный softId
BAD_STATUSНедопустимое значение status
ERROR_APIНепредвиденная ошибка на стороне сервиса
Коды сервисовполный список — getServicesList
waWhatsApp
tgTelegram
vkVK
goGoogle
fbFacebook
lfTikTok
igInstagram
dsDiscord
drOpenAI
aczClaude
Коды странполный список — getCountries
43Германия
15Польша
16Великобритания
78Франция
86Италия
56Испания
2Казахстан
62Турция
187Соединенные Штаты
22Индия
Ограничения
Запросов на один ключ600 в минуту (≈10 в секунду)
Опрос статусараз в 2–5 сек на активацию