Интеграция сторонних приложений

Cuento поддерживает внешние приложения через систему API-ключей. Стороннее приложение — бот, мост к другой платформе, инструмент автоматизации — аутентифицируется статическим ключом и работает в рамках набора прав, которые вы задаёте в панели администратора для каждого подфорума отдельно.

Как это работает

Каждое внешнее приложение получает собственный API-ключ и независимый набор прав. Приложение обращается к небольшому набору публичных эндпоинтов (без процесса входа) с ключом в заголовке запроса. Права выдаются пофорумно, поэтому можно разрешить приложению писать в одном подфоруме, оставив его в режиме только для чтения или полностью заблокированным в других.

Приложение опционально работает от имени конкретного пользователя форума: создаваемые им посты отображаются под именем этого пользователя.


Создание приложения

Перейдите в Администратор → Внешние приложения → Создать. Заполните:

Поле Назначение
Название Понятный человеку ярлык для приложения — отображается только в панели администратора
Статус Активно или неактивно. Неактивное приложение получает 403 на каждый запрос
Пользователь Аккаунт пользователя форума, от имени которого приложение создаёт посты. Обязательно для операций записи; необязательно для приложений только для чтения

После сохранения сгенерированный API-ключ показывается один раз. Скопируйте его сразу — он больше не отображается (хотя хранится в базе данных, и администратор при необходимости может найти его там).


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

Все эндпоинты внешних приложений находятся по пути /external-app/* и не требуют JWT. Приложение аутентифицируется, включая ключ в каждый запрос:

X-Api-Key: <ваш_api_ключ>

Отсутствующий или неизвестный ключ возвращает 401. Валидный ключ неактивного приложения возвращает 403.


Права

Права выдаются пофорумно. Откройте страницу редактирования приложения (Администратор → Внешние приложения → [название приложения]) и добавьте записи прав — каждая запись представляет собой комбинацию подфорума и действия.

Доступные действия:

Право Что разрешает
get_active_topics Получить список активных тем в подфоруме
get_first_post Прочитать первый пост любой темы в подфоруме
post Создать новый пост в теме в подфоруме

При каждом запросе эндпоинт проверяет соответствующее право для подфорума, к которому относится запрашиваемая тема. Если подходящей записи нет — возвращается 403.

Примечание: get_post (чтение любого поста по ID) и update_post (редактирование содержимого поста) также существуют в бэкенде, но не отображаются в форме прав в интерфейсе администратора — при необходимости их нужно добавлять через API напрямую.


API-эндпоинты

Все эндпоинты требуют заголовок X-Api-Key. Эндпоинты, работающие с подфорумами, проверяют права для подфорума запрашиваемой темы.

Список активных тем

GET /external-app/active-topics?subforum_ids=1,2&page=1

Требует право get_active_topics для каждого из запрашиваемых подфорумов.

Первый пост темы

GET /external-app/topic-first-post?topic_id=123

Требует право get_first_post для подфорума темы. Возвращает post_id, content (BBCode) и content_html.

Получить отдельный пост

GET /external-app/get-post/:id

Требует право get_post для подфорума поста. Возвращает post_id, post_content и post_author_id.

Создать пост

POST /external-app/post
{ "topic_id": 123, "content": "Содержимое в формате BBCode" }

Требует право post для подфорума темы. Требует, чтобы у приложения был задан Пользователь — пост создаётся от его имени. Возвращает { "post_id": ... }.

Обновить пост

POST /external-app/update-post/:id
{ "content": "Обновлённое содержимое в формате BBCode" }

Требует право update_post для подфорума поста. Требует, чтобы у приложения был задан Пользователь.


Управление приложением

На странице редактирования приложения вы можете:

  • Переименовать приложение или изменить связанного пользователя
  • Переключить статус между активным и неактивным (быстрый способ отключить приложение без удаления его и его прав)
  • Добавлять или удалять отдельные записи прав для подфорумов

Удаление приложения удаляет ключ и все его права.