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

Главная
API документация

API

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

Краткое описание работы протокола

Метод запроса количества номеров GET_SERVICES

Метод запроса номера GET_NUMBER

Метод доставки смс на сервер SMSBOWER – PUSH_SMS

Метод запроса на завершение активации FINISH_ACTIVATION

Тестирование протокола

Таблицы статусов

Таблица данных

Краткое описание работы протокола

Партнерский протокол предназначен для предоставления номеров и входящих SMS через API напрямую на сервер SMSBOWER .

Во всех запросах используется параметр ключ - KEY. Данный ключ выдается сотрудниками поддержки и доступен в ЛК .

Запросы количества GET_SERVICES, запросы номера GET_NUMBER и завершения активации

FINISH_ACTIVATION посылаются напрямую с нашего сервера на сервер партнера .

Формат url — https://SMSBOWER где SMSBOWER может быть partner.ru:port/SMSBOWER или partner.ru/SMSBOWER.php

GET_SERVICES

GET_NUMBER

PUSH_SMS

FINISH_ACTIVATION

Сервер SMSBOWER посылает запрос на количество номеров по методу GET_SERVICES раз в 10-20 секунд.

Если вы отдаете количество > 0, то вы получите запрос на выдачу номера GET_NUMBER

После запроса GET_NUMBER вы должны выдать номер телефона, подходящий по всем критериям, и передавать нам абсолютно все входящие SMS по методу PUSH_SMS. Это необходимо для того, чтобы мы могли провести четкую и объективную фильтрацию и выдать клиенту нужную SMS под нужный сервис.

По окончании всех необходимых работ с номером вы получите статус 3 по методу FINISH_ACTIVATION. Он означает, что номер был успешно куплен и вам было начислено за него вознаграждение.

Требования

формат запроса/ответа JSON
кодировка UTF-8
обязательно используйте user-agent header в запросах на сервер smsbower
во всех запросах/ответах применяется метод сжатия gzip

Типы полей:

число int - целое значение в диапазоне от -2 147 483 648 до 2 147 483 647
число Uint - целое беззнаковое значение в диапазоне от 0 до 2 147 483 647
число long - целое значение в диапазоне от -9 223 372 036 854 775 808 до 9 223 372 036 854 775 807
число Ulong - целое беззнаковое значение в диапазоне от 0 до 9 223 372 036 854 775 807
число cur - вещественное значение, содержащее до 2 знаков после точки, например 177.77 ;
boolean - литерал принимающий значения true или false
string - строковое значение неограниченной длины

Метод запроса количества номеров GET SERVICES

Данный запрос передает нам информацию о количестве сервисов, которые доступны для продажи .

POST запрос выполняется с сервера SMSBOWER на сервер партнера .

! Обратите внимание: Если у вас GSM модем ограничен в количестве одновременно активных модулей, то вы должны отдавать количество, равное количеству активных модулей.

Состав полей запроса

Поле	Тип	Обязательность	Описание
action	String		GET_SERVICES
key	String		Ключ протокола

Состав полей ответа

Поле	Тип	Обязательность	Описание
status	String		Статус ответа (см. Таблицы статусов)
countryList	Array		Список стран

CountryList

Поле	Тип	Обязательность	Описание
country	String		Статус ответа (см. Status Table)
operatorMap*	Ассоциативный массив		Ключ - оператор (см. Таблица данных), Значение - ассоциативный массив сервисов **

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


            {
     "action": "GET_SERVICES",
     "key": "qwerty123"
}

Скопировано

Пример ответа


            {
     "countryList":
     [
          {
              "country": "russia",
               "operatorMap":
               {
                    "beeline":
                    {
                         "ok": 15,
                         "wa": 20
                    },
                    "megafon":
                    {
                         "vk": 3,
                         "ok": 10
                    }
               }
          },
          {
               "country": "ukraine",
               "operatorMap":
               {
                    "life":
                    {
                         "vk": 0,
                         "wa": 32
                    }
               }
          }
     ],
     "status": "SUCCESS"
}

Скопировано

Метод запроса номера GET_NUMBER

Данный запрос передает нам номер телефона, который мы передаем клиенту .

POST запрос выполняется с сервера SMSBOWER на сервер партнера .

Если в массиве exceptionPhoneSet есть список префиксов, например 44742 и 44740, то вы не должны выдать номер, который начинается на один из этих префиксов. Количество цифр не ограничено размером префикса .

Состав полей запроса

Поле	Тип	Обязательность	Описание
action	String		GET_NUMBER
key	String		Таблица данных
country	String		Таблица данных
service	String		Таблица данных
operator	String		Ключ протокола
sum	Cur		Сумма, которую вы получите за успешно проданный сервис
exceptionPhoneSet	Array		Список префиксов, которые ЗАПРЕЩЕНО

Состав полей ответа

Поле	Тип	Обязательность	Описание
status	String		Статус ответа (см. Таблицы статусов)
number	Ulong		Номер телефона с кодом страны
activationId	Ulong		ID активации в системе партнера
call	String		Flash call доступен для номера
voice	String		Звонок с кодом доступен для номера

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


            {
     "action": "GET_NUMBER",
     "key": "qwerty123",
     "country": "russia",
     "operator": "beeline",
     "service": "tg",
     "sum": "20.00"
}

Скопировано

Пример ответа


            {
      "number": "79156537788",
      "activationId": "36532",
      "status": "SUCCESS",
      "call": "1",
      "voice": "1"
}

Скопировано

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


            {
      "action": "GET_NUMBER",
      "key": "qwerty123",
      "country": "russia",
      "operator": "any",
      "service": "vk",
      "sum": "10",
      "exceptionPhoneSet":
      [
          "7918",
          "79281",
      ]
}

Скопировано

Метод доставки смс на сервер SMSBOWER PUSH_SMS

Данный запрос передает нам номер телефона, который мы передаем клиенту : https://smsbower.online/agent/api/sms

Если вы получаете ответ со статусом SUCCESS, то помечайте в вашей базе смс успешно доставленной и больше не отправляйте смс . Если статус отличный от SUCCESS вернулся, повторяйте запрос пока не получите статус SUCCESS .

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

Поле	Тип	Обязательность	Описание
action	String		PUSH_SMS
key	String		Ключ протокола
smsId	Ulong		ID смс в системе партнера
phone	Ulong		Номер телефона (включая код страны), на который пришла SMS
phoneFrom	String		Наименование отправителя, который направил SMS (может быть как буквенное, так и цифровое выражение)
text	String		Текст SMS
voice	Boolean		Данный запрос является звонком
call	Boolean		Данный запрос является звонком с голосовым кодом

Состав полей ответа

Поле	Тип	Обязательность	Описание
status	String		Статус ответа (см. Таблицы статусов)

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


            {
     "action": "PUSH_SMS",
     "key": "qwerty123",
     "smsId": 1,
     "phone": 447472190082,
     "phoneFrom": "Microsoft",
     "text": "Microsoft access code: 5015"
     "call": "0",
     "voice": "0"
}

Скопировано

Example of a flash call request


            {
     "action": "PUSH_SMS",
     "key": "qwerty123",
     "smsId": 1,
     "phone": 447472190082,
     "phoneFrom": "446756540011",
     "text": "446756540011"
     "call": "1",
     "voice": "0"
}

Скопировано

Example of a voice call request


            {
     "action": "PUSH_SMS",
     "key": "qwerty123",
     "smsId": 1,
     "phone": 447472190082,
     "phoneFrom": "446756540011",
     "text": "12345"
     "call": "0",
     "voice": "1"
}

Скопировано

Состав полей ответа


            {
      "status": "SUCCESS"
}

Скопировано

Метод запроса на завершение активации FINISH_ACTIVATION

Данный запрос мы передаем с сервера SMSBOWER на сервер партнера, чтобы завершить активацию.

POST запрос выполняется с сервера SMSBOWER на сервер партнера.

Управление активацией происходит полностью со стороны SMSBOWER. По независящим от нас причинам мы можем не получить ответ от вас об успешном изменении статуса. Поэтому, если SMSBOWER повторно шлет запрос завершения активации, вы должны проверить существование активации у вас по ID и ,если активация у вас существует, то прислать статус SUCCESS в запросе.

Состав полей запроса

Поле	Тип	Обязательность	Описание
action	String		FINISH_ACTIVATION
key	String		Ключ протокола
activationId	Ulong		ID активации, полученный во втором запросе
status	Unit		Статус ответа (см. Таблицы статусов)

Состав полей ответа

Поле	Тип	Обязательность	Описание
status	String		Статус ответа (см. Таблицы статусов)

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


            {
     "action": "FINISH_ACTIVATION",
     "key": "qwerty123",
     "activationId": 100,
     "status": 3,
}

Скопировано

Пример ответа


            {
      "status": "SUCCESS"
}

Скопировано

Тестирование протокола

После реализации протокола, вам необходимо обратиться в нашу техническую поддержку, предоставить URL, и наши сотрудники проведут тестирование. Если проверка пройдена по всем параметрам, то вы будете успешно подключены к SMSBOWER .

Одновременная выдача номера

Вы должны обрабатывать одновременные запросы должным образом и не выдавать номера повторно. Например, если вы отдаете 100 номеров на Telegram United Kingdom, то если SMSBOWER делает одновременно 100 запросов на Telegram United Kingdom, то сервер партнера должен выдать 100 уникальных номеров. Если номер выдан несколько раз, то тест провален .

Корректное завершение активации

Изменение статуса активации происходит сугубо на стороне SMSBOWER. Вы не должны самостоятельно завешать активацию.

Проверка выдачи SMS

Как только вы получили SMS ее необходимо сразу же направить на сервер SMSBOWER. Если вам был отправлен статус SUCCESS, то вы не должны больше направлять эту SMS. Если же вы получаете иной статус, то вам следует повторять запрос раз в 10-20 секунд. Если же SMS будет выдана повторно после получения статуса SUCCESS, то тест провален .

Проверка типов полей

Тщательно проверяйте типы полей, которые были указаны в данной документации. Если данное условие было нарушено, то тестирование провалено .

Проверка наличия кода страны в телефоне номера

Выдача номера телефона должна производиться сугубо в цифровом виде и с кодом страны .

Проверка времени выдачи номера

Вы должны выдавать номер с задержкой менее 3 секунд. Если же задержка более 3 секунд , то тестирование провалено .

Проверка количества номеров

Если в запросе на количество номеров вы показываете количество 1000, а при одновременном запросе номеров выдаете только 100, то тестирование провалено .

Проверка на исключения

Если некорректно обрабатываете исключения для выдачи номера, то тестирование провалено .

Статус ответа

Статус	Описание
SUCCESS	Запрос выполнен успешно
ERROR	Ошибка при выполнении запроса. Поле ERROR должно быть заполнено описанием
NO_NUMBER	Нет номеров. Возвращается только на запрос номера.

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

Статус	Описание
1	Выдача номера под данный сервис запрещена
3	Активация была успешно продана. Вы получили вознаграждение
4	Активация была отменена*
5	Активация была возвращена. Покупателю были возвращены деньги за активацию. Возможно данный номер был уже зарегистрирован ранее, и на номере стоит двухфакторная аутентификация

* Описание работы с механизмом отмены: Если номер был отменен 5 раз, то данный номер вы не должны нам выдавать снова. Возможно данный номер не подошел клиенту или был уже зарегистрирован под данный сервис.

Успешный ответ на запрос


            {
     "status": "SUCCESS",
     //информация
}

Скопировано

Ответ при ошибке


            {
      "status": "ERROR",
      "error": "описание ошибки"
}

Скопировано

Таблица данных

Список стран

Полный список стран с наименованиями и ID находится по ссылке https://smsbower.org /api#countries.

Список операторов

На данный момент разбивка по операторам в в разработке, поэтому следует передавать значение any. Как только будет реализован данный функционал, мы сообщим вам в чате технической поддержки .

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

Полный список сервисов с наименованиями и ID находится по ссылке https://smsbower.org /api#services

Example Postman

Link