Публичный API, токены и вебхуки

Внешние системы взаимодействуют с платформой по REST, а сценарии принимают вызовы по вебхуку. Справочник установленной версии доступен на экране Документация API: там можно найти методы, их параметры и форматы ответов. Эта глава объясняет выпуск токенов, запуск сценариев по вебхуку, контроль доступа и нагрузки.

Что вам понадобится

• учётная запись в платформе и доступ к разделу Профиль → Безопасность;
• членство в том рабочем пространстве, с которым будет работать интеграция;
• право integrations:view в этом пространстве — для вызова вебхук-триггеров с авторизацией;
• адрес инсталляции платформы вида https://<ваш-домен>;
• глобальная роль admin — для разделов Токены API и Политики API.

Где посмотреть описание API вашей инсталляции

Выберите Документация API в меню учётной записи внизу левого меню. Страница доступна любому участнику и не требует глобальной роли admin. Описание загружается из самой инсталляции: версия и число операций показаны рядом с заголовком, кнопка OpenAPI открывает машинное описание.

Быстрый старт объясняет общие соглашения. Поле Найти операцию и список Разделы помогают выбрать нужную часть справочника; карточка операции раскрывает Параметры, Тело запроса и Ответы, если они предусмотрены. Отдельный раздел посвящён запуску сценария вебхуком. За рекомендациями для конкретной интеграции обратитесь к команде сопровождения Уника AI.

Как выпустить и отозвать персональный API-токен

Токен вы выпускаете в разделе Профиль → Безопасность, и платформа показывает его значение ровно один раз. Платформа хранит только хеш токена, поэтому восстановить значение нельзя: потерянный токен отзовите и выпустите новый.

1. Откройте Профиль → Безопасность.
2. Нажмите Выпустить новый токен.
3. В диалоге Новый API-токен заполните Название.
4. Выберите Срок действия.
5. Нажмите Выпустить.
6. В блоке Новый токен нажмите Скопировать и сохраните значение в своём хранилище секретов.

Название обязательно, не длиннее 64 символов; пустое поле вызывает ошибку Укажите название токена. Назовите токен по системе, которая будет его использовать: это имя видно и вам, и администратору. Сроки: 30 дней, 90 дней, 180 дней, 365 дней и Без срока. По умолчанию выбрано 90 дней. Бессрочный токен придётся отзывать вручную.

Значение — 64 шестнадцатеричных символа. Блок Новый токен хранит его до перезагрузки страницы. В списке показаны имя, маска вида •••• 1234, состояние Активен или Истёк, дата создания, дата истечения либо Без срока, последнее использование либо Ещё не использовался. Истёкшие токены остаются в этом списке, но вызовы с ними получают 401. Токены, выпущенные до версии 1.2, остаются бессрочными: срок задним числом не назначается.

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

Чтобы прекратить доступ, нажмите Отозвать в строке нужного токена. Отзыв применяется сразу: следующий запрос с этим значением получит 401. Отозванные токены остаются в списке под свёрнутым блоком Отозванные токены с датами выпуска и отзыва — это история, а не действующий доступ.

Токены привязаны к учётной записи и живут вместе с ней. Если администратор переводит пользователя в статус disabled, платформа отзывает все его персональные токены, и интеграции на этой учётной записи останавливаются.

Выпустить токен можно только под сессией входа в интерфейс. Попытка выпуска с авторизацией другим токеном возвращает 403 с кодом TOKEN_ISSUE_REQUIRES_SESSION.

Как посмотреть все токены установки и отозвать доступ

Реестр открывается в Администрирование → Интеграции и API → Токены API и доступен глобальному администратору. Выпускать токены здесь нельзя — владелец делает это в своём профиле.

Сузить выборку помогают Поиск токенов и состояния Все статусы, Активные, Истёкшие, Отозванные. По заголовкам Токен, Обращение и Вызовов можно сортировать. При поиске счётчик рядом с заголовком показывает долю найденных строк от общего числа.

Чтобы закрыть доступ, откройте меню активного токена, выберите Отозвать и подтвердите действие в диалоге Отозвать токен «название»?. Истёкшие и отозванные токены меню действий не имеют. Следующий запрос с отозванным значением перестанет проходить; другие токены продолжат работать. Отзыв необратим, для восстановления доступа владелец выпускает новый токен в профиле.

Если токены ещё не выпускались, реестр сообщает об этом. Если ничего не найдено по фильтрам, нажмите Сбросить поиск и фильтры.

Как запустить сценарий по вебхуку

Сценарий получает собственный URL, если начинается с узла Webhook. Поведение узла задают три поля инспектора в редакторе сценария.

Адрес начинает принимать вызовы после публикации сценария и сохраняется между публикациями.

curl -X POST https://<ваш-домен>/api/public/workflows/triggers/<slug> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"4172","comment":"Клиент просит перенести срок"}'

Платформа принимает тело как JSON независимо от заголовка Content-Type. В сценарии тело доступно как inputs.channel.webhook.body, рядом лежат query, headers и method.

Важно. При режиме Bearer personal token платформа проверяет не только токен, но и членство его владельца в пространстве сценария и право integrations:view.

Что вернётся вызывающей стороне

Асинхронный режим отвечает сразу, синхронный держит соединение до конца прогона. Синхронный режим подходит для коротких сценариев, которые должны вернуть результат в том же запросе; долгие процессы запускают асинхронно и забирают результат отдельно.

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

curl -H "Authorization: Bearer <token>" \
  https://<ваш-домен>/api/public/workflows/triggers/<slug>/runs/<id-прогона>

Незавершённый прогон отдаёт { "ok": true, "done": false, "status": "…" }, завершённый — то же тело, что и синхронный вызов.

Чем вебхук отличается от интеграции ассистента без кода

Вебхук — это входящий вызов: инициативу проявляет внешняя система, платформа запускает сценарий и отвечает. Интеграция ассистента без кода устроена наоборот: логика ответа остаётся в платформе, её описывает сценарий, а внешние сервисы сценарий вызывает сам узлом HTTP Request. Выбирайте вебхук, когда событие рождается во внешней системе, и интеграцию без кода, когда пользователь работает в интерфейсе платформы, а обработку собирает сценарий. Подробности второго контура — в главе Интеграция ассистента без кода.

Как защитить программный доступ

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

• Заведите под интеграцию отдельную учётную запись и включите её только в те пространства, которые ей нужны.
• Соберите для неё роль под конкретные операции вместо роли администратора пространства.
• Храните токен в хранилище секретов, а не в коде, конфигурации репозитория или задаче в трекере.
• Задавайте срок при выпуске и меняйте токен по расписанию: выпустите новый, переключите интеграцию, затем отзовите старый. По умолчанию срок — 90 дней; бессрочный вариант требует ручного контроля.
• Отзывайте токен сразу, если он попал в лог, переписку или скриншот.

В Администрирование → Обзор, на вкладке Сводка, блок Активность публичного API показывает вызовы за период, ошибки вызывающего, отказы по потолку и среднее время ответа. Таблица Кто ходит помогает проверить, перестала ли интеграция использовать старый токен после замены — см. Эксплуатация платформы.

Как ограничить нагрузку на публичный API

Глобальный администратор задаёт ограничения в Администрирование → Интеграции и API → Политики API. Они действуют на всю инсталляцию и применяются к следующим вызовам без перезапуска.

Суточные счётчики обнуляются в 00:00 по UTC. В положении Авто параметр использует показанное системное значение. При выключении Авто появляются поле и ползунок; 0 отключает ограничение. После правки доступны Сохранить и Отмена.

Строка Худший случай в памяти показывает произведение одновременных загрузок на экземпляр и потолка файла. Это объём, который потребуется при одновременной обработке предельных файлов.

Важно. Если произведение превышает 2 ГБ, настройки не сохранятся. Уменьшите число одновременных загрузок или потолок файла. Системные значения дают ровно 2 ГБ, поэтому увеличение одного из этих параметров требует уменьшения другого.

Режим наблюдения считает превышения, но не отклоняет вызовы. Перед введением ограничений на работающей инсталляции можно включить наблюдение, задать потолки и оценить превышения, затем выключить наблюдение для применения ограничений.

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

Частые вопросы

Где взять полное описание методов API

Откройте Документация API в меню учётной записи; кнопка OpenAPI отдаёт машинное описание установленной версии. За составом методов и рекомендациями под вашу интеграцию обратитесь к команде сопровождения Уника AI.

Почему запрос возвращает 401, хотя токен свежий

Токен не прочитан платформой. Проверьте:

• заголовок передан целиком, в формате Authorization: Bearer <token>, без кавычек вокруг значения;
• токен имеет состояние Активен, его срок не истёк;
• токен не отозван в профиле или администратором на странице Токены API;
• учётная запись активна: деактивация пользователя отзывает все его токены.

Почему вебхук отвечает 404

Адрес не зарегистрирован. Платформа регистрирует триггер в момент публикации сценария, поэтому черновик с узлом Webhook вызовы не принимает. Опубликуйте сценарий и скопируйте адрес заново из инспектора узла.

Почему синхронный вебхук возвращает пустой результат

В сценарии нет узла Ответ на вебхук, а завершающий узел не передал текст. Без этого узла синхронный вызов отдаёт служебное тело с полем result, которое может оказаться пустым. Добавьте узел Ответ на вебхук и задайте в нём статус, заголовки и тело ответа.

Что происходит с кредитами при запуске по вебхуку

Списание идёт по общим правилам: прогон сценария попадает в потребление пространства, в котором сценарий опубликован, и виден в журнале прогонов и в разделе Потребление.

Почему вызов вернул 429 с упоминанием суточной квоты

Исчерпана квота пространства или пользователя. В отказе указано время обнуления по UTC. Дождитесь обнуления или обсудите квоту с администратором, который управляет Политиками API.

Почему вызовы API не видны в списке чатов

Для публичного API платформа создаёт служебный чат-контейнер с вложениями и ходом работы. Он не показывается в списке и поиске чатов; открыть его можно по прямой ссылке с chatId из ответа. Вебхук сценария создаёт обычный чат Webhook <slug> у учётной записи исполнителя триггера. Чаты API, созданные до версии 1.2, остаются в списке.

Что дальше

• Эксплуатация платформы — активность публичного API и наблюдение за инсталляцией.

• Сценарии — как собрать сценарий с узлом Webhook и вернуть ответ вызывающей стороне.

• Интеграция ассистента без кода — второй контур интеграции, в котором обработку описывает сценарий платформы.

• Роли и права доступа — как собрать роль под интеграцию и выдать минимальные права.

• Раздел администрирования — где находятся журналы запусков и прогонов.