REST API v1

Запрос

Структура запроса HTTP_METHOD /RESOURCE/[IDENTIFIERS]

HTTP_METHOD

Поддерживаются следующие HTTP методы

GET - получение данных PUT - обновление POST - создание DELETE - удаление

IDENTIFIERS - Идентификаторы

Один или несколько. Идентификаторы разделяются запятой "," без пробелов.

Ответ

Структура ответа

{ "status" : "OK" || "ERROR", "results" : [], "error" : "" // Поле содержит строку сообщения об ошибке. }

Аутентификация и авторизация

Поддерживается basic HTTP authentication. При включенной аутентификации все запросы к API должны содержать корректный заголовок Authorization.

При отсутствии этого заголовка или если в нем содержатся некорректные данные - ответ сервера будет содержать HTTP статус 401 Unauthorized и сообщение:

< {"status":"ERROR","results":"","error":"401 Unauthorized request"}

Для успешной аутентификации достаточно добавить в каждый запрос к API заголовок:

Authorization: Basic <base64encode("login":"password")>

Поддерживаемые ресурсы

STB

Управление приставками (рекомендуется использовать ресурс ACCOUNTS вместо STB)

Идентификатор: лицевой счет, MAC адрес (один ЛС может содержать больше одной приставки)

Поддерживаемые методы: GET, PUT, DELETE, POST

Разрешенные поля для обновления: status, additional_services_on, ls

Разрешенные поля для добавления: mac, login, password, status, additional_services_on, ls

Описание полей

mac - MAC адрес приставки
ls - лицевой счет
login - логин лицевого счета
status - административный статус (1 - включена, 0 - выключена)
online - состояние приставки (1 - онлайн, 0 - оффлайн)
ip - IP адрес приставки
version - строка с версиями прошивки, портала и т.д.
additional_services_on - статус подключения дополнительных услуг, таких как Видеоклуб, Караоке и т.д. (1 - включена, 0 - выключена)
last_active - дата и время последней активности (проигрывание контента)

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

> GET [API_URL]/stb < {"status":"OK","results":[{"mac":"00:1A:79:00:15:B3","status":0,"additional_services_on":"0","ls":1553,"login":"1553","online":"1"}, {"mac":"00:1A:79:00:39:5E","status":0,"additional_services_on":"1","ls":3,"login":"3","online":"0"}]

Пример 2. Получение данных об одной приставке по идентификатору

> GET [API_URL]/stb/1553 < {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","status":1,"additional_services_on":"1","ls":1553,"login":"1553","online":"1"}]}

Пример 3. Получение данных о нескольких приставках по идентификаторам

> GET [API_URL]/stb/1553,3 < {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","status":1,"additional_services_on":"1","ls":1553,"login":"1553","online":"1"}, {"mac":"00:1A:79:00:21:40","status":0,"additional_services_on":"0","ls":3,"login":"3","online":"0"}]}

Пример 4. Обновление данных приставки по идентификатору

> PUT [API_URL]/stb/1553 > status=1&additional_services_on=0 < {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","status":1,"additional_services_on":"0","ls":1553}]}

Пример 5. Удаление приставки по идентификатору

> DELETE [API_URL]/stb/1553 < {"status":"OK","results":true}

Пример 6. Добавление приставки по с логином и паролем (для аутентификации)

> POST [API_URL]/stb/ > login=test&password=1234 < {"status":"OK","results":{"mac":"","status":1,"additional_services_on":"1","ls":"0","login":"test"}}

Пример 7. Добавление приставки с выключенными дополнительными сервисами

> POST [API_URL]/stb/ > mac=00:1A:79:00:39:5E&additional_services_on=0 < {"status":"OK","results":{"mac":"00:1A:79:00:39:5E","status":1,"additional_services_on":"0","ls":"0","login":""}}

ACCOUNTS

Управление учетными записями пользователей (вместо ресурса STB)

Идентификатор: лицевой счет, MAC адрес (один ЛС может содержать больше одной приставки)

Поддерживаемые методы: GET, PUT, DELETE, POST

Разрешенные поля для обновления: login, password, full_name, account_number, tariff_plan, tariff_expired_date, tariff_instead_expired, status, stb_mac, comment, end_date, account_balance

Разрешенные поля для добавления: login, password, full_name, account_number, tariff_plan, tariff_expired_date, tariff_instead_expired, status, stb_mac, comment, end_date, account_balance

Обязательные поля: login

Описание полей

login - Логин для авторизации. (уникален, обязателен) password - Пароль для авторизации. full_name - Наименование пользователя. (ФИО или название организации) account_number - Номер лицевого счета. tariff_plan - Идентификатор тарифного плана. tariff_expired_date - Дата переключения тарифа tariff_instead_expired - Идентификатор тарифного плана на который переключится аккаунт после наступления tariff_expired_date status - Административный статус. (1 - включена, 0 - выключена) stb_mac - MAC адрес приставки. stb_sn - Серийный номер устройства. stb_type - Модель устройства. online - Состояние приставки (1 - онлайн, 0 - оффлайн) ip - IP адрес приставки version - Строка с версиями прошивки, портала и т.д. subscribed - Список идентификаторов опциональных пакетов, на которые есть подписка. comment - Строка - комментарий. Видна только администратору. end_date - Дата отключения (при enable_internal_billing = true) в формате "Y-m-d H:i:s". account_balance - Строка, содержащая баланс. Например "100 грн.". last_active - дата и время последней активности (проигрывание контента)

Пример 1. Получение данных о пользователе.

> GET [API_URL]/accounts/00:1A:79:00:39:5E < {"status":"OK","results":[{"login":"3210","full_name":"Test","account_number":"123","tariff_plan":"FULL","stb_sn":"123345","stb_mac":"FF:FF:FF:FF:FF:FF","stb_type":"MAG250","status":1,"subscribed":[]}]

Пример 2. Создание учетной записи пользователя.

> POST [API_URL]/accounts/ > login=3210&password=1234&full_name=Test&account_number=123&tariff_plan=FULL&status=1&2016-01-01%2012:00:00=&account_balance=100%20грн. < {"status":"OK","results":true}

Пример 3. Обновление учетной записи пользователя.

> PUT [API_URL]/accounts/00:1A:79:00:39:5E > tariff_plan=STANDART < {"status":"OK","results":true}

Пример 4. Удаление учетной записи пользователя.

> DELETE [API_URL]/accounts/00:1A:79:00:39:5E < {"status":"OK","results":true}

USERS

Управление учетными записями пользователей.

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

В результате вместо коллекции объектов возвращается один объект.

Идентификатор: логин, MAC адрес.

Пример 1. Получение данных о пользователе.

> GET [API_URL]/users/3210 < {"status":"OK","results":{"login":"3210","full_name":"Test","account_number":"123","tariff_plan":"FULL","stb_sn":"123345","stb_mac":"FF:FF:FF:FF:FF:FF","stb_type":"MAG250","status":1,"subscribed":[]}

STB_MSG

Отправка сообщений на приставку

Идентификатор: лицевой счет, MAC адрес (один ЛС может содержать больше одной приставки)

Поддерживаемые методы: POST

Разрешенные поля для обновления: msg (текст сообщения должен быть url encoded), ttl (время жизни сообщения в секундах)

При успешном добавлении в results возвращается true.

Пример 1. Обновление данных приставки по идентификатору

> POST [API_URL]/stb_msg/1553
> msg=%D0%BF%D1%80%D0%BE%D0%B2%D0%B5%D1%80%D0%BA%D0%B0%20%D1%81%D0%B2%D1%8F%D0%B7%D0%B8
< {"status":"OK","results":true]}

SEND_EVENT

Отправка событий на приставку

Идентификатор: лицевой счет, MAC адрес (один ЛС может содержать больше одной приставки)

Поддерживаемые методы: POST

Разрешенные поля для обновления: event (название события: send_msg, reboot, reload_portal, update_channels, play_channel, update_image, cut_off), msg (текст сообщения должен быть url encoded), ttl (время жизни сообщения в секундах), need_reboot (флаг перезапуска, только для события send_msg), channel (номер канала, только для события play_channel)

При успешном добавлении в results возвращается true.

Пример 1. Отправка события перезапуска всем устройствам

> POST [API_URL]/send_event/
> event=reboot
< {"status":"OK","results":true]}

Пример 2. Отправка события проигрывания канала №10 конкретной приставке

> POST [API_URL]/send_event/00:1A:79:00:00:00
> event=play_channel&channel=10
< {"status":"OK","results":true]}

Пример 3. Отправка события отключения приставок на лицевом счету 12345, при этом нужно дополнительно отключать приставку (status=0) через ресурсы STB, ACCOUNTS или USERS.

> POST [API_URL]/send_event/12345
> event=cut_off
< {"status":"OK","results":true]}

STB_MODULES

Управление доступом к модулям (разделам главного меню)

Идентификатор: лицевой счет, MAC адрес (один ЛС может содержать больше одной приставки)

Поддерживаемые методы: PUT, GET

Разрешенные поля для обновления: disabled (разделы не отображаются, требуется перезагрузка), restricted (ограничивается доступ)

Пример 1. Запрет доступа в разделы vclub karaoke, отключение модуля radio

> POST [API_URL]/stb_modules/00:1A:79:00:39:5E
> restricted[]=vclub&restricted[]=karaoke&disabled[]=radio
< {"status":"OK","results":{"disabled":["radio"],"restricted":["vclub","karaoke"]}}

Пример 2. Отключение всех ограничений

> POST [API_URL]/stb_modules/00:1A:79:00:39:5E
> restricted[]=&disabled[]=
< {"status":"OK","results":{"disabled":[""],"restricted":[""]}}

ITV

Получение списка каналов

Идентификатор: ID канала

Поддерживаемые методы: GET

Описание полей

id - ID канала name - имя канала number - номер канала base_ch - идентификатор базового канала

Пример 1. Получение данных о всех каналах

> GET [API_URL]/itv
< {"status":"OK","results":[{"id":"37","name":"\u041c-TV \u0423\u043a\u0440\u0430\u0438\u043d\u0430","number":"64"}, ...]

ITV_SUBSCRIPTION

Управление подпиской на каналы

Идентификатор: лицевой счет, MAC адрес (один ЛС может содержать больше одной приставки)

Поддерживаемые методы: GET, PUT

Разрешенные поля для обновления: sub_ch

Описание полей

ls - лицевой счет mac - MAC адрес приставки sub_ch - список ID каналов additional_services_on - статус подключения дополнительных услуг

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

> GET [API_URL]/itv_subscription
< {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","sub_ch":["27"],"ls":1553,"additional_services_on":"0"}, {"mac":"00:1A:79:00:15:B3","sub_ch":["27", "29"],"ls":3,"additional_services_on":"0"}]}

Пример 2. Получение данных о подписке для конкретного лицевого счета

> GET [API_URL]/itv_subscription/1553
< {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","sub_ch":["27"],"ls":1553,"additional_services_on":"0"},{"sub_ch":["58"],"mac":"00:1A:79:00:15:B3","ls":"1553","additional_services_on":"0"}]}

Пример 3. Получение данных о подписке для конкретной приставки

> GET [API_URL]/itv_subscription/00:1A:79:00:39:5E
< {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","sub_ch":["27"],"ls":1553,"additional_services_on":"0"}]}

Пример 4. Обновление данных о подписке для всех приставок на лицевом счете

> PUT [API_URL]/itv_subscription/1553
> sub_ch[]=27&sub_ch[]=29&additional_services_on=1
< {"status":"OK","results":[{"sub_ch":["27","29"],"mac":"00:1A:79:00:15:B3","ls":"1553","additional_services_on":"1"},{"sub_ch":["27","29"],"mac":"00:1A:79:00:39:5E","ls":"1553","additional_services_on":"1"}]}

TARIFFS

Информация о тарифных планах и пакетах услуг

Идентификатор: ID тарифного плана

Поддерживаемые методы: GET

Описание полей

id - ID тарифного плана external_id - ID для внешних систем name - название user_default - опция тарифного плана по умолчанию days_to_expires - количетво дней действия тарифа packages - описание пакетов услуг

Описание полей пакета услуг

id - ID пакета услуг external_id - ID для внешних систем name - название type - тип (video, tv, radio, module) description - описание all_services - флаг, означающий что пакет содержит все услуги указанного типа service_type - тип пакета (periodic или single) rent_duration - длительность аренды (для service_type = single) optional - флаг, означающий что пакет является опциональным

Пример 1. Получение данных о тарифных планах

> GET [API_URL]/tariffs
< {"status":"OK","results":[{"id":"10","external_id":"","name":"\u0422\u0430\u0440\u0438\u0444 \u041f\u0430\u043a\u0435\u0442 +","user_default":"0","packages":[{"id":"10","external_id":"all_video"...

SERVICES_PACKAGE

Информация о пакетах услуг

Идентификатор: ID пакета услуг

Поддерживаемые методы: GET

Описание полей

id - ID пакета услуг external_id - ID для внешних систем name - название type - тип (video, tv, radio, module) description - описание all_services - флаг, означающий что пакет содержит все услуги указанного типа service_type - тип пакета (periodic или single) rent_duration - длительность аренды (для service_type = single) services - список услуг или 'all', означающее все услуги данного типа

Пример 1. Получение данных о пакетах услуг

> GET [API_URL]/services_package
< {"status":"OK","results":[{"id":"10","external_id":"all_video","name":"\u0412\u0441\u0435 \u0432\u0438\u0434\u0435\u043e","type":"video","description":"\u041f\u043e\u043b\u043d\u044b\u0439 \u0434\u043e\u0441\u0442\u0443\u043f \u043a \u0432\u0438\u0434\u0435\u043e\u043a\u043b\u0443\u0431\u0443","all_services":"1","service_type":"periodic","rent_duration":"0","services":"all"},...

ACCOUNT_SUBSCRIPTION

Управление подписками на опциональные пакеты

Идентификатор: лицевой счет, MAC адрес (один ЛС может содержать больше одной приставки)

Поддерживаемые методы: GET, POST, PUT, DELETE

Разрешенные поля для обновления: subscribed, subscribed_id, unsubscribed (для PUT), unsubscribed_id (для PUT)

Описание полей

mac - MAC адрес приставки subscribed - список опциональных пакетов (external_id), на которые осуществлена подписка subscribed_id - список опциональных пакетов (внутренний id), на которые осуществлена подписка

Пример 1. Получение данных о подписанных опциональных пакетах

> GET [API_URL]/account_subscription/1553
< {"status":"OK","results":[{"mac":"00:1A:79:00:15:B3","subscribed":["tv_6","tv_3"]}]}

Пример 2. Подписка на опциональный пакет

> PUT [API_URL]/account_subscription/1553
> subscribed[]=tv_2
< {"status":"OK","results":true}

Пример 3. Отписка от опционального пакета

> PUT [API_URL]/account_subscription/1553
> unsubscribed[]=tv_2
< {"status":"OK","results":true}

Пример 4. Обновление информации о всех подписанных пакетах

> POST [API_URL]/account_subscription/1553
> subscribed[]=tv_2&subscribed[]=tv_3
< {"status":"OK","results":true}

Пример 5. Отписка от всех опциональных пакетов

> DELETE [API_URL]/account_subscription/1553
< {"status":"OK","results":true}