Solavel Документы
Русский

Интеграции

Последнее обновление

Вкладка Интеграции проекта связывает один проект с другими системами:

  • Исходящие веб-хуки отправляют события проекта (задача создана, спринт начался, документ создан…) на принадлежащий вам HTTPS-эндпоинт с цифровой подписью, которой получатель может доверять.
  • Токены входящих webhook позволяют внешней системе (инструменту форм, GitHub, скрипту) создавать задачи или комментарии в проекте.
  • Токены Публичного API предоставляют другой системе ограниченный доступ на чтение или запись к задачам и времени проекта через API SolaProjects.
  • Готовность встроенных провайдеров показывает готовые подключения (Slack, Microsoft Teams, GitHub, GitLab, Google Calendar, Google Drive, OneDrive, Zapier / IFTTT) и возможность подключения каждого.

Используйте функцию, когда проекту нужно взаимодействовать с другим инструментом — например, отправлять обновления задач на панель клиента или превращать обращения с сайта в задачи. Её настраивают руководители и администраторы проекта; обычно один раз для проекта совместно с вашим ИТ-специалистом.

Две страницы называются «Интеграции». Здесь описывается вкладка проекта. Пункт Интеграции в разделе Рабочее пространство боковой панели (/projects/settings/integrations) — это подключение организации к SolaCount. См. ниже Подключение организации к SolaCount и Бюджет и финансы.

#Где найти

Боковая панель Раздел Проект → Интеграции (между разделами Автоматизации и ИИ)
URL /projects/{project}/integrations
Командная строка Интеграции · {project name} в разделе Текущий проект

Кто это видит:

  • Тариф: интеграции являются функцией тарифа Премиум (а также Корпоративного). На более низких тарифах вкладка скрыта. Если срок действия платного тарифа истекает, вкладка исчезает, а веб-хуки перестают предлагаться до продления.
  • Роль: вкладку могут открыть только пользователи, которые могут редактировать проект (см. Права доступа). Остальные видят "Не удалось загрузить интеграции." с кнопкой Повторить.

#Обзор экрана

#Карточка заголовка

Интеграции — Исходящие webhook, входящие токены и история доставки.

Блок Значение
Исходящие Активные исходящие веб-хуки.
Входящие токены Активные, не отозванные входящие токены.
Последние отправки Попытки доставки, перечисленные в Последних доставках.
Неудачные доставки Неудачные попытки среди них (красным, если больше нуля).

#Карточка исходящих webhook

Отправка событий проекта на внешний HTTPS-эндпоинт, подписанный с помощью HMAC-SHA256. Новый веб-хук в правом верхнем углу.

Каждая карточка вебхука показывает название, URL конечной точки, отметку статуса (Активен, Отключён или В архиве), по одной отметке на каждое событие подписки и {n} доставок · {n} ошибок. Действия строки (кроме архивных вебхуков): Редактировать, Проверить, Заменить секрет, Архивировать.

Пустое состояние: Нет исходящих веб-хуков — Создайте один, чтобы отправлять события в внешнюю систему.

#Карточка токенов входящих веб-хуков

Разрешите внешним системам создавать задачи и комментарии, отправляя POST с секретным токеном. Новый токен справа вверху.

Каждая карточка токена: название, провайдер (Пользовательский или GitHub) · последнее использование {date} или не использовался, отметка Активен, Неактивен или Отозван. Действия (кроме отозванных токенов): Заменить, Отозвать.

Пустое состояние: Нет входящих токенов — Создайте токен для приема входящих веб-хуков.

#Карточка публичного API

Создавайте токены носителя с ограниченной областью действия для документированных эндпоинтов проектов, задач и учета времени. Кнопки: Документация (открывает справочник OpenAPI в новой вкладке) и Новый токен.

Каждая карточка токена: имя, last used {date} / never used, значок статуса, по одной метке на каждое право. Действия: Rotate, Revoke.

Пустое состояние: Нет API-токенов — Создайте токен для публичного API.

#Карточка последних поставок

Попытки исходящей доставки и их результаты. Бейдж с количеством.

Столбец Значение
Когда Дата доставки.
Вебхук Имя веб-хука или Архивированный веб-хук.
Событие Тип события, например task.status_changed.
Статус Доставлено (зеленый), Ожидает обработки (желтый, ожидание или повторная попытка), Ошибка (красный), Пропущено.
Попытки Сколько раз SolaProjects выполнил попытку.
Ответ Код статуса HTTP, возвращённый вашей конечной точкой, ошибка, если ответ не был получен, или —.
(кнопка) Повторить попытку для любой недоставленной отправки.

Пустое состояние: Пока нет доставок — Попытки доставки появятся здесь, как только сработает событие или вы отправите тест.

#Карточка готовности нативного провайдера

Состояние подключения и предварительные условия настройки для интеграций конкретных провайдеров. Одна плитка на провайдера:

Провайдер Что он делает
Slack Отправлять уведомления о проекте в Slack и получать команды задач из Slack.
Microsoft Teams Отправлять уведомления о проекте в каналы Teams и поддерживать действия Teams.
GitHub Связывать события репозитория, задачи, pull-запросы и коммиты с задачами проекта.
GitLab Связывать merge-запросы GitLab, задачи и события конвейера с задачами проекта.
Google Calendar Синхронизировать вехи проекта и даты задач с Google Calendar.
Google Drive Прикреплять или синхронизировать документы проекта с папками Google Drive.
OneDrive Прикреплять или синхронизировать документы проекта с папками OneDrive.
Zapier / IFTTT Предоставление доступа к SolaProjects триггерам и действиям для платформ без кода.

Каждая плитка показывает статус (Доступно, Ожидает, Активно, Ошибка), возможность и либо Обнаружена рабочая конфигурация провайдера., либо Доступен локальный симулятор; рабочие учётные данные задаются при активации., если провайдер ещё не активен для организации. Также могут отображаться Заблокировано из-за отсутствующих настроек: …, Примечания активации: …, Ожидается обратный вызов OAuth., Последняя ошибка: …, последнее сообщение или полученное событие.

#События, которые можно отправить

Отметьте одно или несколько полей в форме веб-хука:

Событие Отправляется, когда
task.created Задача создается (в том числе из входящего webhook).
task.updated Задача редактируется.
task.status_changed Статус задачи изменяется.
task.completed Задача отмечена как выполненная.
task.blocked Задача отмечена как заблокированная.
comment.created Добавляется комментарий к задаче.
doc.created Создается документ проекта.
time_entry.created Время учтено.
milestone.completed Веха выполнена.
sprint.started / sprint.completed Спринт начинается / завершается.
share_link.created Создана ссылка для гостевого доступа.
automation.run_failed / automation.rule_failed Запуск автоматизации завершился с ошибкой.
ai.suggestion_applied Применено предложение ИИ.

Каждый запрос — это JSON POST с заголовками X-SolaProjects-Event (тип события), X-SolaProjects-Delivery (идентификатор доставки) и X-SolaProjects-Signature (HMAC-SHA256 исходного тела с вашим секретом подписи), а также User-Agent: SolaProjects-Webhooks/1.0. Проверьте подпись, прежде чем доверять запросу.

Повторные попытки. Сбой доставки автоматически повторяется примерно через 1, 5, 15 и 60 минут; после пятой попытки статус меняется на Ошибка. Используйте кнопку Повторить попытку, чтобы повторить отправку вручную.

#Задачи

#Создать исходящий веб-хук

  1. Откройте проект → Интеграции → Новый webhook.

  2. Заполните Новый исходящий webhook:

    Поле Требуется Правила / значения по умолчанию Примечания
    Имя Да До 160 символов. например, Панель клиента.
    URL-адрес конечной точки (HTTPS) Да Корректный URL, до 2048 символов, публичный HTTPS. Плейсхолдер https://example.com/hooks/solaprojects. Локальные адреса и адреса в частных сетях отклоняются: "Используйте публичный HTTPS-эндпоинт. URL-адреса локальных и частных сетей заблокированы."
    События Да Хотя бы одно. См. таблицу выше.
    Активный — Выбрано по умолчанию. Снимите флажок, чтобы сохранить его как Отключено.
  3. Нажмите Создать. Появится Исходящий вебхук создан. и диалог Секрет подписи: «Сохраните его сейчас: он показывается только один раз, и позже его нельзя получить». Нажмите Копировать (Скопировано в буфер обмена.), сохраните секрет в принимающей системе, затем нажмите Готово.

#Изменение, тестирование, ротация и архивация веб-хука

Действие Шаги Результат
Редактировать Измените имя, URL, события или параметр Активно → Сохранить. Исходящий вебхук обновлен.
Тест Нажмите Тест. Тестовая доставка поставлена в очередь. Строка появляется в разделе Недавние доставки.
Ротировать секрет Подтвердите Сменить секрет — "Текущий секрет перестанет работать. Обновите подключенные сервисы новым секретом." Секрет обновлен. Новый секрет показывается один раз.
Архив Подтвердите Архивировать webhook — "Этот исходящий webhook перестанет передавать события проекта." Веб-хук отправлен в архив. Бейдж В архиве; доставки прекращены; история сохранена.

#Создать токен входящего веб-хука

  1. Нажмите Новый токен в разделе Входящие токены webhook.
  2. Название (обязательно, до 160 символов) и Провайдер: Пользовательский (по умолчанию) или GitHub.
  3. Нажмите Создать → Входящий токен создан. Скопируйте Токен входящего веб-хука, отображаемый только один раз: "Используйте его в качестве токена в URL входящего веб-хука. Отображается только один раз."

Затем внешняя система отправляет POST /api/projects/webhooks/incoming/{token} с телом в формате JSON (лимит 60 запросов в минуту от одного отправителя):

Провайдер Тело документа Что происходит
Пользовательский {"title": "...", "description": "...", "priority": "high"} Создает приватную задачу в списке Сделать (приоритет по умолчанию medium; заголовок обрезается до 180 символов). Ответ содержит новый task_key.
Пользовательский {"task_key": "ALN-14", "comment": "..."} Добавляет внутренний комментарий к этой задаче.
GitHub Событие проблемы или комментария к проблеме Проблема становится задачей; комментарий к проблеме, название которой содержит ключ задачи (например, ALN-14), становится комментарием к этой задаче.

Все остальное отклоняется с сообщением "Веб-хук отклонен."; отозванный или неверный токен получает тот же ответ. Авторами задач и комментариев является лицо, создавшее токен.

Заменить выпускает новый токен и сразу отзывает старый (Токен заменён.). Отозвать запрашивает подтверждение Отозвать токен — «Запросы с этим токеном больше не будут иметь доступа». → Токен отозван.

#Создать публичный токен API

  1. Нажмите Новый токен в разделе Публичный API.

  2. Имя (обязательно, до 120 символов) и Права (хотя бы одно; projects:read, tasks:read и time:read выбраны по умолчанию):

    Право Разрешает
    projects:read Прочитайте этот проект.
    tasks:read / tasks:write Чтение / создание и обновление задач.
    time:read / time:write Чтение / создание записей учёта времени.
  3. Создать → API-токен создан. Скопируйте API-токен проекта: «Используйте его как Bearer-токен для /api/v1. Показывается только один раз.»

Задачи, созданные через API, запускают те же автоматизации и вебхуки, что и задачи из приложения. Заменить → подтвердите Заменить токен («Текущий токен перестанет работать. Укажите новый токен в подключённых сервисах».) → Токен API заменён. Отозвать → Токен API отозван.

#Повторить попытку неудачной доставки

В разделе Недавние доставки нажмите Повторить попытку в строке → Доставка повторена. Через мгновение проверьте Статус и Ответ.

#Подключить нативного провайдера

  1. На плитке провайдера выберите канал (например, #projects для Slack) и нажмите Подключить → Подключение {Provider} начато.
  2. Завершите диалог авторизации Авторизация {Provider} с помощью Завершить обратный вызов (или Позже) → Нативная интеграция подключена.
  3. После подключения используйте Отправить тест (Тестовое сообщение {Provider} отправлено.), Обновить ({Provider} обновлено.) или Отключить ({Provider} отключено.).

Плитки в режиме симулятора также показывают Имитировать событие и Ошибка для проверки настройки до запуска провайдера; они не обращаются к реальному сервису.

#Статусы

Объект Статусы
Исходящий веб-хук Активно, Отключено (сохранено с отключенным параметром «Активно»), В архиве
Доставка Ожидает обработки, Доставлено, Ошибка, Пропущено
Входящий / API токен Активно, Неактивно, Отозван
Нативный провайдер Доступно, Ожидает, Активно, Ошибка

#Разрешения

Роль Открыть вкладку Создавать / изменять webhook, токены, провайдеров
Владелец организации Да Да
Администратор проектов Да Да
Менеджер проектов, который здесь является проектным Менеджером Да Да
Участник проектов, проектный Наблюдатель, гости Нет Нет

Если редактирование интеграций отключено для организации, вкладка доступна только для чтения (без Создать, действий строк и Повторить). Отклонённое изменение вызывает «Изменения интеграций отключены или не разрешены».; устаревшая страница — «Обновите страницу и повторите попытку». Секреты и токены никогда не показываются повторно после одноразового диалога — даже владельцам.

#Подключение SolaCount организации

Пункт Интеграции в боковой панели рабочего пространства (/projects/settings/integrations) открывает другую страницу. Она показывает подключение SolaProjects к SolaCount (Подключено, Готово к подключению, Интеграция приостановлена, Отключено — история сохранена, …) и позволяет владельцу организации или финансовому администратору подключить, приостановить, отключить или проверить связь. Отдельный проект может отказаться от неё во вкладке Настройки (карточка Интеграции → Внутренний проект / финансы отключены). См. Бюджет и финансы и Обзор SolaProjects.

#Примеры из практики

#Пример 1 — Запросы становятся задачами (повседневный)

{User 1 name} хочет, чтобы обращения с сайта по проекту {Showroom project name} (DEMO-FIT) создавались как задачи.

  1. Новый токен → Имя Запросы с сайта, Провайдер Пользовательский → Создать; она передает токен веб-разработчику.
  2. Веб-сайт отправляет {"title": "Quote request – reception desk", "priority": "high"}.
  3. Задача ALN-31 Запрос ценового предложения – стойка регистрации появляется в списке Сделать, приватная, приоритет высокий. На карточке токена отображается информация последнее использование 6 окт.

#Пример 2 — лента данных панели клиента со сбоем (полный сценарий)

{User 2 name} подключает панель управления сайта {Organization name}.

Шаг Действие Результат
1 Новый веб-хук: Панель управления сайта, https://hooks.company.example.com/projects, события task.status_changed, task.completed, milestone.completed. Исходящий веб-хук создан.; секрет подписи скопирован на панель управления.
2 Тест. Тестовая доставка поставлена в очередь.; строка Доставлено, Ответ 200.
3 {User 1 name} перемещает ALN-12 в статус Готово. Две доставки: task.status_changed и task.completed, обе со статусом Доставлено.
4 Панель управления отключена на техническое обслуживание. Следующая доставка показывает Ожидание, затем Ошибка с ответом 503; в заголовке красным Неудачных доставок 1; повтор выполняется примерно через 1, 5, 15 и 60 минут.
5 Панель управления снова работает; {User 2 name} нажимает Повторить попытку. Доставка повторена. → Доставлено.
6 ИТ-отдел подозревает утечку секрета. {User 2 name} нажимает Обновить секрет и подтверждает действие. Секрет обновлен. Новый секрет показывается один раз; ИТ-отдел обновляет панель управления.

#Как это связано

Где Ссылка
Задачи Входящие токены и API создают задачи и комментарии; изменения задач отправляют события.
Планирование Завершение этапа и начало/завершение спринта отправляют события.
Автоматизация Действуйте внутри SolaProjects; неудачные запуски можно отправить наружу как события.
Гостевые ссылки для общего доступа событие share_link.created.
ИИ событие ai.suggestion_applied.
Учет времени Событие time_entry.created; возможности API времени.
Настройки Переключатель SolaCount финансов для каждого проекта.

#Советы и частые проблемы

Проблема Причина Решение
Вкладка отсутствует. Тариф ниже Premium или срок действия истек. Обновите или продлите подписку.
Используйте публичную конечную точку HTTPS… URL-адрес является http, localhost или частным адресом. Используйте публичный URL с HTTPS.
Потерян секрет или токен. Отображается только один раз. Перевыпустите и обновите другую систему.
Доставки с кодом 4xx имеют статус Ошибка. Ваш эндпоинт отклоняет запрос (часто из-за проверки подписи). Убедитесь, что эндпоинт использует текущий секрет.
Веб-хук отклонен. при входящих вызовах. Отозванный/неверный токен или в теле нет title или task_key + comment. Проверьте токен и тело запроса.
Комментарий не добавлен из GitHub. У названия выпуска нет ключа задачи. Укажите ключ (например, ALN-14) в названии вопроса.
API возвращает отказ в доступе. У токена нет нужного права или он отозван. Создайте токен с нужными правами.
Провайдер сообщает: Локальный симулятор доступен… Пока не доступно для вашей организации. Обратитесь в службу поддержки Solavel по вопросу активации.