REST API v1

Запрос

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

HTTP_METHOD

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

Пример 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, status, stb_mac, comment, end_date, account_balance.

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

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

Пример 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":"00:1A:79:00:39:5E","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
< {"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,
send_msg_with_video, reboot, reload_portal, update_channels, play_channel,  play_radio_channel, update_image, show_menu, cut_off), msg (текст сообщения должен содержать закодированный URL), 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]}

Пример 4. Отправка события отображения меню на конкретной приставке.

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

STB_MODULES

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

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

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

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

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

> PUT [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. Отключение всех ограничений.

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

ITV

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

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

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

Пример 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.

Пример 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.

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

Пример 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.

Пример 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).

Пример 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}

RESELLER

Управление реселлерами, которое осуществляется после включения опции allow_resellers_info_for_api = true в файле config.ini (custom.ini).

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

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

Разрешенные поля для добавления:  name, max_users, use_ip_ranges.

Разрешенные поля для обновления: name, max_users, use_ip_ranges.

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

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

> GET [API_URL]/reseller
< {"status":"OK","results":[{"id": "1","name": "Example Reseller","created": "2018-10-10 16:25:22","modified": "2019-04-08 10:38:46","max_users": "100","use_ip_ranges": "0"}]}

Пример 2. Добавление нового реселлера в систему.

> POST [API_URL]/reseller
> name=2&max_users=200&use_ip_ranges=0
< {"status": "OK", "results": true}

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

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