Интеграция сторонних приложений
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 для подфорума поста. Требует, чтобы у приложения был задан Пользователь.
Управление приложением
На странице редактирования приложения вы можете:
- Переименовать приложение или изменить связанного пользователя
- Переключить статус между активным и неактивным (быстрый способ отключить приложение без удаления его и его прав)
- Добавлять или удалять отдельные записи прав для подфорумов
Удаление приложения удаляет ключ и все его права.