Stored Data API

Для работы с хранящимися в системе данными используется Stored Data API. Запросы к этому API позволяют получать информацию о:

Операторах
Чатах
Категориях
Тарифах
Отделах
Статистике

Также Stored Data API предоставляет возможность заказывать услуги.

На текущий момент последней версией API является 4. Версии 2 и 3 актуальны, но мы настоятельно рекомендуем Вам переходить на последнюю версию.

Стоит отметить, что API версии 1 технически работает, но признан устаревшим и его поддержка не осуществляется.

Базовый URL

Базовый URL — это домен Вашего аккаунта, он зависит от Вашей сетевой конфигурации. Он имеет вид:

https://{hostname}/api/v{api_version}/{path}

Где {hostname} — имя хоста, на котором размещается Webim Server, вида {account}.webim.ru для облачных клиентов и chat.mycompany.com для hosted, {api_version} - используемая версия API, {path} — команда API.

На базовый URL отправляются запросы для доступа к Webim Stored Data API.

Пример готового запроса к Webim Stored Data API:

https://company.webim.ru/api/v4/operators

Данный запрос должен вернуть список всех операторов.

Для доступа к Webim Stored Data API необходимо пройти авторизацию.

Авторизация, доступ к API

Stored Data API для облачных клиентов доступен на тарифе Корпоративный. Для доступа используется email и пароль любого зарегистрированного в данном аккаунте сотрудника с ролью Администратор (admin_password). В данном API используется "Базовая" (Basic) HTTP-аутентификация. Пример CURL-запроса:

curl -u adm@domain.com:password {base_url}/api/v{api_version}/{request}

Где base_url — базовый URL для вашей сетевой конфигурации, {api_version} - используемая версия API, request — Ваш запрос к API.

Таким образом, после curl -u идёт e-mail пользователя, двоеточие, его пароль, а затем URL запроса.

Работа API осуществляется только по протоколу HTTPS.

Все данные возвращаются в кодировке UTF-8.

Формат времени ISO 8601 и UTC в качестве часового пояса (временной зоны).

Формат временных интервалов: секунды.

Обработка ошибок

Если введён неверный пароль или пользователя не существует, возвращается HTTP-код 401.

Если оператор не является администратором или сделано слишком много попыток авторизации, возвращается HTTP-код 403. Прочие ошибки приходят в формате JSON следующего содержания (с HTTP-кодом 200, если не указано иное):

{"error":"error message"}

Возможные типы ошибок:

Код ошибки	Описание
`chat-not-found`	Чат не найден
`wrong-date-format`	Неверный формат даты
`wrong-price`	Неверная цена
`wrong-period`	Неверный период времени
`no-tariff-option`	Аккаунт не имеет доступа к API
`no-partner-option`	Аккаунт не является партнёрским
`account-blocked`	Аккаунт заблокирован
`db-schema-archived`	БД архивирована
`auth-attempts-limit-reached`	Исчерпан лимит попыток авторизации
`unauthorized`	Пользователь не авторизован
`unknown-method`	Задан неверный тип запроса
`unknown-mode`	Выбран неверный режим запроса (`mode`)
`argument-missing`	Не хватает аргументов для запроса
`internal problem`	Внутренняя ошибка сервиса
`unknown`	Неизвестная ошибка