- Sat

Версия документа 1.0
Описание API сервиса Sat-Control
Описание для разработчиков приложений
1
Оглавление
Общие положения ............................................................................................. 3
Принцип работы ................................................................................................. 3
Использование API............................................................................................ 3
Функции API ........................................................................................................ 4
Функция «q=token» ......................................................................................... 4
Функция «q=category» .................................................................................... 4
Функция «q= category_user» ......................................................................... 5
Функция «q=ch»............................................................................................... 6
Функция «q=guide» ......................................................................................... 8
Функция «add=category» ............................................................................... 9
Функция «add=ch» ........................................................................................ 10
Функция «del=ch».......................................................................................... 10
Функция «del=category» ............................................................................... 11
2
Общие положения
Сервис
Sat-Control
создан
для
повышения
качества
и
комфорта
использования интерфейса управления спутниковым приемником в домашних
кинотеатрах и умных домах.
Программный интерфейс (API), основан на популярном веб-протоколе
HTTP (REST). Настоящее руководство описывает принципы и методы работы с
API и содержит необходимый материал для создания приложений, работающих с
сервисом Sat-Control.
Принцип работы
Общий алгоритм приложения можно представить следующим образом:
1. Получение идентификатора сессии (token).
2. Получение списка каналов, групп каналов, текущего программы на каждый
канал, номеров каналов для указанного спутникового приемника.
3. загрузка программы на указанную дату для выбранного канала.
Использование API
Работа с API подразумевает работу с сетью и не накладывает на
приложение клиента никаких ограничений по выбору средств реализации.
Другими словами - программная часть клиента может быть реализована на любом
языке программирования, который может использовать библиотеки работы с
сетью и протокол HTTP. Поскольку тип ответа в формате XML, рекомендуется
использовать готовые библиотеки для работы с этим форматом данных. Также
рекомендуется
использовать
автономное
хранилище
для
хранения
промежуточных данных (token, всевозможные списки и т.п.).
Все запросы к API отправляются по протоколу HTTP, формируются по
специально сформированному URL и имеют следующий вид:
httр://sat-сontrol.ru/api/?
<func>=<имя_функции>&token=<token>&hwid=<hwid>&param1=value1
<func> - функция (q – получение данных, add – добавление на сервер, del –
удаление с сервера)
Примеры вызовов:
httр://sat-control.ru/api/xml/?q=ch&token=<token>&res=humax &provider=ntv
3
В случае ошибочного запроса API возвращает ответ следующего содержания:
<?xml version="1.0" encoding="UTF-8"?>
< message >
<text>
Сообщение об ошибке
</text>
</ message >
Функции API
Функция «q=token»
Описание функции: получение идентификатора сессии
Вызов:
q=token?hwid=<hwid>
Входные параметры для функции представлены в таблице:
Параметр
Описание
hwid
ID устройства зарегистрированного на
сайте sat-control.ru
Пример ответа:
<gettoken>
<token>c4197f2dfa45e156de3e0204bd5c3b02</token>
<update>1800</update>
<end></end>
</gettoken>
Параметр
token
update
Описание
Идентификатор сессии
Время действия токена в секундах, через указанное время
токен нужно запросить повторно.
Функция «q=category»
Описание функции: получение списка категорий.
Вызов:
q=category?token=<token>&hwid=<hwid> &provieder=ntv
Входные параметры для функции представлены в таблице:
Параметр
Описание
token
Полученный token
4
hwid
ID устройства.
provider
Провайдер из списка доступных
Пример ответа:
<allcategory >
<total>11</total>
<category>
<name>Любимые</name>
<add>user</add>
</category>
<category>
<name>HD</name>
<add>sys</add>
</category>
<category>
<name>Общие</name>
<add>sys</add>
</category>
<category>
<name>Спорт и Отдых</name>
<add>sys</add>
</category>
<category>
<name>Кино и Сериалы</name>
<add>sys</add>
</category>
<end></end>
</allcategory >
Параметр
total
add
name
Описание
Количество категорий
user – добавлена пользователем, sys - добавлена сервером
Название категории
Функция «q= category_user»
Описание функции: получение списка категорий созданных пользователем
Вызов:
q=category_user?token=<token>&hwid=<hwid
Входные параметры для функции представлены в таблице:
Параметр
Описание
token
Полученный token
hwid
ID устройства.
5
Пример ответа:
<allcategoryuser>
<total>2</total>
<category>
<name>Любимые</name>
<add>user</add>
</category>
<category>
<name>Новый список</name>
<add>user</add>
</category>
<end></end>
</allcategoryuser>
Параметр
total
add
name
Описание
Количество категорий
user – добавлена пользователем, sys - добавлена сервером
Название категории
Функция «q=ch»
Описание функции: получение списка каналов
Вызов:
q=ch&ch_mode=ch&category=Общие&token=<token>&hwid=<hwid>&resiver=humax&
provieder=ntv
Входные параметры для функции представлены в таблице:
Параметр
Описание
token
Полученный token
hwid
ID устройства.
resiver
Модель приемника для которого будут
получены номера каналов
provider
Провайдер из списка доступных
ch_mode
Режим полученных данный (ch –
список каналов, guide – список каналов
с текущей программой)
category
Категория каналов (напр. Общие)
6
Пример ответа для запроса с параметром ch_mode=ch:
<allch>
<activecategory >HD</activecategory >
<total>1</total>
<channel>
<id>1</id>
<name>Первый HD</name>
<category>HD</category>
<number>101</number>
<image>
http://sat-control.ru/image/ntv/1/e70c33df7b3b360/1357d449a8/
</image>
<add>sys</add>
</channel>
<end></end>
</allch>
Параметр
activecategory
total
id
name
category
number
image
add
Описание
Категория для которой получены каналы
Количество каналов
Идентификатор канала для работы с ним (добавление в
избранное, получение программы и т.д.)
Название канала
Категория к которой относится канал
Номер канала на спутниковом приемнике
Динамическая ссылка на логотип канала
user – добавлен пользователем, sys - добавлен сервером
Пример ответа для запроса с параметром ch_mode=guide:
<allch>
<activecategory>Спорт и Отдых</activecategory>
<total>1</total>
<channel>
<id>127</id>
<name>Матч</name>
<category>Спорт и Отдых</category>
<number>3</number>
<image>http://sat-control.ru/image/ntv/127/333/11f5818/</image>
<add>sys</add>
<guide>
<time_prev>00:30</time_prev>
<prog_prev>ДАКАР-2016</prog_prev>
<time_cur>01:00</time_cur>
<prog_cur>ВЫШИБАЛА (16+) - фильм</prog_cur>
<value>83</value>
<time_next>02:50</time_next>
<prog_next>ХОККЕЙ- Чемпионат </prog_next>
</guide>
7
</channel
<end></end>
</allch>
Параметр
activecategory
total
id
name
category
number
image
add
guide
time_prev
prog_prev
time_cur
prog_cur
value
time_next
prog_next
Описание
Категория для которой получены каналы
Количество каналов
Идентификатор канала для работы с ним (добавление в
избранное, получение программы и т.д.)
Название канала
Категория к которой относится канал
Номер канала на спутниковом приемнике
Динамическая ссылка на логотип канала
user – добавлен пользователем, sys - добавлен сервером
Краткая программа передач
Время начала прошедшей программы
Название прошедшей передачи
Время начала передачи которая идет сейчас
Название передачи которая идет сейчас
Прогресс текущей передачи в процентах (от 0 до 100)
Время начала следующей передачи
Название следующей передачи
Функция «q=guide»
Описание функции: получение программы передач
Вызов:
q=guide&token=<token>&hwid=<hwid >&ch_id=<id>&provider=<provider
Входные параметры для функции представлены в таблице:
Параметр
Описание
token
Полученный token
hwid
ID устройства.
ch_id
Id канала полученный при получении
списка каналов
provider
Провайдер из списка доступных
Необязательные параметры
Описание
date_shift
Смещение даты относительно текущей
даты, значение от -7 до 7.
date
Дата на которую нужно получить
программу
8
Пример ответа:
<guide>
<date>06.01.2016</date>
<ch>
<name>Матч</name>
<image>
http://sat-control.ru/image/ntv/127/540d766c16/14a091f5818/
</image>
</ch>
<prog>
<time>16:55</time>
<name>
ДЕТАЛИ СПОРТА (16+)
</name>
</prog>
<prog>
<time>17:10</time>
<name>
ХОККЕЙ. КХЛ- ЦСКА - ЛОКОМОТИВ
</name>
</prog>
<total>2</total>
<end></end>
</guide>
Параметр
date
ch name
ch image
prog time
prog name
total
Описание
Дата на которую получена программа
Название канала для которого получена программа
Ссылка на логотип канала для которого получена программа
Время начала передачи
Название передачи
Количество передач в списке
Функция «add=category»
Описание функции: добавление пользовательской категории
Вызов:
add=category?name=<название>&private=no&token=<token>&hwid=<hwid>
Входные параметры для функции представлены в таблице:
Параметр
Описание
token
Полученный token
hwid
ID устройства.
name
Название категории
private
yes – категория будет доступна только
9
на том устройстве на котором она
добавлена
no – категория будет доступна всем
устройствам входящим в одну группу
Пример ответа:
<message>
<text>Новый список каналов добавлен.</text>
<end></end>
</message>
Функция «add=ch»
Описание функции: добавление канала в пользовательскую категорию
Вызов:
add=ch?ch_id=<ch_id>&category=Любимые&token=<token>&hwid=<hwid>
Входные параметры для функции представлены в таблице:
Параметр
Описание
token
Полученный token
hwid
ID устройства.
ch_id
Id канала полученный при получении
списка каналов
category
Название пользовательской категории
в которую нужно добавить канал.
Категория должна быть
предварительно создана.
Пример ответа:
<message>
<text>Канал добавлен в список.</text>
<end></end>
</message>
Функция «del=ch»
Описание функции: удаление канала из пользовательской категории
Вызов:
10
del=ch?ch_id=<ch_id>&category=Любимые&token=<token>&hwid=<hwid>
Входные параметры для функции представлены в таблице:
Параметр
Описание
token
Полученный token
hwid
ID устройства.
ch_id
Id канала полученный при получении
списка каналов
category
Название пользовательской категории
в которую нужно добавить канал.
Категория должна быть
предварительно создана.
Пример ответа:
<message>
<text>Канал удален из списка.</text>
<end></end>
</message>
Функция «del=category»
Описание функции: добавление пользовательской категории
Вызов:
del=category?name=<название>&private=no&token=<token>&hwid=<hwid>
Входные параметры для функции представлены в таблице:
Параметр
Описание
token
Полученный token
hwid
ID устройства.
name
Название категории которую нужно
удалить
Пример ответа:
<message>
<text>Список каналов удален.</text>
<end></end>
</message>
11