# Stored Data API

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

  * Операторах

  * Чатах

  * Категориях

  * Тарифах

  * Отделах

  * Статистике

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

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

!!!Note "Важно (10.8)"
    Начиная с версии **10.8** **Stored Data API** не читает данные из **Elasticsearch**. Параметр `elasticsearch_api` и связанная логика выбора источника отключены. Все ответы формируются только из основной реляционной БД. Интеграция **Elasticsearch** для страницы **История диалогов** при этом не затрагивается.

## Базовый 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 для облачных клиентов доступен [на тарифе Корпоративный](https://webim.ru/price/). Для доступа используется 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` (список доверенных адресов в конфигурации сервера), применяется увеличенный лимит попыток; для остальных адресов действует стандартный, более жёсткий лимит.

Администратор аккаунта может снять блокировку досрочно, сбросив неудачные попытки входа соответствующего сотрудника на странице «Сотрудники» Панели управления (см. раздел [«Регистрация операторов и назначение супервизоров»](https://webim.ru/kb/for-admins/registration-agents-and-supervisors.html)).


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

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

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

```
{"error":"error message"}
```

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

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

!!! Note "N.B."
    Начиная с API версии 4, ошибки возвращаются с соответствующими HTTP-кодами (400, 402, 404 и т.д.) вместо HTTP 200. В более ранних версиях API все ошибки возвращаются с HTTP-кодом 200 (если не указано иное).

Ошибка `db-schema-archived` возвращается, если аккаунт (его схема БД) был переведён в архив. Для возобновления работы с API требуется разархивация аккаунта (обратитесь в [службу технической поддержки](mailto:support@webim.ru)) или используйте активный аккаунт.

---

Источник: https://webim.ru/kb/dev/api/stored-data/overview.html