Перейти к содержанию

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 в качестве часового пояса (временной зоны).

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

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

Если введён неверный пароль или пользователя не существует, возвращается 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 Неизвестная ошибка