События сервиса

Сервис может сообщить о действии пользователя — например, что отчёт готов — и запустить связанную автоматизацию. Сначала администратор создаёт определение события в интерфейсе, а код сервиса затем вызывает его через SDK. Метод emitEvent не создаёт новое определение и не создаёт автоматизацию.

1. Сохраните сервис, чтобы у него появился постоянный ID.
2. Откройте вкладку События со значком молнии. У сервиса по ссылке реестр можно открыть кнопкой событий в общем списке сервисов.
3. Нажмите Создать событие. В отдельном окне укажите название, техническое имя латиницей (report_ready), описание и состояние «Событие включено».
4. Скопируйте пример вызова из элемента списка. Полный код сервер сформирует сам: для сервиса № 42 получится custom.service_42.report_ready.
5. В Администратор → Автоматизации откройте сценарий и нажмите квадратную кнопку с молнией Событие сервиса в шапке рядом с удалением. В открывшемся окне найдите событие по названию или сервису, отметьте его и нажмите Выбрать событие. Проверьте конфигурацию, обработчик и назначение, сохраните и включите автоматизацию.
6. Вызовите событие из опубликованного сервиса после нужного действия пользователя.

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

Вызов из JavaScript

Для встроенного сервиса экземпляр synchra уже предоставлен движком. Выполняйте пример внутри асинхронного обработчика кнопки после проверки интеграции:

if (!(await synchra.isSynchraIntegrated())) {
  throw new Error('Откройте сервис внутри Synchra.');
}

// Один ключ на одну операцию. Сохраните его, если потребуется повтор запроса.
const requestKey = crypto.randomUUID();
const result = await synchra.emitEvent(
  'report_ready',
  { report_id: '125' },
  { requestKey },
);

if (result.preview) {
  // Предпросмотр: реального запуска нет.
} else {
  // result.event_id — подтверждение приёма в очередь, не завершения сценария.
}

В SDK передаётся локальное имя report_ready. Полный код custom.service_42.report_ready нужен для триггера автоматизации, а не для первого аргумента emitEvent. Передавать токен пользователя, ID компании или системный тип события в вызове не нужно: их определяет авторизованный мост.

payload — JSON-объект до 32 КБ. Для одного действия сохраняйте тот же requestKey при повторе: одинаковые ключ и данные не создадут повторное событие. С другими данными прежний ключ даст ошибку 409. Ключи сохраняются не менее 24 часов. Без requestKey каждый вызов получает новый ключ и считается отдельной операцией. Отключайте кнопку на время отправки и показывайте пользователю загрузку, успех приёма или ошибку; не вызывайте событие при каждом рендере и не делайте бесконечных автоматических повторов.

Доступность и ограничения

emitEvent — расширение SDK встроенного веб-сервиса. Не следует считать его методом любой установленной версии npm-пакета @synchra24/app: в редакторе его предоставляет веб-движок. Мобильный мост пока не поддерживает этот вызов. В предпросмотре возвращаются preview: true и accepted: false; настоящие автоматизации не запускаются.

Для создания событий нужны возможность Приложения в подписке и право редактирования сервисов. Для настройки связанной автоматизации — API-интеграция и право управления интеграциями. События работают только для сотрудников с доступом к сервису.

Количество отправок ограничено, чтобы случайные повторные нажатия не перегружали систему. Для одного сотрудника и события допускается до 30 вызовов в минуту; также действуют общие ограничения сервиса и компании. При слишком частых вызовах нужно подождать перед повтором. Если отправка не удалась, сервис должен показать ошибку, а не сообщение об успешном запуске.

Подробнее о настройке и истории — в статье «Запуск по событиям Synchra24».