Вы находитесь на странице: 1из 18

Агентский


протокол SMSHUB
Версия от 13 сентября 2018 года


Страница 1 из 18
Содержание
Содержание 2

Описание 3

Общий алгоритм действий на примере сервиса vk (Вконтакте) 4

1. Запрос количества доступных номеров 5

2. Запрос номера 7

3. Завершение активации 8

4. Доставка смс на сервер smshub 9

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

Приложение 1. Список стран 11

Приложение 2. Список операторов 13

Приложение 3. Список сокращенного наименования сервисов 15

Приложение 4. Статус активации 17

Приложение 5. Статус запроса 18

Страница 2 из 18
Описание
Запросы 1-3 посылаются с сервера smshub на сервер агента. Допускается
использование http или https. В каждом запросе присутствует параметр key (ключ). Ключ
можно получить в личном кабинете.

URL - https://SMSHUB,

где SMSHUB может быть agent.ru:port/smshub или agent.ru/smshub.php

Формат запроса/ответа JSON, кодировка UTF-8.

В запросах на smshub обязательно использовать User-Agent.

В запросах/ответах применяется метод сжатия gzip.

Страница 3 из 18
Общий алгоритм действий на примере сервиса vk
(Вконтакте)
1. Один раз в 10-20 секунд сервер smshub будет посылать запрос количества
доступных номеров на ваш сервер (Запрос 1).

2. Далее, если вы возвращаете количество vk не ноль, то в порядке очереди вам придет


запрос на номер (Запрос 2).

3. К примеру, вы выдали номер 79281234567 под vk. С этого момента вам нужно начать
присылать все смс на сервер smshub, приходящие на номер 79281234567 (Запрос 4). 

Почему все? Принятие решений, что эта смс под вк, а другая под одноклассники
должно быть в одном месте. У нас постоянно обновляемый фильтр по смс, и его
легче поддерживать в актуальном состоянии когда он в одном месте.

4. После работы с номером мы отправим вам статус завершения активации. Если вы


получили статус 3 - это означает, что пользователь успешно получил смс и в кабинете
smshub вам было начислено вознаграждение. По остальным статусам прочтите
Приложение 4.


Страница 4 из 18
1. Запрос количества доступных номеров
POST запрос выполняется с сервера smshub на сервер агента.

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

Поле Тип Обязательность Описание/Значение

action Строка Обязательный GET_SERVICES

key Строка Обязательный Ключ протокола

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

Поле Тип Обязательность Описание

status Строка Обязательный Статус ответа.

Приложение 5

countryList Список Обязательный Список стран

countryList:

Поле Тип Обязательность Описание

country Строка Обязательный Приложение 1

operatorMap Ассоциативный массив Обязательный Ключ - оператор


Приложение 2,
значение -
ассоциативный массив
сервисов*

*Ассоциативный массив сервисов: ключ - краткое наименование сервиса


(Приложение 3), значение - количество номеров под сервис (тип-int).

ВАЖНО. Необходимо возвращать актуальное количество одновременно доступных


симкарт. К примеру, если у вас симбанк на 512, а gsm модулей всего 60, то возвращать
нужно количество 60, а не 512. Если вы нарушите данное условие, система автоматически
заблокирует получение номеров от вас на 30 минут.

Страница 5 из 18
Пример запроса:

"action": "GET_SERVICES",

"key": "123"

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

"countryList": [

"country": "russia",

"operatorMap": {

"beeline": {

"vk": 10,

"ok": 15,

"wa": 20

},

"megafon": {

"vk": 0,

"ok": 10,

"wa": 32

} }

},

"country": "ukraine",

"operatorMap": {

"life": {

"vk": 0,

"ok": 10,

"wa": 32

],

"status": "SUCCESS"

Страница 6 из 18
2. Запрос номера
POST запрос выполняется с сервера smshub на сервер агента.

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

Поле Тип Обязательность Описание/Значение

action Строка Обязательный GET_NUMBER

key Строка Обязательный ключ протокола

country Строка Обязательный Приложение 1

service Строка Обязательный Приложение 3

operator Строка Обязательный Приложение 2

sum Число Обязательный Сумма, которую вы


получите за успешно
проданный сервис

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

Поле Тип Обязательность Описание

status Строка Обязательный Статус ответа.

Приложение 5

number Число Обязательный Номер телефона с


кодом страны

activationId Число Обязательный Id активации в системе


агента

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

"country": "russia",

"operator": "mts",

"service": "vk",

"sum": 20.00,

"action": "GET_NUMBER",

"key": "1234"

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

"number": 79281234567,

"activationId": 355,

"status": "SUCCESS"

Пример ответа в случае отсутствия номеров:

"status": "NO_NUMBERS"

Страница 7 из 18
3. Завершение активации
POST запрос выполняется с сервера smshub на сервер агента.

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

Поле Тип Обязательность Описание/Значение

action Строка Обязательный FINISH_ACTIVATION

key Строка Обязательный ключ протокола

activationId Число Обязательный Id  активации,


полученный во втором
запросе

status Число Обязательный Статус активации.

Приложение 4

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

Поле Тип Обязательность Описание

status Строка Обязательный Статус ответа.

Приложение 5

*Управление активацией происходит полностью со стороны smshub. По


независящим от нас причинам (проблемы с сетью) мы можем не получить ответ от вас об
успешном изменении статуса. Поэтому, если smshub повторно шлет статус завершения
активации, вы должны проверить существование такой активации у вас по id и если
активация у вас существует, то прислать status SUCCESS.

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

"activationId": 100,

"status": 3,

"action": "FINISH_ACTIVATION",

"key": "123"

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

"status": "SUCCESS"

Страница 8 из 18
4. Доставка смс на сервер smshub
POST запрос выполняется с сервера агента на сервер smshub на адрес

http://smshub.org:2052/json

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

Поле Тип Обязательность Описание/Значение

action Строка Обязательный PUSH_SMS

key Строка Обязательный ключ протокола

smsId Число Обязательный Id смс в системе агента

phone Число Обязательный Номер телефона с


кодом страны, на
который пришла смс

phoneFrom Строка Обязательный Номер телефона


откуда пришла смс
(может быть буквенное
наименование)

text Строка Обязательный Текст смс

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

Поле Тип Обязательность Описание

status Строка Обязательный Статус ответа.

Приложение 5

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

"smsId": 1,

"phoneFrom": "Vk",

"phone": 79281234567,

"text": "VK: 33708 - ваш код для регистрации ВКонтакте»,

"action": «PUSH_SMS",

"key": "12345"

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

"status": "SUCCESS"

Если вы получаете ответ со статусом SUCCESS, то у себя в базе помечайте смс


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


Страница 9 из 18
Тестирование протокола
ОБЯЗАТЕЛЬНО К ПРОЧТЕНИЮ

После реализации протокола разработчики smshub будут его тестировать.

Для этого нам нужен ваш url.

Тесты, которые мы будем проводить:

1. Одновременная выдача номеров под один и тот же сервис. Самый важный тест. 

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

К примеру, система отправит 30 запросов с одними и теми же критериями: russia,
megafon, vk. Если вы выдали номер повторно - тест провален.

2. Корректная обработка запроса завершения активации. 



Управление активацией происходит ТОЛЬКО со стороны smshub. По независящим от
нас причинам (проблемы с сетью) мы можем не получить ответ от вас об успешном
изменении статуса. Поэтому, если smshub повторно шлет статус завершения
активации, вы должны проверить существование такой активации у вас по id и если
активация у вас существует, то прислать status SUCCESS. 


Также, вы НЕ должны самостоятельно завершать активацию на вашей стороне.
Только запрос завершения от smshub должен завершить активацию на вашей
стороне.

3. Тест СМС. 

После того, как смс попала в вашу базу, вы должны как можно скорей переслать её
нам. Пришла смс - сразу отправляйте к нам.

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

Если на запрос отправки смс вы получили ответ со статусом ERROR, то такую смс вы
должны прислать нам еще раз пока не получите ответ со статусом SUCCESS..

Если вы пришлете одну и туже смс после того как мы ответим вам статусом SUCCESS
- тест провален.

4. Тип полей. 

Внимательно проверьте типы полей, которые вы посылаете по протоколу. Если в
описании протокола сказано, что поле числового типа, а вы присылаете smsId: «123» -
тест провален.

5. Номер телефона должен быть с кодом страны. 



В запросе номера телефона поле number и в запросе доставки смс поле phone
должно быть ЧИСЛОВОЕ и С КОДОМ страны.

6. Время выдачи номера от вас должно быть минимальное. 



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

7. Количество номеров, возвращаемое запросом 1, должно отражать


действительность. Если вы возвращаете 100 vk, а на самом деле их 30, то 70
запросов вернутся с ответом NO_NUMBERS - тест провален.


Страница 10 из 18
Приложение 1. Список стран
RU country (Значение используется в протоколе)

Россия russia

Украина ukraine

Казахстан kazakhstan

Китай china

Филиппины philippines

Мьямна myanmar

Индонезия indonesia

Малайзия malaysia

Кения kenya

Танзания tanzania

Вьетнам vietnam

Киргизия kyrgyzstan

USA usa

Израиль israel

Гонконг hongkong

Польша poland

Англия england

Мадагаскар madagascar

Демократическая Республика Конго dcongo

Нигерия nigeria

Макао macao

Египет egypt

Индия india

Ирландия ireland

Камбоджа cambodia

Лаос laos

Гаити haiti

Кот д'Ивуар ivory

Гамбия gambia

Страница 11 из 18
RU country (Значение используется в протоколе)

Сербия serbia

Йемен yemen

Южная Африка southafrica

Румыния romania

Колумбия colombia

Эстония estonia

Если вы предоставляете страну, которой нет у нас в списке, напишите в


техподдержку. Обязательно решим этот вопрос.


Страница 12 из 18
Приложение 2. Список операторов
Наименование Используется в протоколе

Мегафон megafon

Билайн beeline

Теле2 tele2

Мтс mts

Ростелеком rostelecom

Актив activ

Алтел altel

Айва aiva

Сбер sber

Yota yota

Sim sim simsim

Лайф life

Киевстар kyivstar

Оранж orange

О (киргизский оператор) o!

Utel utel

Etisalat etisalat

Globacom glo

Mtn mtn

Vodacom vodacom

Vodafone vodafone

Natcom Global natcom

Comium comium

Q CELLS qcell

Gamcel gamcel

ТТК ttk

Mobtel mobtel

Vip vip

Sabafon sabafon

Страница 13 из 18
Наименование Используется в протоколе

Claro claro

Movistar movistar

Tigo tigo

Авантел avantel

Exito exito

ETB etb

Virgin virgin

Goodline goodline

Lebara lebara

Любой* any

Если вы предоставляете оператора, которого нет у нас в списке, напишите в


техподдержку. Обязательно решим этот вопрос.

*«Любой» оператор нужно возвращать только в случае, если у вас нет возможности
сделать разбивку по операторам по конкретной стране.

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


этой стране нельзя.

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


для этой страны будет нельзя без обращения в техподдержку.

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


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


Страница 14 из 18
Приложение 3. Список сокращенного наименования
сервисов
Используется в протоколе Наименование

vk Вконтакте

ok Одноклассники

wa Whatsapp

vi Viber

tg Telegram

wb WeChat

go Google,youtube,Gmail

av avito

fb facebook

tw Twitter

ub Uber

qw Qiwi

gt Gett

sn OLX

ig Instagram

ss SeoSprint

ym Юла

ma Mail.ru

mm Microsoft

uk Airbnb

me Line messenger

mb Yahoo

we ДругВокруг

bd Пятерочка

kp HQ Trivia

dt WOG

ya Яндекс

mt Steam

Страница 15 из 18
Используется в протоколе Наименование

oi Tinder

fd Mamba

zz Drom.ru

kt KakaoTalk

pm AOL

tn LinkedIN

ot Любой другой

Страница 16 из 18
Приложение 4. Статус активации
Используется при запросе завершения активации.

Статус Значение

1 Больше не выдавать номер под данный сервис

3 Успешно продана

4 Отменена

5 Возвращена

Статус 1 - Отмена номера. Номер выдавать больше не нужно. Возможная причина


отмены - номер уже был продан под данный сервис ранее.

Статус 3 - Номер успешно продан под сервис. Пользователь успешно получил смс и
вам было начислено вознаграждение в кабинете smshub.

Статус 4 - Отмена номера. Такой номер вы можете выдать нам еще 3 раза (то есть
всего 4 раза если его отменяли статусом 4).

Возможная причина отмены - номер не подошел пользователю или был уже


зарегистрирован на данный сервис ранее.

Статус 5 - Возвращение денег пользователю за номер. Бывают случаи, когда за


активацию пользователю возвращаются средства. В таком случае мы оповестим вас об
этом статусом 5.

Страница 17 из 18
Приложение 5. Статус запроса
Значения поля status в ответах на запросы:

status Описание

SUCCESS Запрос выполнен успешно

ERROR Ошибка при выполнении запроса.

Нужно заполнить поле error описанием ошибки.

NO_NUMBERS Нет номеров.

Вы можете вернуть статус только на запрос


получения номера.

Общий формат успешного ответа на запрос:

"status": "SUCCESS",

//данные

Общий формат ответа при возникновении ошибки:

"status": "ERROR",

"error": "описание ошибки"

Страница 18 из 18