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

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

folderАўтаматызацыя

Канфігурацыя аўтаматызацыі

Даведнік YAML і JSON: расклад, Сістэмныя падзеі і падзеі сэрвісаў, крыніцы, прызначэння і паўторы.

Пераклад пакуль недаступны. Паказаны арыгінал.

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

Размер конфигурации не должен превышать 256 КБ. Поддерживаются версии схемы 1 и 2. Версия 2 нужна для запуска по событиям Synchra24.

Верхний уровень

Поле Обязательно Назначение
version да Версия схемы: 1 или 2. Для событий нужен 2.
trigger да Ручной запуск, запуск по расписанию или по событию.
source для простого режима без события Один HTTP-источник или артефакт. Для event не используется.
destination для простого режима Одно HTTP-назначение, артефакт или подтверждённый чат MAX.
steps для расширенного режима Несколько источников и назначений.
transform нет Настройки JavaScript-обработчика.
retry нет Повтор отправки данных в назначение.
conditions нет Условия для входных данных, события и подключённых артефактов.
artifacts нет Алиасы имён артефактов компании, доступных на всех этапах запуска.

Для ручного запуска и расписания используйте либо пару source + destination, либо массив steps. Для события входом служит его payload, поэтому укажите только destination или шаги назначений. Смешивать обычные поля и steps в одной автоматизации нельзя.

version

version: 1

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

trigger

Ручной запуск

trigger:
  type: manual

Автоматизация выполняется по кнопке Запустить. Поля cron и timezone в этом режиме не используются.

Запуск по расписанию

trigger:
  type: schedule
  cron: "30 8 * * 1-5"
  timezone: Europe/Moscow
Поле Обязательно Значение
type да manual, schedule или event.
cron для schedule Пять полей cron: минута, час, день месяца, месяц, день недели.
timezone нет Название часового пояса IANA. По умолчанию Europe/Moscow.
event для event Точное имя системного события (employee.late) или полный код события сервиса (custom.service_42.report_ready).

Примеры расписаний:

Задача Cron
Каждый день в 00:00 0 0 * * *
Каждый день в 08:30 30 8 * * *
По будням в 21:00 0 21 * * 1-5
Каждый час 0 * * * *
В первый день месяца в 03:15 15 3 1 * *

Расписание рассчитывается в указанном часовом поясе, а время запусков внутри системы хранится в UTC.

Плановый запуск можно настроить не чаще одного раза в 30 минут. Например, */30 * * * * допустим, а */15 * * * * будет отклонён при проверке конфигурации.

Один запуск по расписанию или событию может выполняться не более 60 секунд. В этот срок входят получение данных из всех источников, JavaScript-обработка, отправка во все назначения, задержки и повторные попытки. По истечении лимита выполнение останавливается и в истории появляется ошибка. Интервал 30 минут применяется только к триггеру schedule; ручные и проверочные запуски им не ограничиваются.

Запуск по событию

version: 2
trigger:
  type: event
  event: employee.late

В этом режиме входные данные уже содержатся в событии, поэтому source и шаги с kind: source указывать нельзя. Нужны только обработчик и одно или несколько назначений. Полный список событий и пример условий приведены в разделе Запуск по событиям Synchra24.

Для события собственного сервиса укажите полный код из вкладки События, например custom.service_42.report_ready. В редакторе доступен выбор события из каталога сервисов компании. Сам сервис вызывает локальное имя report_ready через synchra.emitEvent; этот вызов не создаёт определение события. Регистрация, ограничения и полный пример конфигурации: Пользовательские события сервисов.

source

Источник — HTTP-адрес, из которого автоматизация получает данные.

source:
  type: http
  method: GET
  url: https://api.example.com/v1/orders
  headers:
    Authorization: "Bearer ${secrets.SOURCE_TOKEN}"
    Accept: application/json
  response:
    format: json
    encoding: utf-8
Поле Обязательно Значение
type да Для источника и назначения — http или artifact.
method нет HTTP-метод. Для источника по умолчанию используется GET.
url для HTTP Абсолютный адрес с http:// или https://.
headers нет До 50 HTTP-заголовков. В значениях можно использовать секреты.
body нет Тело запроса источника. Используется, если API получает фильтр через POST.
response для HTTP Правила чтения ответа.

Если задан body, он отправляется как JSON. Если принимающий API требует заголовок Content-Type: application/json, добавьте его в headers явно. Для обычного GET поле лучше не добавлять.

Источник считается успешным только при HTTP-статусе от 200 до 299.

response

response:
  format: xml
  encoding: windows-1251
  options:
    delimiter: ";"
    header: true
Поле Обязательно Значение
format нет json, xml, csv, tsv или text. Если поле пустое, формат определяется по Content-Type.
encoding нет utf-8 или windows-1251. По умолчанию UTF-8.
options.delimiter нет Один символ-разделитель для CSV. По умолчанию ;.
options.header нет Считать ли первую строку CSV заголовком. По умолчанию true.
options.root нет Для чтения не используется; применяется при создании XML.

Подробнее: Форматы данных.

transform

transform:
  type: javascript
  timeout_seconds: 2
Поле Обязательно Значение
type нет Пустое значение или javascript.
timeout_seconds нет Лимит выполнения функции от 1 до 5 секунд. По умолчанию 2 секунды.

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

destination

Назначение определяет, куда автоматизация передаёт итоговые данные: во внешний HTTP-сервис, артефакт или подтверждённый чат MAX.

destination:
  type: http
  method: POST
  url: https://receiver.example.com/v1/orders/import
  headers:
    Authorization: "Bearer ${secrets.DESTINATION_TOKEN}"
  request:
    format: json
    encoding: utf-8
Поле Обязательно Значение
type да Для источника и назначения — http или artifact.
method нет HTTP-метод. Для назначения по умолчанию используется POST.
url для HTTP Абсолютный HTTP- или HTTPS-адрес.
headers нет До 50 заголовков. Пользовательский Content-Type будет заменён типом выбранного формата.
request для HTTP Правила кодирования результата.
body нет Явное тело HTTP-назначения; без него отправляется результат transform.

Назначение считается успешным при HTTP-статусе от 200 до 299. Тело ответа назначения не используется.

Назначение artifact

Вместо HTTP-запроса результат можно сохранить в Synchra24:

destination:
  type: artifact
  name: warehouse.stock

Для этого назначения допускаются только type и name. HTTP-поля не указываются. Подробнее: Артефакты автоматизаций.

Отправка в MAX через общего бота

В облачной Synchra24 можно отправлять уведомления через общего бота платформы. Для этого откройте Администратор → Автоматизации → Чаты MAX. Нужны лицензия API-интеграция и право управления интеграциями. Если окно сообщает, что бот ещё не подключён, сохраните автоматизацию выключенной и вернитесь к настройке после подключения бота оператором.

Добавьте указанного в окне бота в групповой чат или канал MAX с правом отправки сообщений. Отправьте в этом чате команду /chatid и скопируйте полученный ID. В Synchra24 укажите имя подключения и ID, нажмите Отправить код в MAX, затем введите шесть цифр из сообщения бота. Код действует 10 минут; после пяти неверных попыток потребуется новый. Доступно до пяти запросов кода за час на компанию и на чат, включая неудачные отправки. В компании может быть до 20 подключений.

Если готовое расширение отправляет уведомления в MAX, перед его включением проверьте подключение в Чаты MAX. Установка расширения сама по себе не подключает чат. Если список подключений не загрузился, повторите открытие раздела; не создавайте дубликаты автоматизации.

Для готовых расширений оставьте имя default. Если уведомления должны идти в разные чаты, создайте подключения с разными именами и выберите нужное имя в конфигурации. Токен общего бота вводить и передавать продавцу не нужно. Сведения о подключениях доступны только внутри своей компании.

Для разработчика автоматизации назначение выглядит так:

destination:
  type: max
  name: default

В этом назначении допустимы только type и name. ID чата и токен в коде не задаются. Обработчик возвращает простой текст до 4000 символов. Допускается одна строка из одной или двух кнопок-ссылок на разделы текущей компании в облачной веб-версии:

function transform(input, context) {
  return {
    text: 'В Synchra24 появился новый инцидент.',
    attachments: [{
      type: 'inline_keyboard',
      payload: {buttons: [[{
        type: 'link', text: 'Открыть инциденты',
        url: 'https://app.synchra24.com/activity/' + context.provider_id + '/incidents'
      }]]}
    }]
  };
}

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

Чтобы остановить уведомления, выключите автоматизацию или удалите её подключение в Чаты MAX. Если это имя используют несколько автоматизаций, отправка остановится у каждой из них. Уже отправленные сообщения не удаляются. После удаления бота из чата подключение отзывается; для повторной работы подтвердите чат заново. Замена общего бота также требует нового подтверждения. Ссылки на отдельные коробочные серверы этим назначением не поддерживаются.

request

Структура совпадает с response:

request:
  format: csv
  encoding: windows-1251
  options:
    delimiter: ";"

Если формат не указан, результат отправляется как JSON.

retry

retry:
  attempts: 3
  delay_seconds: 10
Поле Диапазон Значение
attempts от 0 до 5 Общее количество попыток отправки. Значения 0 и 1 означают одну попытку.
delay_seconds от 0 до 3600 Пауза между попытками в секундах.

Повторы относятся к отправке в HTTP-назначения. Для общего бота MAX автоматических повторов нет. Ошибочный запрос к источнику не повторяется в рамках текущего запуска.

Полный пример YAML

version: 1

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

source:
  type: http
  method: GET
  url: https://accounting.example.com/export/employees
  headers:
    X-API-Key: "${secrets.ACCOUNTING_API_KEY}"
  response:
    format: xml
    encoding: windows-1251

transform:
  type: javascript
  timeout_seconds: 3

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

retry:
  attempts: 3
  delay_seconds: 15

Тот же пример в JSON

{
  "version": 1,
  "trigger": {
    "type": "schedule",
    "cron": "0 2 * * *",
    "timezone": "Europe/Moscow"
  },
  "source": {
    "type": "http",
    "method": "GET",
    "url": "https://accounting.example.com/export/employees",
    "headers": {
      "X-API-Key": "${secrets.ACCOUNTING_API_KEY}"
    },
    "response": {
      "format": "xml",
      "encoding": "windows-1251"
    }
  },
  "transform": {
    "type": "javascript",
    "timeout_seconds": 3
  },
  "destination": {
    "type": "http",
    "method": "POST",
    "url": "https://hr.example.com/api/employees/import",
    "headers": {
      "Authorization": "Bearer ${secrets.HR_TOKEN}"
    },
    "request": {
      "format": "json",
      "encoding": "utf-8"
    }
  },
  "retry": {
    "attempts": 3,
    "delay_seconds": 15
  }
}

Кнопка форматирования в редакторе приводит YAML или JSON к читаемому виду. Кнопка загрузки позволяет выбрать готовый файл .yaml, .yml или .json размером до 256 КБ.

Входные артефакты на всех этапах

Подключите artifacts: {settings: service.settings} в корне конфигурации. Значения доступны в source, conditions, transform и destination. Источник type: artifact с name возвращает сохранённое значение; HTTP поддерживает ${artifacts.settings.field} в URL, заголовках и JSON-теле. В steps назначение может выбрать input: ${artifacts.settings}. Условия используют path: artifacts.settings.field или input.field; value может ссылаться на подключённый артефакт. В обработчике читайте context.artifacts.settings.

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

Импорт и экспорт ZIP-шаблона автоматизации

В веб-администраторе откройте Автоматизации → Из ZIP-шаблона. Загрузите пакет и проверьте показанные параметры: идентификатор и версию шаблона, тип запуска, ссылки на секретные переменные, артефакты и событие. Перед созданием можно изменить название. Для импорта нужны доступ к администратору, лицензия API и admin_edit_provider_integrations; лицензия AI не нужна.

Кнопка Создать автоматизацию добавляет новую выключенную запись. Существующие автоматизации не заменяются, даже если имя или идентификатор шаблона совпадают. Код, HTTP-запросы и назначения при импорте не выполняются; расписание и события не начинают запускать pipeline. В редакторе проверьте адреса, часовой пояс, секретные переменные, артефакты и код события текущей компании. Затем выполните нужные проверки и отдельно включите автоматизацию.

Стандартная кнопка скачивания в шапке редактора — Экспортировать ZIP-шаблон автоматизации — упаковывает текущие конфигурацию, обработчик, название и описание, включая несохранённые правки. Экспорт не сохраняет изменения в автоматизации и не запускает её.

Формат пакета

automation.json
pipeline.yaml
transform.js
{
  "format": "synchra.automation-template",
  "schema_version": 1,
  "template": {
    "id": "com.example.exchange",
    "version": "1.0.0",
    "description": "Обмен данными с учётной системой"
  },
  "automation": {
    "name": "Обмен данными",
    "description": "Получить данные, преобразовать и сохранить результат"
  },
  "files": {
    "pipeline": "pipeline.yaml",
    "transform": "transform.js"
  }
}

schema_version — версия формата ZIP; template.version — версия конкретного шаблона; version внутри YAML — версия схемы pipeline. Эти три значения имеют разное назначение. Экспорт редактора использует локальный идентификатор local.automation и версию 1.0.0; для распространения задайте собственные значения. Идентификатор — 3–128 строчных латинских букв, цифр, точек, _ или -, начинается с буквы; версия имеет вид 1.0.0, допускается суффикс -beta.1.

automation.name обязателен: от 2 символов до 100 байт UTF-8. automation.description необязателен, до 4000 символов. Описание шаблона — до 2000 символов. Файлы в files обязательны: конфигурация .yaml, .yml или .json и отдельный обработчик .js. Для pipeline без JavaScript-преобразования оставьте файл обработчика пустым. Поле transform.script не нужно: код хранится в отдельном файле, как в редакторе.

Допускаются вложенные каталоги и одна общая папка с automation.json. Пути считаются относительно конфигурации пакета. Можно добавить README.md, LICENSE и LICENSE.txt; служебные файлы macOS игнорируются. Другие файлы не импортируются.

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

ZIP — до 1 МиБ, automation.json — до 64 КиБ, конфигурация и обработчик — до 256 КиБ каждый. Всего до 32 записей вместе с каталогами и до 640 КиБ суммарного заявленного распакованного размера. Требуется UTF-8. Поддерживается обычный ZIP с STORE/DEFLATE без пароля, ZIP64, нескольких томов и символических ссылок. Нельзя использовать абсолютные пути, .., обратные слеши и дублирующиеся имена. Проверяются фактические размеры и CRC, распаковка ограничена даже при неверном размере в ZIP-каталоге.

Перед созданием система проверяет архив и настройки автоматизации. Если найдена ошибка, запись не создаётся: можно исправить пакет и выбрать его повторно, не закрывая окно. Отдельный файл YAML или JSON загружается кнопкой загрузки конфигурации в редакторе.

Значения секретных переменных из хранилища, содержимое артефактов, история запусков, идентификаторы записей и авторов не экспортируются. В конфигурации остаются ссылки ${secrets.NAME}, имена артефактов и код события. Показанный список артефактов включает чтение и назначения: входной артефакт должен существовать, а артефакт-назначение будет создан обычным успешным запуском. Такие зависимости не создаются автоматически. Для события сервиса проверьте и при необходимости выберите код сервиса именно этой компании.

Исходники экспортируются без редактирования. Если адрес, идентификатор компании или секретное значение прописаны прямо в YAML или JavaScript, они останутся в файлах. До передачи архива замените секретные значения ссылками на переменные. Флаг enabled, provider_id, секретные значения и другие поля установленной записи в automation.json не допускаются.

ZIP-шаблон или магазин

ZIP-шаблон создаёт отдельную копию автоматизации. После импорта её нужно настроить для своей компании; обновления продавца к такой копии не привязываются.

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