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-пакет. Формат, пример и ограничения.

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

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

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

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