Компоненты

Схемы

commonErrorResponse

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	Код ошибки в формате UPPER_SNAKE_CASE, возвращается в поле response при HTTP-статусе 200. Список кодов не является закрытым и может пополняться. Неизвестный код следует трактовать как обобщенную ошибку и логировать для разбора. Известные коды, сгруппированные по смыслу: Параметры запроса - UNDEFINED_COUNTRY — некорректное значение параметра страны. Доступные значения — в списке стран; - UNDEFINED_DAYS — некорректный срок аренды или продления. Допустимые значения — в объекте days ответа tariffsRent - для базовых сроков аренды, и в объекте extend ответа getRentState - для продления; - ERROR_NO_SERVICE — некорректное значение параметра сервиса. Доступные значения — в списке сервисов. Состояние и доступность - NO_NUMBER — нет доступных номеров с указанными параметрами. Повторите запрос позже или попробуйте другую страну; - WARNING_LOW_BALANCE — недостаточно средств на балансе. Аккаунт и доступ - ACCOUNT_BLOCKED — аккаунт заблокирован; - API_ACCESS_DISABLED — доступ к API отключён в настройках профиля (см. тумблер API включено); - API_ACCESS_IP — IP-адрес отсутствует в allowlist (см. Доступ с IP). Авторизация - ERROR_WRONG_KEY — некорректный API-ключ; - ERROR_NO_KEY — API-ключ отсутствует. Лимиты запросов - INTERVAL_CONCURRENT_REQUESTS_ERROR — превышена допустимая частота или количество одновременных запросов. Маршрутизация - REQUEST_NOT_FOUND — имя вызываемого метода некорректно или отсутствует. Прочее - TRY_AGAIN_LATER — непредвиденная ошибка

tariffsCountry

Тип: object

Название	Тип	Обязательный	Описание
name	string	✓	Название страны для отображения в интерфейсе
original	string	✓	Имя страны, необходимое при заказе номера. Доступные значения указаны в <ответе >
code	integer	✓	Международный телефонный код страны
pos	integer	✓	Позиция страны в списке по умолчанию
other	boolean	✓	Доступность сервиса "Другие сайты" для этой страны
new	boolean	✓	Служебный флаг для обозначения недавно добавленной страны
enable	boolean	✓	Служебный флаг для обозначения возможности заказа номера страны

tariffsService

Тип: object

Название	Тип	Обязательный	Описание
id	integer	✓	ID сервиса (место в списке по умолчанию, служебное поле)
count	integer	✓	Количество доступных номеров для данного сервиса
price	string	✓	Цена сервиса. При использовании locale_price — в валюте баланса
service	string	✓	Полное название сервиса
slug	string	✓	Короткий ключ сервиса, необходимый для заказа

getTariffsSuccessResponse

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	"1", если запрос был выполнен успешно, либо выведет сообщение об ошибке. Обработку общих ошибок смотри в разделе Обработка исключений
countries	object	✓	Карта стран. Ключи — коды стран с префиксом _ (например, _7, _380)
services	object	✓	Карта сервисов для выбранной страны. Ключи — slug сервисов с префиксом _ (например, _vkcom, _telegram)
favorite_countries	object		Избранные страны (пусто, если клиент не авторизован)
favorite_services	object[]		Избранные сервисы (пусто, если клиент не авторизован)
page	integer		Текущая страница пагинации сервисов
country	integer		Выбранный код страны (совпадает со значением в запросе)
filter	string		Строка фильтра из запроса
end	boolean		true, если сервисов на следующей странице больше нет (конец списка)
favorites	object		Служебное поле; обычно пустой объект, если избранных сервисов нет

getTariffsResponse

Успешный ответ на getTariffs или общая ошибка

operationIdSuccessResponse

Тип: object

Название	Тип	Обязательный	Описание
response	integer	✓	1, если запрос был выполнен успешно, либо выведет сообщение об ошибке. Обработку общих ошибок смотри в разделе Обработка исключений
tzid	integer	✓	ID операции

getNumDetailedSuccessResponse

getNumResponse

getStateOperationItem

Тип: object

Название	Тип	Обязательный	Описание
tzid	integer	✓	ID операции
response	string	✓	Статус операции: - TZ_INPOOL — ожидание выдачи номера - TZ_NUM_WAIT — номер выдан, ожидание SMS - TZ_NUM_ANSWER — SMS получено - TZ_OVER_OK — операция завершена - ERROR_NO_ITEMS — операция неудачна / номер не выдан
number	string		Номер телефона в международном формате со знаком +
country	integer	✓	Код страны без +
service	string	✓	Slug сервиса
sum	integer	✓	Стоимость услуги
time	integer	✓	Секунд до конца операции
msg	string | string[]
form	string	✓	Вид приёма (для приёма SMS всегда index)
guard_interval_remaining_seconds	integer		Секунд до разрешения досрочного закрытия без SMS. Возвращается только при передаче параметра number в запросе

getStateSuccessArrayResponse

Список активных операций. Пустой массив, если их нет (в некоторых случаях сервер возвращает ошибку — см. компоненты commonErrorResponse и getStateMethodError в отдельном разделе)

Тип: array

getStateSuccessWrappedResponse

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	Код успешного выполнения запроса
list	object[]	✓	Список активных операций

getStateMethodError

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	Код ошибки, специфичный для метода: - ERROR_NO_OPERATIONS — нет активных операций или такого tzid не существует - ERROR_UNDEFINED — неопределенная ошибка

getStateResponse

Успешный ответ (обычный массив или в обертке c полем response), либо ошибка (специфичная для метода или общая)

setOperationReviseSuccessResponse

Тип: object

Название	Тип	Обязательный	Описание
tzid	integer	✓	ID операции (тот же, что был передан в запросе)
response	string	✓	"1" — запрос выполнен успешно, указатель сдвинут на следующее SMS

setOperationReviseMethodError

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	Код ошибки, специфичный для метода: - ERROR_NO_TZID — параметр tzid не был передан

setOperationReviseResponse

Успешный ответ, специфичная ошибка метода или общая ошибка

setOperationOkBanNotAppliedResponse

Тип: object

Название	Тип	Обязательный	Описание
response	integer	✓	0 — передан ban=1, но SMS уже есть, поэтому блокировка номера не может быть применена

setOperationOkMethodError

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	Код ошибки, специфичный для метода: - ERROR_NO_TZID — параметр tzid не был передан - ERROR_WRONG_TZID — операции нет или она принадлежит другому аккаунту - NO_COMPLETE_TZID — слишком рано закрывать операцию без SMS. Защитный интервал по умолчанию — 120 с; для WhatsApp — 300 с - INTERVAL_CONCURRENT_REQUESTS_ERROR — повторное закрытие той же tzid чаще, чем раз в 5 секунд - NO_NUMBER — партнёр/выдача не подтвердила закрытие

setOperationOkResponse

Успешное закрытие операции, бан не применен (response: 0), специфичная ошибка метода или общая ошибка

rentCountryTariff

Тип: object

Название	Тип	Обязательный	Описание
code	integer	✓	Код страны (согласно списку стран)
enabled	boolean	✓	Флаг доступности аренды номеров этой страны (true - аренда доступна)
name	string	✓	Slug страны (например, russia, moldova)
new	boolean	✓	Служебный флаг для обозначения недавно добавленной страны
position	integer	✓	Позиция страны в списке по умолчанию
count	object	✓	Остаток номеров по сроку аренды. Ключи — сроки в днях (1, 3, 7, 15, 30), значения — количество
days	object	✓	Цена по тем же срокам аренды. Ключи — сроки в днях, значения — цены
extend	integer	✓	Количество номеров с возможностью продления
confirm	boolean		true — средства списываются сразу, автовозврата при отсутствии SMS нет (в кабинете перед покупкой показывается дополнительное подтверждение)

tariffsRentAllCountriesResponse

Карта стран. Ключи — коды стран в виде строк (например, "7", "46", "373"), значения — объекты rentCountryTariff

Тип: object

tariffsRentEmptyResponse

Пустой массив, возвращается при неизвестной стране

Тип: array

tariffsRentOAuthScopeError

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	Ошибка возвращается, когда OAuth-токен не содержит scope rent-scope: "Invalid scope(s) provided: rent-scope"

tariffsRentResponse

Успешный ответ (все страны, одна страна или пустой массив) или ошибка (специфичная для метода или общая)

rentMessage

Тип: object

Название	Тип	Обязательный	Описание
id	integer	✓	ID сообщения
service	string	✓	Номер или имя отправителя
text	string	✓	Текст SMS-сообщения
code	string	✓	Цифровой код из SMS-сообщения
created_at	string	✓	Дата и время получения SMS-сообщения

rentMessagesPagination

Тип: object

Название	Тип	Обязательный	Описание
current_page	integer	✓	Текущая страница сообщений. Сообщения отсортированы в обратном хронологическом порядке и сгруппированы по страницам (первая страница содержит последние сообщения)
data	object[]	✓	Список сообщений на текущей странице
from	integer	✓	Номер первого сообщения на этой странице
last_page	integer	✓	Номер последней страницы с полученными SMS
per_page	integer	✓	Количество сообщений на одной странице
to	integer	✓	Номер последнего сообщения на этой странице
total	integer	✓	Общее количество полученных этим номером сообщений

rentItem

Тип: object

Название	Тип	Обязательный	Описание
status	integer	✓	Статус аренды: - 0 — ожидание подтверждения (SMS должна прийти в течение 20 минут, иначе операция будет отменена) - 1 — аренда активна - 2 — DEPRECATED номер отключен - 3 — DEPRECATED ошибка аренды - 4 — номер заморожен
messages	object | object[]	✓	Список SMS. Возвращается объектом пагинации, когда pagination включена (по умолчанию), либо плоским массивом при pagination=false
country	integer	✓	Код страны без + (например, 7, 46, 373)
rent	integer	✓	Срок аренды в днях (значение, переданное в days)
extension	integer	✓	Доступность продления: - 0 — продление недоступно - 1 — продление доступно - 2 — автопродление
checked_time	string	✓	Дата и время, когда номер был выдан
sum	number	✓	Стоимость аренды
number	string	✓	Выданный виртуальный номер без кода страны
tzid	integer	✓	ID операции. Используйте его для получения информации о ней, продления или закрытия
time	integer	✓	Оставшееся время до конца текущего окна, в минутах
days	integer	✓	Оставшееся время до конца текущего окна, в днях
hours	integer	✓	Оставшееся время до конца текущего окна, в часах
extend	object	✓	Цены продления по срокам (дни → цена)
checked	boolean	✓	Подтверждена ли аренда SMS. false сразу после выдачи
reload	integer | null	✓	Доступность перезагрузки номера: - 0 — перезагрузка недоступна - 1 — перезагрузка доступна
day_extend	integer	✓	Цена продления аренды на 1 день
m_ext	boolean	✓	Служебный флаг алгоритма продления
freeze	boolean	✓	Заморожен ли номер. Если true, аренда приостановлена до разморозки

getRentNumSuccessResponse

Тип: object

Название	Тип	Обязательный	Описание
response	integer	✓	Номер в аренду успешно выдан
item	object	✓

getRentNumResponse

extendRentStateSuccessResponse

Тип: object

Название	Тип	Обязательный	Описание
response	integer	✓	Аренда виртуального номера была успешно продлена
item	object	✓

extendRentStateResponse

Успешное продление аренды или общая ошибка. Ошибка TRY_AGAIN_LATER также может возвращаться при передаче некорректных значений в параметрах tzid и days, либо при попытке продления уже завершенной операции

getRentStateSuccessResponse

Тип: object

Название	Тип	Обязательный	Описание
response	integer	✓	Код выполнения запроса: 1 - при успехе. Пустой list — не ошибка (нет активных аренд или неизвестный tzid)
list	object[]	✓	Список активных операций аренды (может быть пустым)

getRentStateResponse

Успешный ответ или общая ошибка. OAuth-токен без rent-scope возвращает ошибку scope — см. компонент tariffsRentOAuthScopeError

closeRentNumSuccessResponse

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	"1" — операция аренды успешно закрыта. Возвращается только статус; номер, SMS и баланс не передаются

closeRentNumMethodError

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	Код ошибки, специфичный для метода: - ERROR_NO_OPERATIONS — нет активной аренды с таким tzid у этого аккаунта - NO_COMPLETE_TZID — закрытие во время защитного интервала недоступно: пока нет SMS и не прошло 120 секунд с момента старта (аренда еще в ожидании активации); также всегда возвращается при попытке закрыть арендный номер США - TRY_AGAIN_LATER — закрытие не прошло, повторите запрос позже

closeRentNumResponse

Успешное закрытие операции аренды, специфичная или общая ошибка

getBalanceBaseSuccessResponse

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	Код выполнения запроса: 1 - при успехе
balance	string	✓	Текущий доступный баланс (в валюте профиля)
zbalance	number	✓	Замороженный баланс — средства, зарезервированные под активные операции. Возвращаются на основной баланс при отмене операций

getBalanceWithIncomeSuccessResponse

getBalanceResponse

Успешный ответ (базовый или с деталями дохода по реферальной прогремме — в зависимости от параметра запроса income) или общая ошибка

freeListCountry

Тип: object

Название	Тип	Обязательный	Описание
country	integer	✓	Код страны (согласно списку стран)
country_text	string	✓	Человекочитаемое название страны (с учетом локали)
country_original	string		Slug страны (например, russia, moldova)

freeListNumber

Тип: object

Название	Тип	Обязательный	Описание
country	integer	✓	Код страны без + (согласно списку стран)
country_original	string		Slug страны
data_humans	string	✓	Человекочитаемое время с момента размещения номера (например, «6 дней назад»)
full_number	string	✓	Полный номер телефона в международном формате со знаком +
is_archive	boolean	✓	Находится ли номер в архиве. Для живых номеров всегда false

freeListMessage

Тип: object

Название	Тип	Обязательный	Описание
text	string	✓	Текст SMS
in_number	string	✓	Имя или номер отправителя
my_number	integer	✓	Бесплатный номер, получивший SMS (без кода страны)
created_at	string	✓	Дата и время получения сообщения
data_humans	string	✓	Человекочитаемое время с момента получения сообщения

freeListMessagesPagination

Тип: object

Название	Тип	Обязательный	Описание
current_page	integer	✓	Номер текущей страницы
data	object[]	✓	Список сообщений на текущей странице
per_page	integer	✓	Количество сообщений на странице
total	integer	✓	Общее количество SMS, полученных выбранным номером
last_page	integer	✓	Номер последней страницы
number	string	✓	Выбранный бесплатный номер (без кода страны)
country	integer	✓	Код страны выбранного номера

getFreeListSuccessResponse

Тип: object

Название	Тип	Обязательный	Описание
response	integer | string	✓	1 — запрос выполнен (даже если бесплатные номера отсутствуют)
countries	object[]	✓	Страны с доступными бесплатными номерами
numbers	object	✓	Карта бесплатных номеров. Ключи — номера без кода страны (например, "9915584911"), значения — объекты FreeListNumber
messages	object	✓
ignore	string	✓	HTML-блок: текст публичной оферты и список запрещенных отправителей
content	string | null	✓	SEO-контент страницы или null, если параметр with_content не передан

freeListOAuthScopeError

Тип: object

Название	Тип	Обязательный	Описание
response	string	✓	Возвращается, когда OAuth-токен не содержит scope free-scope: текст про invalid scope

getFreeListResponse

Успешный ответ, ошибка OAuth scope или общая ошибка

days

Дни аренды, допустимые значения — в объекте days ответа tariffsRent для сроков изначальной аренды и в объекте extend ответа getRentState для сроков продления аренды;

Тип: integer