Synchra.24
menu_bookDocumentation
Practical guides for setup and development

Find guides for getting started, building workflows and adding your own tools to your company workspace.

folderEmbedded services

Service Events

Event registration, emitEvent call, communication with automations, and restrictions.

Translation is currently unavailable. The original is shown.

Сервис может сообщить о действии пользователя — например, что отчёт готов — и запустить связанную автоматизацию. Сначала администратор создаёт определение события в интерфейсе, а код сервиса затем вызывает его через 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».