menu_bookДокументация

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

Здесь собраны инструкции по запуску, разработке внутренних сценариев и встраиванию собственных инструментов в рабочий контур компании.

folderАвтоматизации

Запуск по событиям Synchra24

Устройство событийной системы, полный каталог из 49 событий, поля payload, условия, гарантии доставки и примеры автоматизаций.

Событийная автоматизация запускается сразу после изменения в Synchra24. Она подходит для процессов вида «если произошло событие и выполнено условие — отправить данные или вызвать внешний сервис».

Например:

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

Как работает событийный запуск

После бизнес-действия сервис Synchra24 формирует событие с уникальным event_id, названием, компанией, автором действия и полезной нагрузкой payload. Событие асинхронно передаётся в сервис Automation. Для каждой включённой автоматизации с совпадающим trigger.event создаётся отдельный запуск.

Последовательность выглядит так:

пользователь или системный процесс выполняет действие в Synchra24;
исходный сервис формирует событие;
событие попадает в очередь доставки;
Automation находит включённые сценарии этой компании с таким типом события;
система проверяет conditions;
JavaScript-обработчик преобразует данные;
результат отправляется в одно или несколько назначений;
статус, входные данные, результат и логи сохраняются в истории запусков.

Событийная автоматизация не опрашивает сервисы по расписанию и не требует поля source: данные уже находятся в конверте события.

Что нужно для настройки

у компании должна быть активна возможность API-интеграция;
пользователю нужен доступ к разделу Автоматизации;
конфигурация должна использовать version: 2;
автоматизация должна быть включена;
для внешнего API заранее подготовьте URL, способ авторизации и секреты.

В редакторе выберите тип триггера event и укажите одно точное имя события. Регистр и символы имеют значение: task.completed и Task.Completed считаются разными строками.

Каталог событий

Ниже перечислены все события, которые можно указывать в trigger.event. Поле Payload показывает основные данные для условий и обработчика. Кроме них, в payload.title может передаваться название сущности.

Задачи, инциденты и чек-листы

Событие	Когда возникает	Основные поля payload
`task.created`	Создана задача.	`id`, `number`, `title`, `assigned_to`, `priority_id`, `deadline`
`task.status_changed`	Статус задачи действительно изменился.	`id`, `number`, `status`, `status_title`, `assigned_to`, `created_by`
`task.completed`	Новый статус задачи — `completed`. Событие приходит вместе с `task.status_changed`, но имеет другой `event_id`.	те же поля, что у `task.status_changed`
`task.canceled`	Новый статус задачи — `canceled`.	те же поля, что у `task.status_changed`
`incident.created`	Создан инцидент.	`id`, `number`, `title`, `assigned_to`, `priority_id`
`incident.status_changed`	Статус инцидента действительно изменился.	`id`, `number`, `status`, `status_title`, `assigned_to`, `created_by`
`incident.in_progress`	Инцидент переведён в статус `in_progress`.	те же поля, что у `incident.status_changed`
`incident.completed`	Инцидент завершён, закрыт или отмечен невыполненным.	те же поля, что у `incident.status_changed`
`checklist.submitted`	Результат чек-листа отправлен.	`id`, `status`, `session_id`, `violations_count`, `has_failures`
`checklist.failed`	Отправленный чек-лист содержит хотя бы одно нарушение.	те же поля, что у `checklist.submitted`

Учёт времени

Событие	Когда возникает	Основные поля payload
`shift.started`	Сотрудник начал смену.	`timer_id`, `user_id`, `started_at`, `launching_user_id`, `panel_id`, `manual`; при наличии графика — `planned_start`, `planned_end`, `late_minutes`
`shift.ended`	Активная смена сотрудника остановлена.	`timer_id`, `user_id`, `started_at`, `ended_at`, `duration_seconds`, `stopped_by_user_id`, `manual`
`employee.late`	Смена началась позже планового времени.	поля `shift.started`, включая `late_minutes`

Заявки, формы, документы и отчёты

Событие	Когда возникает	Основные поля payload
`request.created`	Сотрудник создал заявку.	`title`
`request.approved`	Заявка окончательно согласована. Промежуточное согласование одного участника событие не создаёт.	`title`
`request.rejected`	Заявка окончательно отклонена.	`title`
`assessment_360.submitted`	Участник отправил оценку 360°.	`title`
`form.blank_completed`	Сотрудник заполнил назначенный бланк.	`dispatch_id`, `form_type`, `title`
`form.poll_completed`	Сотрудник прошёл назначенный опрос.	`dispatch_id`, `form_type`, `title`
`document.signed`	Сотрудник подписал документ.	`title`
`report.created`	Создан отчёт.	`date`, `session_id`, `title`

Отпуска, идеи и касса

Событие	Когда возникает	Основные поля payload
`vacation.requested`	Сотрудник отправил план отпуска.	`subject_user_id`, `year`, `days`, `approver_ids`, `comment`, `title`
`vacation.approved`	План отпуска согласован.	`subject_user_id`, `year`, `comment`, `title`
`vacation.canceled`	Дни плана отпуска отменены или отклонены.	`subject_user_id`, `year`, `days`, `comment`, `title`
`client_hub.employee_idea_created`	Сотрудник отправил идею в клиентском хабе.	`status`, `title`
`cash.transaction_created`	Создана операция прихода, расхода, выдачи или возврата.	`cashbox_id`, `type`, `amount`, `description`, `user_id`, `category_id`, `title`
`cash.transaction_canceled`	Кассовая операция отменена.	`cashbox_id`, `type`, `amount`, `description`, `user_id`, `category_id`, `canceled_by`, `canceled_at`, `title`

Календарь и новости

Событие	Когда возникает	Основные поля payload
`calendar.event_created`	Создано мероприятие календаря.	`starts_at`, `ends_at`, `location`, `user_ids`, `title`
`calendar.event_updated`	Мероприятие календаря изменено.	те же поля, что у `calendar.event_created`
`calendar.event_deleted`	Мероприятие календаря удалено.	`title`
`news.created`	Создана новость.	`show_from`, `show_to`, `title`
`news.updated`	Новость изменена.	`show_from`, `show_to`, `title`
`news.deleted`	Новость удалена.	`title`

Выездные работы

Событие	Когда возникает	Основные поля payload
`field_visit.created`	Создан черновик выезда.	общие поля выезда
`field_visit.updated`	Изменены параметры выезда.	общие поля выезда
`field_visit.published`	Выезд опубликован и назначен сотрудникам.	общие поля выезда
`field_visit.departed`	Исполнитель начал движение на объект.	общие поля и поля операции
`field_visit.arrived`	Исполнитель отметил прибытие.	общие поля и поля операции
`field_visit.completed`	Выезд завершён.	общие поля и поля операции
`field_visit.canceled`	Выезд отменён.	общие поля и поля операции

Общие поля выезда: number, status, priority, date, window_start, window_end, timezone, responsible_id, member_ids, title. Для действий также передаются operation_id, offline, geo_state, reason и result. Повторная доставка одной офлайн-операции не создаёт новое событие.

Сотрудники, отделы и роли

Событие	Когда возникает	Основные поля payload
`employee.added`	Пользователь добавлен в компанию.	`user_id`, `position_id`, `title`
`employee.dismissed`	Сотрудник уволен.	`profile_id`, `employment_status`, `title`
`employee.restored`	Уволенный сотрудник восстановлен.	`profile_id`, `employment_status`, `title`
`employee.blocked`	Профиль сотрудника заблокирован.	`profile_id`, `blocked`, `title`
`employee.unblocked`	Блокировка профиля снята.	`profile_id`, `blocked`, `title`
`department.created`	Администратор создал отдел.	`department_id`, `name`, `description`, `title`
`role.created`	Администратор создал роль вручную или через AI-генератор структуры ролей. Для сгенерированной роли создаётся отдельное событие.	`role_id`, `name`, `description`, `parent_id`, `permissions`, `generated`, `title`

Журналы и база знаний

Событие	Когда возникает	Основные поля payload
`journal.completed`	Сотрудник выполнил мероприятие журнала.	`journal_id`, `journal_title`, `event_title`, `completed_by`, `assignment_at`, `completion_source`, `reason`, `title`
`journal.force_completed`	Руководитель принудительно завершил мероприятие.	те же поля; `completion_source` равно `manager_override`
`wiki.article_created`	Создана статья базы знаний.	`section_id`, `title`
`wiki.article_updated`	Статья базы знаний изменена.	`title`

Базовый пример: опоздание более чем на 15 минут

version: 2

trigger:
  type: event
  event: employee.late

conditions:
  all:
    - path: payload.late_minutes
      operator: gte
      value: 15

transform:
  type: javascript
  timeout_seconds: 2

destination:
  type: http
  method: POST
  url: https://example.com/api/lateness
  headers:
    Authorization: "Bearer ${secrets.DESTINATION_TOKEN}"
  request:
    format: json

retry:
  attempts: 3
  delay_seconds: 5

У событийной автоматизации нет source: источником служит само событие. В режиме steps также нельзя добавлять шаги kind: source, но можно добавить несколько назначений.

Другие примеры условий

Завершён срочный выезд

trigger:
  type: event
  event: field_visit.completed

conditions:
  all:
    - path: payload.priority
      operator: eq
      value: urgent

Кассовая операция больше 100 000

trigger:
  type: event
  event: cash.transaction_created

conditions:
  all:
    - path: payload.amount
      operator: gte
      value: 100000

Любое кадровое выбытие

Одна автоматизация слушает только одно имя события. Для увольнения используйте employee.dismissed. Если нужно одинаково обрабатывать увольнение и блокировку, создайте две автоматизации или направьте оба сценария в один внешний endpoint.

Условия

В conditions.all перечисляются условия, которые должны выполниться одновременно. В conditions.any достаточно выполнения одного условия. Обе группы можно использовать вместе.

Оператор	Назначение
`eq`, `ne`	Равно или не равно.
`gt`, `gte`, `lt`, `lte`	Сравнение чисел.
`in`	Значение входит в указанный массив.
`contains`	Строка содержит фрагмент или массив содержит значение.
`exists`	Поле существует; для проверки отсутствия укажите `value: false`.

Путь может обращаться к event_type, actor_user_id, entity_type, entity_id, source_service или полям payload, например payload.priority_id.

Данные обработчика

Функция transform(input, context) получает конверт события целиком:

Поле	Тип	Описание
`event_id`	UUID	Уникальный идентификатор события и ключ защиты от дублей.
`schema_version`	число	Версия конверта. Сейчас используется `1`.
`event_type`	строка	Имя события из каталога выше.
`provider_id`	строка	Идентификатор компании.
`actor_user_id`	строка	Пользователь, выполнивший действие. Для системного процесса может быть пустым.
`source_service`	строка	Сервис Synchra24, создавший событие.
`entity_type`	строка	Тип сущности: например `task`, `timer` или `field_visit`.
`entity_id`	строка	Идентификатор сущности.
`occurred_at`	дата и время	Момент события в UTC в формате ISO 8601.
`correlation_id`	строка	Идентификатор связанной цепочки операций.
`causation_id`	строка	Идентификатор события-причины, если оно есть.
`depth`	число	Глубина цепочки автоматизаций, от `0` до `4`.
`payload`	объект	Данные конкретного события.

{
  "event_id": "2dc81c0d-7bf5-4cd6-8837-57ce93730c50",
  "schema_version": 1,
  "event_type": "employee.late",
  "provider_id": "company-id",
  "actor_user_id": "42",
  "source_service": "time_manager",
  "entity_type": "timer",
  "entity_id": "123",
  "occurred_at": "2026-10-04T08:15:00Z",
  "correlation_id": "2dc81c0d-7bf5-4cd6-8837-57ce93730c50",
  "depth": 0,
  "payload": {
    "user_id": "42",
    "late_minutes": 15
  }
}

event_id уникален и используется для защиты от повторной обработки. correlation_id связывает действия одной цепочки. Глубина цепочки ограничена пятью уровнями, чтобы автоматизации не могли создать бесконечный цикл.

В JavaScript поля читаются напрямую:

function transform(input, context) {
  return {
    eventId: input.event_id,
    companyId: input.provider_id,
    employeeId: input.actor_user_id,
    minutesLate: input.payload.late_minutes,
    receivedAt: context.started_at
  };
}

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

Доставка и защита от дублей

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

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

После принятия события очередью транспорт использует модель как минимум один раз: при сбое одно событие может быть доставлено повторно. Automation сохраняет event_id и не создаёт второй запуск той же автоматизации. Внешняя система также может хранить полученный event_id как ключ идемпотентности.

События разных действий могут прийти почти одновременно. Если порядок критичен, сравнивайте occurred_at и состояние сущности во внешней системе.

Совместимость

имя существующего события и смысл текущих полей не меняются без необходимости;
новые необязательные поля могут появляться в payload;
обработчик не должен завершаться ошибкой из-за неизвестного поля;
при создании новой несовместимой структуры будет увеличена schema_version;
даты передаются в UTC, если в описании поля не указано иное;
денежные значения передаются числом в валюте, используемой кассой компании.

Проверка и запуск

Проверочный запрос API может передать тестовые данные в поле event_payload; система покажет результат обработчика и логи, но не вызовет назначения. Если поле не передано, используется пустой объект. Для отладки используйте проверочный запуск с event_payload.

Один событийный запуск ограничен 60 секундами. Рабочая событийная автоматизация не имеет обычного ручного запуска: её запускает выбранное событие.

После реального события откройте историю автоматизации и проверьте:

появился ли запуск с триггером event;
совпал ли event_type;
прошли ли условия;
что записано во входных и выходных данных;
какие сообщения вывел обработчик;
какой ответ вернул внешний endpoint.

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

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

rocket_launch30 дней бесплатно

Попробуйте Synchra24 на своей команде
без риска

Запустим Synchra24 на реальной команде и настроим ключевые сценарии под ваши процессы. За 30 дней вы сможете оценить результат и понять, подходит ли система вашему бизнесу.