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 идёт Email пользователя, двоеточие, его пароль, а затем URL запроса.

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

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

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

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

Ограничение числа попыток авторизации

Для защиты от подбора пароля Stored Data API ограничивает количество неуспешных попыток авторизации для каждой пары «IP-адрес – логин пользователя».

При превышении лимита дальнейшие запросы с этой пары завершаются ошибкой auth-attempts-limit-reached. Ограничение действует около 30 минут, после чего попытки авторизации снова обрабатываются в обычном режиме.

Для IP-адресов, указанных в параметре my_ips (список доверенных адресов в конфигурации сервера), применяется увеличенный лимит попыток; для остальных адресов действует стандартный, более жёсткий лимит.

Администратор аккаунта может снять блокировку досрочно, сбросив неудачные попытки входа соответствующего сотрудника на странице «Сотрудники» Панели управления (см. раздел «Регистрация операторов и назначение супервизоров»).

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

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

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

{"error":"error message"}

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

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