Platform HTTP API

Формат взаимодействия

Запросы к API выполняются по протоколу HTTP. Входные и выходные структуры данных передаются в теле запроса и ответа в формате JSON.

Авторизация

Большинство вызовов HTTP API требуют процедур аутентификации и авторизации, которые связывают вызовы API с необходимыми приложениями в Вашей учетной записи.

Для этого каждый запрос должен содержать заголовок, либо аргумент X-Authorization с токеном соединения в формате AccessKey token,

Например заголовком:
POST /apps/activate HTTP/1.1
Host: api.unibell.ru
X-Authorization: AccessKey d8ac9959r12b43545da9034,

либо параметром:
POST api.unibell.ru/apps/activate?X-Authorization=AccessKey d8ac9959r12b43545da9034

Формат ответов

JSON схема любого ответа содержит параметр status типа string со следующими значениями:

Значение status	Описание
ok	Без ошибок
invalidAccessKeyError	Неверный AccessKey
requiredJsonError	В теле запроса требуется JSON
invalidSchemeError	Неверная схема JSON
invalidDataError	Ошибочные входные данные
prohibitedForAppError	Запрещено для данного приложения
prohibitedForServiceError	Запрещено для данной услуги
rpcError	Коммуникационная ошибка

Например:

    {
        …
        “status”: “ok”
        ....
    }

Некоторые GET запросы поддерживают постраничный вывод. Для управления постраничным выводом используются следующие параметры:

Параметр	Описание
page	Запрашиваемый номер страницы
per_page	Количество элементов на странице
disable_pagination	Отключить постраничный вывод

Например,

GET api.unibell.ru/media?page=1&per_page=10

В ответе на такой запрос будет содержаться json объект pagination:

    {
        …
        "pagination": {
            "totalItems": 2,
            "currentPage": 1,
            "totalPages": 1
        }
        ....
    }

где:

Параметр	Описание
totalItems	Общее количество элементов
currentPage	Порядковый номер страницы
totalPages	Общее количество страниц

Формат запросов

Управление медиатекой

Медиатека — иерархическое хранилище различных файлов пользователя, напоминающее файловую систему. Объектами хранения медиатеки являются файлы и папки. Файлы могут быть разбиты по папкам. Доступ к медиатеке осуществляется с помощью ЛК или данного API.

Параметр	Описание
totalItems	Общее количество элементов
currentPage	Порядковый номер страницы
totalPages	Общее количество страниц

Получение списка всех объектов

Запрос

GET api.unibell.ru/media

Ответ

    {
        "status":  "ok",
        "pagination": {
            "totalItems":  2,
            "currentPage":  1,
            "totalPages":  1
        },
        "media": [
            {
                "createdDateTime":  "2020-02-12 18:09:10",
                "id":  65,
                "name":  "Гимны",
                "isFolder":  1
            },
            {
                "createdDateTime":  "2020-03-04 13:17:47",
                "id":  74,
                "name":  такой молодой.mp3",
                "isFolder":  0
            }
        ]
    }

media — массив объектов медиатеки содержащие следующие параметры:

Параметр	Описание
id	Уникальный идентификатор медиаресурса
name	Наименование
createdDateTime	Дата\время загрузки
isFolder	Признак того, что данный объект является папкой. 1 — да, 0 — нет

Получение конкретного объекта

Запрос

GET api.unibell.ru/media/id, где id — уникальный идентификатор медиаресурса

Ответ

Для папок возвращается список вложенных файлов:

    {
        "status": "ok",
        "pagination": {
            "totalPages": 1,
            "totalItems": 2,
            "currentPage": 1
        },
        "media": [
            {
                "isFolder": 0,
                "name": "Гимн пионэров.mp3",
                "createdDateTime": "2020-02-12 18:19:05",
                "id": 67
            },
            {
                "isFolder": 0,
                "name": "Гимн СССР.mp3",
                "createdDateTime": "2020-02-12 18:19:18",
                "id": 68
            }
        ]
    }

Для файлов возвращается запрашиваемый файл.

Создание папки

Запрос

POST api.unibell.ru/media

    {
        "name": "asdasd"
    }

Параметр	Описание
name	Наименование папки

Ответ

   {
        "status": "ok",
        "media": {
            "name": "asdasd2",
            "createdDateTime": "2020-04-06 18:44:45",
            "isFolder": 1,
            "id": 111
        }
    }

Загрузка файла

Запрос

POST api.unibell.ru/media — помещает файл в корневую папку
POST api.unibell.ru/media/folder_id — помещает файл в указанную папку

Файл передается в теле запроса посредством Content-Type: multipart/form-data

Ответ

    {
        "status": "ok",
        "media": {
            "name": "test",
            "createdDateTime": "2020-04-06 18:44:45",
            "isFolder": 0,
            "id": 112
        }
    }

Переименование объекта

Запрос

PUT api.unibell.ru/media/id, где id — уникальный идентификатор медиаресурса

    {
        "name": "asdasd"
    }

Ответ

    {
        "status": "ok",
        "media": {
            "name": "asdasd",
            "createdDateTime": "2020-04-06 18:44:45",
            "isFolder": 1,
            "id": 111
        }
    }

Удаление объекта

Запрос

DELETE api.unibell.ru/media/id, где id — уникальный идентификатор медиаресурса

Ответ

    {
        “status”: “ok”
    }

Управление приложениями

Активация приложения

Выполняет активацию заранее созданного приложения.

Запрос

POST api.unibell.ru/apps/activate

 {
"reference": "123456789",
"sourceAddr": "XXXXXXXXXXX",
"destAddr": "XXXXXXXXXXX",
"sex": 1,
"volume": 1,
"language": "xx-XX",
"rate": 1,
"scenarioData": "text=Привет, как дела?"
}

Параметр	Тип	Описание
reference	string	Пользовательский параметр с которым будет вызван callback по результатам выполнения приложения
sourceAddr	string	Исходящий номер
destAddr	string	Номер телефона получателя
scenarioData	string	Переменные сценария для данного приложения. Представляет из себя набор пар параметр=значение, разделенных знаком — &.
sex	int	Пол. 0 — женский, 1 — мужской
volume	int	Громкость голоса (0-2)
rate	int	Скорость проговаривания текста (0-4). (0 — самая медленная)
language	string	Язык синтеза. Для русского этот параметр опускается. Доступные языки: en-US — Английский (США) en-IN — Английский (Индия) en-IE — Английский (Ирландия) en-UA — Английский (Австралия) en-GB-WLS — Английский (Уэльс) en-NZ — Английский (Новая Зеландия) en-ZA — Английский (Южная Африка) ar-AE — Арабский (Персидский залив) nl-NL — Голландский nl-BE — Голландский (Бельгия) da-DK — Датский is-IS — Исландский es-ES — Испанский (Европа) es-US — Испанский (США) es-MX — Испанский (Мексика) it-IT — Итальянский ca-ES — Каталанский cmn-CN — Китайский (Северный Китай) yue-CN — Китайский (Кантон/Гуанчжоу) ko-KR — Корейский de-DE — Немецкий de-AT — Немецкий (Австралия) nb-NO — Норвежский pl-PL — Польский pt-PT — Португальский (Европа) pt-BR — Португальский (Бразилия) ro-RO — Румынский ru-RU — Русский tr-TR — Турецкий cy-GB — Валлийский fi-FI — Финский fr-FR — Французский fi-CA — Французский (Канада) fr-BE — Французский (Бельгия) sv-SE — Шведский ja-JP — Японский

Ответ

    {
        “status”: “ok”
    }

При исполнении приложения могут быть настроены callback по протоколу HTTP/HTTPS. Callback настраивают на два вида события — начало исполнения(Start callback) и завершение исполнения(End callback). Поддерживается Basic авторизация. Параметры передаются в URL запроса.

Например,
GET www.host.ru?type=startCallback&reference=324234

Параметры передаваемые в startCallback:

Параметр	Описание
reference	Пользовательский параметр переданный в запросе активации
type	Тип callback запроса, в данном случае — startCallback

Параметры передаваемые в endCallback:

Параметр	Описание
reference	Пользовательский параметр переданный в запросе активации
type	Тип callback запроса, в данном случае — endCallback
state	Результат выполнения приложения
error	Код ошибки, либо 0 — в случае успешного выполнения
duration	Длительность вызова

где, state — результат выполнения сценария:

state	Значение	Описание
STATE_OK	2	Приложение выполнено успешно
STATE_ERR	5	Ошибка в результате выполнения

error — код ошибки:

error	Значение	Описание
ERR_NO_ANSWER	16	Абонент не взял трубку, попытки дозвона исчерпаны
ERR_BUSY	17	Абонент занят, попытки дозвона исчерпаны
ERR_ALERTING	19	Абонент не доступен
ERR_CONGESTION	34	Перегрузка каналов связи
ERR_PLAY	1001	Ошибка воспроизведения файла, файл не найден, неверный формат
ERR_TTS	1002, 1017	Ошибка TTS преобразования
ERR_ASR	1003	Ошибка ASR преобразования

Проверка баланса

Запрос

GET api.unibell.ru/balance

Выводит в формате JSON лицевой счет и его баланс. Лицевой счет отображается тот, на котором находится приложение, ключ от которого указан в авторизации запроса

Ответ

     {
        "personalAccountId": "0000000000",
        "balance": "100.0"
     }

На этой странице