Перейти к основному контенту

HTTP API и OpenAPI / Swagger

Назначение

Клавдий предоставляет HTTP API для программного управления архивом и интеграции со сторонними системами: CRM, службами поддержки, ИИ-агентами, средствами автоматизации и аналитики.

Спецификация публикуется в формате OpenAPI 3.0.3 и доступна через Swagger UI.

Где открыть спецификацию

Swagger UI встроен в веб-интерфейс и доступен по адресу:

https://<адрес-узла>:<порт-WUI>/swagger/index.html

Ссылка [Документация к API] также доступна на главной странице веб-интерфейса.

Файл openapi.yaml является источником истины для маршрутов, параметров и схем запросов и ответов. Его можно использовать с openapi-generator или swagger-codegen для генерации клиентского SDK.

Доступные API

API Адрес Назначение Аутентификация
WUI API /api/..., порт 8001 поиск и просмотр архива, источники, задачи, настройки, кластер, пользователи JWT в HttpOnly-cookie access_token

Для интеграций используйте HTTP API веб-интерфейса. Доступные маршруты, поля и форматы ответов проверяйте в Swagger установленной версии.

Аутентификация WUI API

  1. Выполните POST /api/login и передайте username и password.
  2. Сервер вернёт JWT в HttpOnly-cookie access_token.
  3. В браузере cookie передаётся автоматически. Другой клиент может передать его вручную заголовком Cookie: access_token=<jwt>.

Права запроса определяются учётной записью:

  • администратор имеет полный доступ;
  • обычный пользователь работает со своими данными и письмами;
  • дополнительные ограничения задаются правилами доступа к разделам, данным и действиям. Для интеграции выдавайте учётной записи только необходимые права.

См. Правила доступа и RBAC.

Работа с длительной сессией

POST /api/login принимает username и password в JSON. Клиент должен сохранять cookie из ответа и учитывать её обновление сервером при продлении сессии. Маршрут обновления сессии и его параметры проверьте в Swagger установленной версии.

При ответе 401 выполните повторный вход; при 403 проверьте права. Для длительной интеграции не используйте постоянное значение токена, скопированное из браузера. Пример регулярного опроса с получением новой сессии: Мониторинг через Zabbix.

Основные группы маршрутов

В спецификации OpenAPI маршруты сгруппированы по тегам. Имена тегов приводятся в точном виде:

  • Auth — вход и выход;
  • Dashboard — состояние, метрики и самопроверка;
  • Archive — поиск, просмотр писем и вложений, API-импорт PST/EML/MSG;
  • Sources — создание и проверка источников EWS/IMAP/SMTP, запуск сбора;
  • Tasks — очередь задач, отмена и возобновление;
  • Schedules — расписания задач;
  • Settings — общие настройки, поиск, оповещения, SMTP- и IMAP-серверы;
  • Cluster — узлы и группы кластера;
  • Users, Groups, Rights — пользователи, группы и правила доступа;
  • Storages, StorageGroups, StorageRules — хранилища, группы и правила хранения;
  • LDAP — LDAP/AD;
  • TLS, License, Solr — сертификаты, лицензия и экземпляры поиска.

Большинство маршрутов WUI API используют схему GET/POST /api/{domain}/{action}. Отдельно определены /api/login, /api/logout, /api/archive/messages/{id}/attachments/{aid}/download и /api/archive/ingest.

Пример: войти и выполнить поиск

Замените адрес, логин и пароль своими значениями. При внутреннем центре сертификации передайте доверенный CA через --cacert. Если ответ входа требует дополнительного кода, сначала завершите второй шаг; порядок входа с RADIUS описан в справочнике API. Используйте один и тот же адрес при входе и последующих запросах, чтобы сохранённая cookie подходила серверу.

Установка лицензии

POST /api/license/upload устанавливает лицензию платной редакции. Требуется право изменять настройки. Пользовательская инструкция: Лицензирование и редакции.

Перед вызовом выполните вход, как показано выше, и сохраните cookie в cookies.txt. В примерах ниже используется https://klvd.example.ru:8001; замените его адресом своей установки. Для внутреннего центра сертификации укажите доверенный CA через --cacert.

Основной способ — загрузить исходный .lic как multipart/form-data (!) в поле license_file:

curl --silent --show-error --fail-with-body \
  --cookie cookies.txt --cookie-jar cookies.txt \
  --form 'license_file=@klavdii.lic' \
  'https://klvd.example.ru:8001/api/license/upload'

Альтернатива — передать содержимое файла в base64 в JSON-поле license_data_b64. Переносы строк внутри base64 допускаются. Для GNU/Linux пример без переносов:

base64 -w0 klavdii.lic > license.b64
python3 -c 'import json; from pathlib import Path; print(json.dumps({"license_data_b64": Path("license.b64").read_text()}))' > license-request.json
curl --silent --show-error --fail-with-body \
  --cookie cookies.txt --cookie-jar cookies.txt \
  --header 'Content-Type: application/json' \
  --data-binary @license-request.json \
  'https://klvd.example.ru:8001/api/license/upload'

Файлы license.b64 и license-request.json содержат ту же лицензию. После запроса удалите временные копии, если они больше не нужны.

Проверяйте не только HTTP-статус, но и тело ответа. Недействительная лицензия возвращает "ok": false и причину отказа; ранее установленная не заменяется. После успешной установки проверьте строку [Текущая лицензия] в веб-интерфейсе.

Собственный профиль пользователя

Эти вызовы относятся только к текущей учётной записи и доступны любому вошедшему пользователю. Они не дают права изменять чужие профили.

Вызов Параметры Назначение
GET /api/user/profile — логин, отображаемое имя, источник, группы, адреса почты и состояние двухфакторной аутентификации
POST /api/user/save-profile display_name изменить отображаемое имя локальной учётной записи
POST /api/user/save-notification notification_email указать адрес для оповещений
GET /api/auth/mfa-setup — получить secret_base32, ссылку otpauth_uri для приложения и срок настройки expires_in в секундах; настройка действует 10 минут
POST /api/auth/mfa-enable code; для локальной учётной записи также password включить TOTP
POST /api/auth/mfa-disable password для локальной учётной записи или code для внешней выключить TOTP

После изменения профиля повторно вызовите GET /api/user/profile и проверьте сохранённые значения. Порядок действий в интерфейсе: Просмотр и изменение профиля и Включение и смена двухфакторной аутентификации.

Вход с кодом RADIUS

Дополнительный запрос кода после пароля RADIUS

Если RADIUS запросил код, POST /api/login возвращает:

{"ok": false, "radius_challenge": "<токен>", "message": "<сообщение сервера RADIUS>"}

Повторите POST /api/login с тем же username, кодом в поле password и полученным токеном в radius_challenge. Токен действует 5 минут. Покажите пользователю текст message, чтобы он понимал, какой код требуется.

RADIUS как второй фактор после пароля домена

После верного пароля домена POST /api/login возвращает:

{"ok": true, "mfa_required": true, "mfa_method": "radius"}

Продолжите вход вызовом POST /api/auth/mfa-verify, передав код в поле code. Если сервер запросил ещё один код, ответ содержит "error": "radius_challenge" и текст в message. Повторите проверку со следующим кодом и сохранённой сессией.

Проверьте окончательный результат входа и доступ к разрешённому API. Ответ mfa_required — промежуточный шаг, даже если в нём указано "ok": true.

Настройка режима RADIUS

Для POST /api/radius/options требуется право изменять настройки.

Параметр Значения Назначение
mode password, second_factor альтернативный пароль или второй фактор после пароля домена
auto_create true, false создавать учётную запись при первом входе через RADIUS; применяется в режиме password

Текущие настройки возвращает GET /api/radius/config в поле options. После изменения прочитайте их повторно и проверьте выбранную схему входа. Порядок настройки через интерфейс: RADIUS.

Примеры интеграций

  • CRM может находить связанную переписку по адресу или теме и получать вложения.
  • ИИ-агент может читать письма и вложения через поиск или API-импорт и использовать их для классификации и ответов на запросы.
  • Средства автоматизации могут запускать сбор, отслеживать задачи и передавать метрики в систему мониторинга.
  • BI-система может получать объёмы по ящикам через /api/dashboard/mailbox-volumes, времена обработки и состояние кластера.

Для программной интеграции создавайте отдельную учётную запись с минимально необходимыми правами вместо использования администратора.

Проверьте файл OpenAPI

python3 -c "import yaml; yaml.safe_load(open('openapi.yaml'))"

Связанные материалы

Навигация по книге

Наверх