Synchra.24
menu_bookДокументация
Практические материалы по запуску и развитию

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

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

Введение и быстрый старт

Что такое автоматизации Synchra24, как создать первый сценарий и безопасно выполнить проверочный запуск.

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

Например, автоматизация может раз в сутки:

  • получить из 1С список сотрудников в XML;
  • привести поля к структуре, которую принимает другая система;
  • отправить результат в JSON;
  • сохранить статус и диагностические данные запуска.

Что потребуется

Для работы нужны:

  • лицензия API-интеграция;
  • право роли на редактирование интеграций компании;
  • доступные по HTTPS или HTTP адреса источников и назначений;
  • токены внешних систем, если их API требует авторизацию.

AI-помощник в редакторе обработчика дополнительно требует лицензию AI-агент.

Где находятся автоматизации

Откройте компанию и перейдите:

  1. Администратор;
  2. Автоматизации;
  3. Создать.

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

Раздел админки, открытая автоматизация и вкладка её редактора сохраняются в адресе страницы. После перезагрузки восстанавливается сохранённая автоматизация на той же вкладке; работают кнопки браузера «Назад» и «Вперёд». Ссылка не передаёт права доступа и не содержит код обработчика, секреты или несохранённые изменения. Чтобы сохранить изменения перед перезагрузкой, используйте Проверить и сохранить.

Из чего состоит автоматизация

В редакторе есть две основные вкладки.

Конфигурация

Описывает порядок выполнения:

  • когда запускать автоматизацию;
  • откуда получить данные;
  • в каком формате прочитать ответ;
  • куда отправить результат;
  • сколько раз повторить отправку при ошибке.

Конфигурацию можно написать в YAML или JSON. В примерах документации используется YAML, потому что он обычно короче и удобнее для чтения.

Обработчик

Содержит JavaScript-функцию transform(input, context). Она получает данные источника и возвращает результат для назначения.

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

Первая автоматизация

Ниже приведён минимальный пример: получить JSON, оставить нужные поля и передать результат в другой сервис.

1. Заполните основные данные

Укажите понятное название, например Ежедневная выгрузка заказов, и кратко опишите назначение автоматизации.

2. Добавьте конфигурацию

version: 1

trigger:
  type: manual

source:
  type: http
  method: GET
  url: https://api.example.com/orders
  headers:
    Authorization: "Bearer ${secrets.SOURCE_TOKEN}"
  response:
    format: json
    encoding: utf-8

transform:
  type: javascript
  timeout_seconds: 2

destination:
  type: http
  method: POST
  url: https://receiver.example.com/import/orders
  headers:
    Authorization: "Bearer ${secrets.DESTINATION_TOKEN}"
  request:
    format: json
    encoding: utf-8

retry:
  attempts: 3
  delay_seconds: 5

trigger.type: manual означает, что автоматизация запускается только вручную. Это удобный режим для первого знакомства и отладки.

3. Добавьте обработчик

function transform(input, context) {
  const orders = Array.isArray(input.orders) ? input.orders : [];

  return orders.map((order) => ({
    number: String(order.id),
    amount: Number(order.total || 0),
    createdAt: order.created_at || null,
  }));
}

Функция обязательно должна называться transform и вернуть JSON-совместимое значение: объект, массив, строку, число, логическое значение или null.

4. Создайте секреты

Откройте Переменные в списке автоматизаций и добавьте:

  • SOURCE_TOKEN;
  • DESTINATION_TOKEN.

Значения секретов хранятся отдельно от конфигурации и после сохранения не показываются.

5. Проверьте конфигурацию

Нажмите Проверить конфигурацию. Система проверит:

  • структуру YAML или JSON;
  • обязательные поля;
  • формат cron, если задано расписание;
  • адреса источника и назначения;
  • синтаксис JavaScript.

При этой проверке внешние запросы не выполняются.

6. Выполните проверочный запуск

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

В модалке результата отображаются:

  • данные, полученные из источника;
  • данные после обработчика;
  • сообщения console.log, console.info, console.warn и console.error;
  • ошибка JavaScript, если она возникла.

7. Сохраните и включите

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

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

trigger:
  type: schedule
  cron: "0 0 * * *"
  timezone: Europe/Moscow

Этот пример запускается каждый день в 00:00 по московскому времени.

Запуск из собственного сервиса

Например, сотрудник готовит отчёт в вашем сервисе, нажимает «Отправить», а автоматизация сохраняет результат в артефакт или передаёт его во внешнюю систему.

  1. В администраторе сохраните сервис и создайте во вкладке События включённое событие с локальным именем report_ready.
  2. В автоматизации выберите это событие сервиса. Используйте version: 2, trigger.type: event и полный код, например custom.service_42.report_ready.
  3. Настройте обработчик и назначение. Поле source не нужно: входом служит конверт события, данные сервиса находятся в input.payload.
  4. Сохраните и включите автоматизацию.
  5. Добавьте в сервис вызов synchra.emitEvent с устойчивым ключом операции, опубликуйте сервис и проверьте рабочую отправку и историю автоматизации.

Для этого сценария дополнительно нужна лицензия Приложения и право редактирования сервисов. AI-помощник редактора может добавить вызов уже зарегистрированного события; он не регистрирует события из кода. Предпросмотр сервиса имитирует отправку и не запускает рабочие автоматизации. Вызов пока поддерживается только веб-движком.

Примеры кода и лимиты: Сервисы и Событийные автоматизации.

Порядок выполнения

При рабочем запуске Synchra24 выполняет этапы последовательно:

  1. загружает и расшифровывает секретные переменные компании;
  2. получает данные из источника или источников;
  3. декодирует ответ в соответствии с форматом;
  4. вызывает transform(input, context), если обработчик включён;
  5. кодирует результат в формат назначения;
  6. отправляет данные;
  7. записывает статус, время и безопасное превью результата в историю.

Если любой обязательный этап завершился ошибкой, запуск получает статус Ошибка.

Какой режим выбрать

Используйте обычные source и destination, когда данные идут из одной системы в одну другую.

Используйте steps, когда нужно:

  • собрать данные из нескольких источников;
  • отправить результат в несколько назначений;
  • передать каждому назначению свою часть результата.

Подробности: Конфигурация автоматизации и Несколько источников и назначений.

Следующий шаг

Перед рабочим запуском рекомендуется ознакомиться с документами:

Данные, изменяемые из сервиса

Создайте JSON-артефакт в управлении автоматизациями. В сервисе заменяйте значение через await synchra.setArtifact(name, value). В YAML подключите его как artifacts: {settings: service.settings}: дальше он доступен источникам, условиям, обработчику (context.artifacts.settings) и назначениям. Создание имени остаётся отдельным административным действием. Полный сценарий.

Создание из ZIP-шаблона

В разделе Автоматизации нажмите Из ZIP-шаблона, выберите архив с automation.json, конфигурацией и обработчиком, проверьте зависимости и создайте запись. Она будет выключена и не выполнит запросы при загрузке. Настройте секретные переменные и ресурсы этой компании, проверьте код, затем отдельно включите. Кнопка скачивания в шапке редактора создаёт обратный ZIP-пакет. Формат, пример и ограничения.

Магазин и публикация автоматизации

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

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

Как установить продукт, заполнить карточку продавца, отправить публикацию на проверку и выдать ключ покупателю, описано в статье «Магазин расширений».