Доступ к HTTP API и 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
- Выполните
POST /api/loginи передайтеusernameиpassword. - Сервер вернёт JWT в HttpOnly-cookie
access_token. - В браузере cookie передаётся автоматически. Другой клиент может передать его вручную заголовком
Cookie: access_token=<jwt>.
Права запроса определяются учётной записью:
- администратор имеет полный доступ;
- обычный пользователь работает со своими данными и письмами;
- дополнительные ограничения задаются правилами доступа к разделам, данным и действиям. Для интеграции выдавайте учётной записи только необходимые права.
Работа с длительной сессией
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.
Пример: войти и выполнить поиск
# 1. Вход; cookie сохраняется в файл
curl --silent --show-error --fail-with-body \
--cookie-jar cookies.txt \
--header 'Content-Type: application/json' \
--data '{"username":"<логин>","password":"<пароль>"}' \
'https://klvd.example.ru:8001/api/login'
# 2. Поиск после завершённого входа
curl --silent --show-error --fail-with-body \
--cookie cookies.txt --cookie-jar cookies.txt \
--get --data-urlencode 'q=договор' --data 'page=1' \
'https://klvd.example.ru:8001/api/archive/search'
Замените адрес, логин и пароль своими значениями. При внутреннем центре сертификации передайте доверенный CA через --cacert. Если ответ входа требует дополнительного кода, сначала завершите второй шаг; порядок входа с RADIUS описан в справочнике API. Используйте один и тот же адрес при входе и последующих запросах, чтобы сохранённая cookie подходила серверу.
Лицензия, профиль и вход с кодом
В справочнике API описаны установка лицензии из файла, собственный профиль и продолжение входа с кодом RADIUS. Для многошагового входа сохраняйте cookie из каждого ответа: запрос кода является промежуточным шагом, а не завершённым входом.
Примеры интеграций
- CRM может находить связанную переписку по адресу или теме и получать вложения.
- ИИ-агент может читать письма и вложения через поиск или API-импорт и использовать их для классификации и ответов на запросы.
- Средства автоматизации могут запускать сбор, отслеживать задачи и передавать метрики в систему мониторинга.
- BI-система может получать объёмы по ящикам через
/api/dashboard/mailbox-volumes, времена обработки и состояние кластера.
Для программной интеграции создавайте отдельную учётную запись с минимально необходимыми правами вместо использования администратора.
Проверьте файл OpenAPI
python3 -c "import yaml; yaml.safe_load(open('openapi.yaml'))"
Связанные материалы
- HTTP API: справочник
- Правила доступа и RBAC
- Как выбрать способ сбора почты
- SMTP-форвардинг из CommuniGate Pro
- Коды ошибок
Навигация по книге
- Следующая статья: Балансировка нагрузки через HAProxy