Onlinesim API

v1.1

Общее описание

Это API позволит Вам получить доступ ко всем услугам, предоставляемым Onlinesim:

  • прием SMS от одного конкретного сервиса на виртуальный номер;
  • аренда виртуального номера для получения SMS от нескольких различных отправителей в течение длительного времени;
  • Вы также можете воспользоваться нашими бесплатными номерами, для тестирования функционала сервиса перед покупкой.

Список API запросов

Запросы различаются в зависимости от вида услуги и разбиты по соответствующим подразделам:

Раздел "Профиль"

Данные запросы относятся либо к профилю клиента, либо ко всем предоставляемым Onlinesim услугам одновременно:

  • getBalance - возвращает текущий доступный баланс Вашего профиля, замороженный баланс (зарезервированные средства для активных операций, которые вернутся при их отмене) и информацию о доходе по реферальной программе.
  • webhook - позволяет Вам установить URI, на который будут пересылаться все сообщения с Ваших активных операций . Это касается как SMS с услуги "Прием SMS", так и с "Аренда номера".

Раздел "Прием SMS"

Позволяет получить номер для приёма неограниченного количества SMS от одного выбранного сервиса в течение короткого промежутка времени (для большинства сервисов — 15 минут). Пожалуйста, обратите внимание, что Вы не можете менять сервис во время операции. Для приема SMS от разных сервисов, Вам необходимо будет заказать новые номера с соответствующими параметрами.

  • getTariffs - запрашивает количество доступных номеров, сгруппированных по странам и сервисам (если такие указаны в запросе);
  • getNum - заказывает номер выбранной страны для приема SMS от указанного сервиса;
  • getState - возвращает подробную информацию обо всех активных номерах Вашего профиля (включая полученные ими SMS-сообщения);
  • setOperationRevise - запрашивает следующее полученное этим номером SMS-сообщение из очереди, если первое не содержало необходимый код и/или нужную информацию.
  • setOperationOk - меняет статус операции на успешно выполненную и закрывает её.

Раздел "Аренда"

Эта услуга предполагает, что номер будет использоваться для приема SMS от множества различных отправителей (включая SMS с других мобильных номеров), за исключением запрещенных.

  • tariffsRent - запрашивает список стран с подробной информацией о тарифах арендны;
  • getRentNum - заказывает в аренду номер выбранной страны на указанный срок;
  • extendRentState - продляет аренду выбранного номера;
  • getRentState - возвращает список номеров Вашего профиля с активной арендой и полученными ими сообщениями;
  • closeRentNum - закрывает операцию аренды.

Раздел "Бесплатные номера"

Данное API предоставляет доступ к функционалу по использованию бесплатных номеров Onlinesim, которые можно найти на главной странице сайта.

Вы можете использовать бесплатные номера для тестирования предоставляемых нами услуг, однако просим Вас учесть, что количество доступных стран и номеров ограничено. Также стоит отметить, что сообщения, полученные на бесплатные номера, не являются приватными, они отображаются в соответствующем виджете на главной странице и доступны другим пользователям сайта.

В этом API доступен один универсальный запрос, который позволяет Вам получить доступ ко всей необходимой информации для использования бесплатных номеров:

  • getFreeList - возвращает подробную информацию о списке доступных стран, бесплатных номеров и сообщений, которые они приняли.

Коллекция запросов для Postman доступна здесь:

Run In Postman

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

Каждый запрос содержит свое описание, тип, URL эндпойнта, параметры, примеры тела запроса и ответа. В описании отдельных запросов также может быть указан список специфичных ошибок, получаемых в виде ответа, которые могут появиться при вызове этих методов. Ответы представлены в JSON или TXT формате в зависимости от вызванного метода и результатов.

Обработка исключений

Ниже перечислены общие ошибки: они не привязаны к конкретному эндпоинту и могут встречаться в нескольких методах. Такие ответы всегда приходят с HTTP-статусом 200, а код ошибки передается в поле response:

{
  "response": "ERROR_CODE"
}

Правила обработки

  1. Формат кода — UPPER_SNAKE_CASE
  2. Список кодов не закрыт — он может пополняться
  3. Неизвестный код следует трактовать как обобщенную ошибку и логировать для разбора
Код Категория Описание
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 Прочее Произошла непредвиденная ошибка, повторите запрос позже

Terms of Service: https://onlinesim.io/documentation/offer

Контакты

Лицензия

GNU General Public License, version 3.0

Серверы

https://onlinesim.io

Сервер Onlinesim