Сервер — ресурс на котором размещен портал oll.tv.
Оператор (провайдер) — телеком-оператор, с которым есть договорные отношения.
Подписка типа бандл (Bundle) – подписка, включаемая оператором пользователю.
Подписка типа VAS – подписка, которую пользователь покупает самостоятельно через свой личный кабинет на портале oll.tv.
Подписка для доступа к основной услуге — подписка типа бандл, предоставляющая доступ к просмотру контента на портале oll.tv.
Подписка для доступа с доп. экрана — подписка типа бандл, не дающая доступ к контенту, а предоставляющая пользователю возможность привязать дополнительное устройство; активация возможна только после подписки на основную услугу и одновременно может быть активировано несколько подписок данного типа.
Методы, возвращающие блоки данных, вызываются при помощи HTTP GET запросов на сервер. Сервер, в свою очередь, возвращает данные в виде JSON.
Методы, передающие данные от клиента к серверу, вызываются при помощи HTTP POST, данные в POST запросе передаются в прямом виде, ответ же кодируется в JSON.
Корневая папка для запросов на сервер находится по адресу: ispAPI.
Для тестирования используется сервер dev.oll.tv. Доступ на него возможен только для предоставленных ip-адресов.
Первый запрос должен прийти на метод авторизации. Используя логин и пароль для ispAPI, клиентское приложение получает уникальный хеш, который должно передавать при последующих обращениях к серверу.
Пример:
Запрос:
POST /ispAPI/auth2/
login=isp#1&password=password#1
Ответ:
{
"status": "0",
"hash": "o32xf3oddksk33"
}
После успешной авторизации доступны остальные методы API, с обязательной передачей хеша, используя ключ "hash", например:
GET /ispAPI/emailExists?hash=o32xf3oddksk33
Ответ представляет собой объект в JSON, в котором обязательно присутствует элемент status, значение которого в случае успешного выполнения запроса равно нулю, а в случае ошибки — коду ошибки. Второй элемент в общем случае — data (где это не так — указано отдельно). Ответ, также, может содержать поле warnings со списком предупреждений (например, об отсутствии в запросе каких-либо полей или неправильном их значении).
Если же какой-либо метод не может быть выполнен по той или иной причине сервер возвращает объект в JSON с полями status и message, где message – описание ошибки (перечень возможных ошибок описан в одноимённом разделе данной документации).
В случае, если хеш ещё не выдан или не может быть верифицирован, элемент status дублируется элементом id для совместимости с ispAPI версии 1.х.х.
auth2 - http://oll.tv/ispAPI/auth2
Принимает два параметра, login и password.
Возвращает хеш (элемент объекта hash).
Возможные коды ошибок: 111, 112, 113.
emailExists - http://oll.tv/ispAPI/emailExists
Принимает один параметр – email.
Возвращает 1 если email существует в базе, и 0 – если нет.
Возможные коды ошибок: 109, 110, 200, 201.
accountExists - http://oll.tv/ispAPI/accountExists
Принимает один параметр – account – аккаунт абонента на стороне провайдера.
Если такой абонент уже есть у нас в базе – будет возвращён объект с информацией по этому абоненту, в противном случае будет возвращен 0.
Возможные коды ошибок: 109, 110, 200.
addUser - http://oll.tv/ispAPI/addUser
Принимает следующие параметры, из которых первые два – обязательны:
email
account
birth_date (допускаются форматы YYYY-MM-DD или DD.MM.YYYY)
gender (значения M или F, по-умолчанию: M)
firstname (по-умолчанию: «Гость»/«Гостья»)
password (если не задан — сгенерируется автоматически)
lastname
phone (пример: 0501234567)
region
receive_news (значения 1 или 0, по-умолчанию: 1)
send_registration_email (слать ли пользователю сообщение о регистрации, значения 1 или 0, по-умолчанию: 1)
index (почтовый индекс или другой идентификатор региональной привязки абонента)
Возвращает ID созданного пользователя.
Возможные коды ошибок: 109, 110, 115, 116, 120, 200, 301.
getUserList - http://oll.tv/ispAPI/getUserList
Принимает следующие необязательные параметры:
offset
limit — (не больше 1000, по умолчанию равно 1000)
Метод возвращает список пользователей oll.tv (с подробной информацией), которые "привязаны" к провайдеру.
Возможные коды ошибок: 109, 110, 200.
changeAccount - http://oll.tv/ispAPI/changeAccount
После выполнения данного метода, если пользователь не был ранее привязан к провайдеру, пользователю на почту будет выслано письмо с уведомлением о том, что он будет привязан к провайдеру, и ссылкой, перейдя по которой, он завершит процедуру привязки к провайдеру.
Принимает следующие обязательные параметры:
email — кому изменить
account — новое значение
Не возвращает ничего кроме статуса.
Возможные коды ошибок: 109, 110, 200, 201, 404, 505.
deleteAccount - http://oll.tv/ispAPI/deleteAccount
Принимает один обязательный параметр:
account или email или id или ds_account
Не возвращает ничего кроме статуса.
Возможные коды ошибок: [**109**](#error-109), [**110**](#error-110), [**200**](#error-200), [**404**](#error-404), [**505**](#error-505).
##### *1.7. Метод изменения email* changeEmail - **http://oll.tv/ispAPI/changeEmail**
Провайдер может менять email только привязанным к нему пользователям. Метод принимает два параметра:
email — кому изменить
new_email — новый адрес
Не возвращает ничего кроме статуса.
Возможные коды ошибок: 109, 110, 200, 201, 205, 404, 505.
getUserInfo - http://oll.tv/ispAPI/getUserInfo
Принимает один обязательный параметр:
account или email или id или ds_account
Возвращает объект с данными:
email
account
registration_date
bought_subs (массив с купленными подписками типа бандл, где каждая подписка представлена объектом с необходимой информацией).
alt_mail (в случае если аккаунт от укртелекома)
Возможные коды ошибок: 109, 110, 200, 404, 505.
changeUserInfo - http://oll.tv/ispAPI/changeUserInfo
Провайдер может менять данные только привязанным к нему пользователям.
Метод принимает следующие параметры, из которых первый – обязательный:
account или email или id или ds_account
birth_date (допускаются форматы YYYY-MM-DD или DD.MM.YYYY)
gender (значения M или F, по-умолчанию: M)
password
firstname
lastname
phone
region
index (почтовый индекс или другой идентификатор региональной привязки абонента)
Не возвращает ничего кроме статуса.
Возможные коды ошибок: 109, 110, 200, 404, 505.
resetParentControl - http://oll.tv/ispAPI/resetParentControl
Принимает один обязательный параметр:
account или email или id или ds_account
Не возвращает ничего кроме статуса.
Возможные коды ошибок: 109, 110, 200, 404, 505.
enableBundle - http://oll.tv/ispAPI/enableBundle
Принимает три параметра:
account или email или id или ds_account
sub_id
type
Первый параметр обязателен.
Параметр sub_id принимает идентификатор подписки, которую необходимо включить пользователю; необходим в случае если провайдеру доступно более одного варианта бандл-подписки. Подписка на доступ с доп. экрана не может быть включена раньше подписки на основную услугу.
Параметр type предназначен для передачи уточняющей информации об активации и может принимать одно из следующих значений:
subs_free_device — Новый контракт - 24 мес и оборудование за 1 грн
subs_buy_device — Новый контракт - покупка оборудования
subs_rent_device — Новый контракт - аренда оборудования
subs_no_device — Новый контаркт - без оборудования
subs_renew — Восстановление текущего контракта
В случае удачи возвращает строку, содержащую код привязки дополнительных устройств(если такая возможность входит в бандл-подписку) или 1, в противном — 0.
Возможные коды ошибок: 109, 110, 200, 404, 407, 408, 505, 506.
disableBundle - http://oll.tv/ispAPI/disableBundle
Принимает три параметра:
account или email или id или ds_account
sub_id
type
Первый параметр обязателен.
Параметр sub_id принимает идентификатор подписки, которую необходимо выключить пользователю; необходим в случае если провайдеру доступно более одного варианта бандл-подписки. Подписка на основную услугу не может быть отключена при наличии активных подписок на доп. Экраны.
Параметр type предназначен для передачи уточняющей информации о деактивации и может принимать одно из следующих значений:
subs_break_contract — Разрыв договора
subs_negative_balance — Отрицательный баланс
subs_malfunction — Технические неполадки
subs_vacation — Каникулы
Все пользовательские устройства, которые были привязаны с помощью кода привязки, который был выдан по данной подписке, будут автоматически отвязаны от пользователя.
В случае удачи возвращает 1, в противном — 0.
Возможные коды ошибок: 109, 110, 200, 404, 407, 408, 504, 505.
checkBundle - http://oll.tv/ispAPI/checkBundle
Принимает два параметра:
account или email или id или ds_account
sub_id
Первый параметр обязателен.
Параметр sub_id принимает идентификатор подписки, по которой необходимо выполнить проверку; необходим в случае если провайдеру доступно более одного
варианта бандл-подписки.
В случае если подписка активна возвращает 1, в противном — 0.
Для получения более подробной информации используйте метод getUserInfo (1.8).
Возможные коды ошибок: 109, 110, 200, 404, 407, 505.
changeBundle - http://oll.tv/ispAPI/changeBundle
Принимает три обязательных параметра:
account или email или id или ds_account
old_sub_id
new_sub_id
Параметр old_sub_id принимает идентификатор подписки, которая активна у пользователя в данный момент, а new_sub_id — идентификатор подписки, на которую осуществляет смена. Смену можно производить только с подписками на основной тарифный план, при этом активные доп. экраны будут автоматически перенесены на новый основной тарифный план с сохранением кодов привязки.
В случае, если у пользователя неактивна подписка, идентификатор которой передается в параметре old_sub_id, возвращает 0.
В случае, если подписка, идентификатор которой передается в параметре new_sub_id, уже активна возвращает 1.
Не возвращает ничего кроме статуса.
Возможные коды ошибок: 109, 110, 200, 404, 407, 504, 505.
getAllPurchases - http://oll.tv/ispAPI/getAllPurchases
Принимает два параметра:
start_date
page
Параметры start_date – начло отчетного периода, обязателен. Параметр page – номер страницы, каждая страница возвращает до 10000 puchases, не обязателен.
Структура возвращаемого JSON:
{
data: {
purchases: [
0: {
TransactionID:
SubscriberDSID:
SubscriberProviderID:
TariffName:
TariffID:
PurchaseDate:
StartDate:
ExpirationDate:
StartOfReportingPeriod:
EndOfReportingPeriod:
RetailPrice:
ProviderPrice:
DaysWorkBundle
}
...
]
Count:
DaysInMonth:
ProviderID:
ProviderName:
Page:
}
status: 0
}Возможные коды ошибок: 109, 110, 200.
addDevice - http://oll.tv/ispAPI/addDevice
Принимает следующие параметры:
account
serial_number — серийный номер устройства
mac — mac-адрес устройства
device_type — тип устройства (например: stb, dune, smarttv, lge, samsung, ipad и т.д.)
device_model — модель устройства
binding_code — код привязки устройства, выданный во время активации подписки для доступа с доп. экрана
type
Первые три параметра обязательны.
Из параметров mac и serial_number обязателен один любой, но желательно использование обоих вместе.
Параметр binding_code обязателен для провайдеров, которые работают с подписками для доступа с доп. устройств.
Параметр type предназначен для передачи уточняющей информации об привязке и может принимать одно из следующих значений:
device_free — Новый контракт - 24 мес и оборудование за 1 грн
device_buy — Новый контракт - покупка оборудования
device_rent — Новый контракт - аренда оборудования
device_change — Сервисная замена текущего оборудования
Не возвращает ничего кроме статуса.
Возможные коды ошибок: 109, 110, 119, 200, 203, 301, 302, 303, 304, 305, 404, 405, 505.
delDevice - http://oll.tv/ispAPI/delDevice
Принимает следующие параметры:
account
mac — mac-адрес устройства
serial_number — серийный номер устройства
type
Из параметров mac и serial_number обязателен один любой, но желательно использование обоих вместе.
Если передается параметр account – перед удалением устройства будет произведена проверка на то, что это устройство привязано именно к этому пользователю.
Параметр type предназначен для передачи уточняющей информации об отвязке и может принимать одно из следующих значений:
device_break_contract — Окончание контракта
device_change — Сервисная проблема оборудования
Не возвращает ничего кроме статуса.
Возможные коды ошибок: 109, 110, 117, 200, 203, 406, 501.
deviceExists - http://oll.tv/ispAPI/deviceExists
Принимает следующие параметры:
mac — mac-адрес устройства
serial_number — серийный номер устройства
Обязателен один любой параметр, но желательно использование обоих вместе.
Возвращает объект с информацией по устройству, если оно было найдено, или же 0 в противном случае.
Возможные коды ошибок: 109, 110, 200.
getDeviceList - http://oll.tv/ispAPI/getDeviceList
Принимает следующие необязательные параметры:
account или email
offset
limit (не больше 1000, по умолчанию равно 1000)
Возвращает список устройств провайдера с указанием дополнительных данных устройства и пользователя.
Возможные коды ошибок: 109, 110, 200.
| Status | Message | Описание | Методы |
|---|---|---|---|
| 109 | Hash expired | Время действия хеша истекло или хеш не верен | Все, кроме auth |
| 110 | Authorization missed | Хеш не указан | Все, кроме auth |
| 111 | Auth failed | Неверный логин или пароль | auth |
| 112 | Login empty | Не указан логин | auth |
| 113 | Password empty | Не указан пароль | auth |
| 115 | Email already exists | Указанный имейл уже есть в БД | addUser |
| 116 | Email validation failed | Формат указанного имейла неверен | addUser |
| 117 | Result user account does not match provided | Не указан аккаунт или он не совпадает с аккаунтом на который подвязано устройство | delDevice |
| 119 | Device with provided mac or/and serial number already exist | Устройство с указанным мак-адресом и/или серийным номером уже присуствует в БД и за кем-то закреплено | addDevice |
| 120 | Wrong date format | Неверный формат даты | addUser |
| 200 | Required fields missed | Остутствуют необходимые параметры | Все, кроме auth |
| 201 | Field email is required | Отсутствует необходимый параметр email | changeAccount changeEmail emailExists |
| 203 | Neither mac nor serial_number was found in your request | Отсутствуют параметры mac и serial_number | addDevice delDevice |
| 205 | Field new_email is required | Отсутствует необходимый параметр new_email | changeEmail |
| 301 | Registration failed. Contact technical support | Ошибка добавления устройства пользователю или регистрации нового пользователя | addDevice addUser |
| 302 | Wrong MAC address | Неверный формат мак-адреса | addDevice |
| 303 | Wrong Serial number | Неверный формат серийного номера | addDevice |
| 304 | Invalid binding code | Неверный код привязки устройства | addDevice |
| 305 | No devices can be binded by this code | Достигнут лимит кол-ва устройств, которые можно привязать по указанному коду привязки | addDevice |
| 404 | Account not found | Пользователь не найден в БД | addDevice changeAccount changeBundle changeEmail changeUserInfo checkBundle deleteAccount disableBundle enableBundle getUserInfo resetParentControl |
| 405 | Not eligible device_type | Недопустимое значение в параметре device_type | addDevice |
| 406 | Device not found in our DB | Устройство не найдено в БД или оно отвязано от пользователя | delDevice |
| 407 | Subscription not found | Подписка, указанная в параметрах sub_id, new_sub_id или old_sub_id, не найдена | changeBundle checkBundle disableBundle enableBundle |
| 408 | Subscription order violation | Нарушение очерёдности отключения или включения услуги согласно подписке | disableBundle enableBundle |
| 501 | Access denied | Устройство привязано к пользователю другого провайдера | delDevice |
| 504 | User already deactivated | Услуга была уже выключена ранее | changeBundle disableBundle |
| 505 | User is attached to another operator | Пользователь привязан к другому провайдеру | addDevice changeAccount changeBundle changeEmail changeUserInfo checkBundle deleteAccount disableBundle enableBundle getUserInfo resetParentControl |
| 506 | Account is not active | Аккаунт пользователя не активен | enableBundle |