HTTP API и OpenAPI / Swagger
Раздел: Интеграции (внутри книги «Установка и настройка»). Связанные разделы: Сервер SMTP, SMTP-форвардинг из CommuniGate Pro.
Назначение
Клавдий предоставляет HTTP API для программного управления архивом и интеграции со сторонними системами: CRM, службами поддержки, ИИ-агентами, скриптами автоматизации, BI-инструментами.
Полная спецификация API — в формате OpenAPI 3.0.3, с интерактивным интерфейсом Swagger UI.
Где найти спецификацию
Интерактивный интерфейс Swagger UI встроен в веб-панель и доступен по адресу:
https://<адрес-узла>:<порт-WUI>/swagger/index.html
Ссылка «Документация к API» также есть на главной странице веб-панели.
Спецификация openapi.yaml — источник истины по маршрутам, параметрам, телам запросов и
ответам. Её можно скачать и подключить к генераторам клиентов (openapi-generator,
swagger-codegen) для получения SDK на нужном языке.
Два API
| API | URL | Назначение | Аутентификация |
|---|---|---|---|
| WUI API | /api/..., порт 8001 |
Управление архивом: поиск, просмотр писем, источники, задачи, настройки, кластер, пользователи | Сессионная — JWT в HttpOnly-cookie access_token |
| Storage(!) API | /put, /get, /check, /get-bulk, порт 8444 |
Межузловой обмен содержимым писем (внутренний) | JWT auth_token с claim(!) purpose |
Для интеграций со сторонними системами используется WUI API. Storage(!) API предназначен для обмена между узлами Клавдия и не применяется во внешних интеграциях.
Аутентификация
-
POST /api/loginсusernameиpassword— возвращает JWT в HttpOnly-cookieaccess_token. - Дальнейшие запросы к
/api/...передают cookie автоматически (браузер) или вручную заголовкомCookie: access_token=<jwt>(не-браузерные клиенты).
Роли и права:
- Администратор — полный доступ ко всем эндпоинтам.
- Пользователь — самообслуживание (свои данные, свои письма).
- Детальные права настраиваются через RBAC (см. Пользователи, права и группы):
секции (
SECTION_ARCHIVE_MESSAGES,SECTION_SETTINGS, …) и действия (can_list/can_view/can_edit_details/can_create/can_delete_entity/can_action_*).
Что доступно через API
Основные группы эндпоинтов (теги в спецификации):
- 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 — преимущественно generic:
GET/POST /api/{domain}/{action}. Специальные маршруты:/api/login,/api/logout,/api/archive/messages/{id}/attachments/{aid}/download,/api/archive/ingest.
Пример: получить сессию и найти письмо
# 1. Вход — cookie сохраняется в файл
curl -k -c cookies.txt -X POST https://127.0.0.1:8001/api/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"<пароль>"}'
# 2. Поиск по архиву (cookie передаётся из файла)
curl -k -b cookies.txt 'https://127.0.0.1:8001/api/archive/search?q=договор&page=1'
Сценарии интеграции
- CRM — по письму из CRM находить переписку в архиве (поиск по адресу/теме), подтягивать вложения.
- ИИ-агенты — читать содержимое писем и вложений (через API-импорт или поиск), классифицировать, отвечать на запросы пользователей по данным архива.
- Скрипты автоматизации — запускать сбор из источников, отслеживать задачи, выгружать метрики в системы мониторинга.
-
BI / аналитика — агрегировать объёмы по ящикам (
/api/dashboard/mailbox-volumes), времена обработки, состояние кластера.
Для программ, работающих от имени пользователей, заводите отдельные учётные записи с минимально нужными правами (RBAC), а не используйте администратора.
Проверка спецификации
# Синтаксис YAML:
python3 -c "import yaml; yaml.safe_load(open('openapi.yaml'))"
См. также
- Пользователи, права и группы — учётные записи для интеграций, RBAC.
- Источники писем — API-импорт PST/EML/MSG.
- SMTP-форвардинг из CommuniGate Pro — push-вариант интеграции с почтовым сервером.
- Коды ошибок — расшифровка кодов в ответах и журнале.
Навигация по книге
- Следующая статья: Порты и сетевые соединения