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

HTTP API и OpenAPI / Swagger

Раздел: Интеграции (внутри книги «Установка и настройка»). Связанные разделы: Сервер SMTP, SMTP-форвардинг из CommuniGate Pro.

Назначение

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

Полная сСпецификация API —публикуется в формате OpenAPI 3.0.3, с3 и доступнта черактивным интерфейсомз Swagger UI.

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

Интерактивный интерфейс Swagger UI встроен в веб-паинтельрфейс и доступен по адресу:

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

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

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

Дваоступные API

API URLАдрес Назначение Аутентификация
WUI API /api/..., порт 8001 Управление архивом: поиск, и просмотр пархисемва, источники, задачи, настройки, кластер, пользователи Сессионная — JWT в HttpOnly-cookie access_token
Storage(Storage API (!) API /put, /get, /check, /get-bulk, порт 8444 Мвнутрежузловонний обмен содержимым писем (внмеждутренн узламий) JWT auth_token с claim(полем (claim (!)) purpose

Для внешних интеграций со сторонними системами используйтется WUI API.API. Storage(!)Storage API предназначен для обмвнутренаних соединений между узлами Клавдия и не применяется во внешних интеграциях.

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

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

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

  • Аадминистратор —имеет полный доступ ко всем эндпоинтам.;
  • обычный Ппользователь —работает самообслуживание (своими данные,ми свои письма).ми;
  • Ддополнитетальные погравничения за настраивдаются RBAC (!) через RBAC (см. Пользователи, права и группы): секции, (например SECTION_ARCHIVE_MESSAGES, и SECTION_SETTINGS, …) и действия (can_list/, can_view/, can_edit_details/, can_create/, can_delete_entity/, can_action_*).

Что

См. {{ССЫЛКА:install.rbac|Правила доступа и RBAC}}.

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

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

При ответе 401 выполните повторный вход; при 403 проверьте права. Для длительной интеграции не используйте постоянное значение токена, скопированное из браузера. Пример регулярного опроса с получением новой сессии: {{ССЫЛКА:install.integration-zabbix|Мониторинг через APIZabbix}}.

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

(теги в

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

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

Большинство

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

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

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

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

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

Проверкьте файл спецификацииOpenAPI

# Синтаксис YAML:
python3 -c "import yaml; yaml.safe_load(open('openapi.yaml'))"

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

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

Наверх