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

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

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

Артэфакты аўтаматызацый

Захаванне JSON-дадзеных ўнутры кампаніі, версіі і API.

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

Артефакт — именованное JSON-значение, которое автоматизация или сервис сохраняет в Synchra24 для своей компании. Это позволяет получать данные из внешней системы, преобразовывать их и хранить последний результат для чтения и обновления через API и мост сервисов. Данные сохраняются после перезапуска сервиса.

Например, автоматизация раз в час получает остатки из учётной системы и сохраняет их под именем warehouse.stock. Другая интеграция читает этот артефакт, не обращаясь повторно к источнику.

Настройка назначения

В конфигурации с одним источником замените HTTP-назначение:

version: 1
trigger:
  type: schedule
  cron: "0 * * * *"
  timezone: Europe/Moscow
source:
  type: http
  method: GET
  url: https://accounting.example.com/api/stock
  headers:
    Authorization: "Bearer ${secrets.ACCOUNTING_TOKEN}"
  response:
    format: json
transform:
  type: javascript
  timeout_seconds: 2
destination:
  type: artifact
  name: warehouse.stock

Обработчик возвращает данные для сохранения:

function transform(input, context) {
  if (!Array.isArray(input.items)) {
    throw new Error('Источник не вернул список остатков');
  }
  return { items: input.items, received_at: context.started_at };
}

Кнопка с иконкой архива в редакторе конфигурации помогает добавить такое назначение. В режиме source/destination она заменяет прежнее назначение; в режиме steps добавляет ещё один шаг.

Одновременно сохранить и отправить

В steps можно сочетать HTTP-назначения и артефакты. Источники могут читать HTTP или сохранённый артефакт (type: artifact, name). Пример шага:

- id: stock_snapshot
  kind: destination
  type: artifact
  name: warehouse.stock
  input: ${transform.output.stock}

Без input сохраняется весь результат обработчика. Селектор поддерживает поля объектов, как у HTTP-назначений. Для артефакта не нужны url, method, headers, request, response и body; эти поля запрещены. В одном pipeline нельзя дважды записать одно имя артефакта.

Артефакты поддерживают ручные запуски, расписание и события. Для событий используются version: 2 и trigger.type: event, источник не указывается. В steps данные HTTP-источников доступны обработчику по их id: например, input.stock_source.

Обновление и ошибки

  • Первая запись создаёт версию 1. Каждая следующая запись полностью заменяет значение и увеличивает версию. История содержимого предыдущих версий не хранится.
  • Ошибка источника, обработчика или сохранения оставляет предыдущий артефакт доступным. Если данные имеют неверную структуру, обработчик должен явно выбросить ошибку.
  • Проверочный запуск ничего не записывает. Чтобы создать артефакт, сохраните pipeline и выполните обычный запуск.
  • Назначения исполняются параллельно. Если HTTP-назначение завершилось ошибкой, успешно записанный артефакт остаётся сохранённым; общей транзакции с внешними сервисами нет.
  • При одновременной записи одного имени из разных pipeline побеждает последняя завершённая запись. Повторный запуск также увеличивает версию, даже если значение совпадает.
  • Автоматического срока удаления нет. При удалении pipeline его артефакты остаются до явного удаления. pipeline_id и run_id показывают происхождение последней записи и могут ссылаться на уже удалённую историю. Ручная запись очищает эти поля.

Просмотр и ручное управление

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

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

API

Все методы ограничены текущей компанией. Нужна активная лицензия API и право admin_edit_provider_integrations. Артефакт другой компании нельзя прочитать или изменить, даже зная его имя.

Метод Путь Назначение
GET /api/v1/automations/artifacts Список метаданных без содержимого.
GET /api/v1/automations/artifacts/item?name=warehouse.stock Метаданные и значение одного артефакта.
POST /api/v1/automations/artifacts/upsert Создать или полностью заменить значение.
DELETE /api/v1/automations/artifacts/delete?name=warehouse.stock Удалить артефакт.

Для внешней интеграции передавайте X-OpenAPI-Token и X-Provider-Token той же компании. Получение токенов описано в руководстве по интеграциям. Перечисленные методы предназначены для Open API; сервисы внутри Synchra24 работают с артефактами через SDK.

Тело POST:

{ "name": "warehouse.stock", "value": { "items": [{ "sku": "A01", "quantity": 12 }] } }

value — JSON-значение, а не строка с сериализованным JSON. Допускаются объект, массив, строка, число, boolean и явный null; отсутствие value недопустимо.

Все ответы возвращаются в общей оболочке code, status, message, result. Чтение одного артефакта:

{
  "code": 200,
  "result": {
    "name": "warehouse.stock",
    "value": { "items": [{ "sku": "A01", "quantity": 12 }] },
    "size_bytes": 39,
    "version": 1,
    "created_at": "2026-10-13T09:00:00Z",
    "updated_at": "2026-10-13T09:00:00Z"
  }
}

POST возвращает сохранённый артефакт; DELETE — result: { "deleted": true }; список — result: { "items": [...] } без value. Некорректное имя/JSON — 400, отсутствие доступа — 403, отсутствующий артефакт — 404, превышение квоты — 409.

Ограничения и безопасность

Имя начинается с латинской буквы, содержит латинские буквы, цифры, ., _, - и имеет длину до 128 символов. Регистр учитывается. Максимум 100 артефактов на компанию, до 1 МиБ сериализованного JSON на значение и до 64 МиБ суммарно. Обновление существующего имени разрешено при достижении лимита количества, если хватает места.

Артефакты предназначены для прикладных данных. Пароли, API-ключи и токены храните в секретных переменных: содержимое артефакта доступно пользователям с правом управления интеграциями.

Чтение из гибридных микроприложений

Для чтения из сервиса используйте метод SDK getArtifact(name). Перед чтением проверьте подключение к Synchra24 и обработайте возможную ошибку доступа или отсутствия данных.

const synchra = new SynchraApp("SERVICE_TOKEN");
const snapshot = await synchra.getArtifact<{
  items: { sku: string; quantity: number }[];
}>("warehouse.stock");

console.log(snapshot.value.items);
console.log(snapshot.version, snapshot.updated_at);

Мост проверяет токен открытого внутреннего сервиса, а мобильное приложение выполняет запрос от текущего пользователя и компании. Микроприложению не передаются Bearer-токен и токен компании. Указывать компанию, URL API или заголовки не нужно.

Результат содержит name, value, size_bytes, version, created_at, updated_at и необязательные идентификаторы источника pipeline_id, run_id. Сохранённый null возвращается как value: null. Тип в TypeScript описывает ожидаемые данные, но не заменяет проверку структуры при чтении.

Действуют те же права API: лицензия API и admin_edit_provider_integrations. Мост не предоставляет дополнительных прав пользователю. Если артефакт не найден, доступ запрещён или сеть недоступна, Promise отклоняется. В старой версии мобильного приложения, не поддерживающей событие моста, сработает responseTimeout SDK. Предусмотрите состояние недоступных данных в интерфейсе микроприложения.

Запись из сервиса

Во встроенном SDK доступен setArtifact(name, value). Метод полностью заменяет существующее значение, увеличивает версию и возвращает сохранённый артефакт. Создайте имя заранее через управление артефактами или обычный запуск автоматизации. Если имя удалено или не существует, запись вернёт 404 и не создаст его заново.

if (await synchra.isSynchraIntegrated()) {
  const saved = await synchra.setArtifact('warehouse.stock', {
    items: [{sku: 'A01', quantity: 12}]
  });
  console.log(saved.version);
}

Вызовите запись после подтверждённого действия пользователя, показывайте ожидание и ошибку. Запись не запускает автоматизацию автоматически: при необходимости отдельно отправьте зарегистрированное событие сервиса. При параллельной записи побеждает последняя успешная запись; частичного слияния и истории версий нет. Запись из сервиса очищает pipeline_id и run_id последнего запуска.

Действуют прежние ограничения: лицензия API, право admin_edit_provider_integrations, текущая компания, токен открытого сервиса, JSON до 1 МиБ и общая квота 64 МиБ. Мост не выдаёт дополнительных прав. Внешний SDK, в котором ещё нет удобного метода, может вызвать synchra.requestPayload('app.automation.artifact.set', {name: 'warehouse.stock', value: {...}}). На мобильном устройстве нужна обновлённая сборка с поддержкой этого события. Во встроенном редакторе метод уже включён в SDK.

В предпросмотре можно изменять только существующие тестовые артефакты вкладки «Тестовые артефакты». Повторное чтение увидит изменённое значение и версию. Перезапуск предпросмотра сбрасывает эти изменения; реальные данные компании не меняются.

Чтение на любом этапе автоматизации

Подключите нужные имена в верхнем блоке artifacts. Ключ — короткий алиас, значение — реальное имя артефакта текущей компании:

version: 2
trigger:
  type: manual
artifacts:
  settings: service.settings
source:
  type: artifact
  name: warehouse.stock
conditions:
  all:
    - path: artifacts.settings.enabled
      operator: eq
      value: true
transform:
  type: javascript
  timeout_seconds: 2
destination:
  type: http
  url: https://accounting.example.com/api/stock
  headers:
    X-Location: '${artifacts.settings.location}'

Отдельный обработчик:

function transform(input, context) {
  const minimum = context.artifacts.settings.minimum;
  return {items: input.items.filter(item => item.quantity >= minimum)};
}

Доступ к значениям:

Этап Как читать
source type: artifact + name читает значение целиком. HTTP-источник принимает подстановки в url, headers и body.
conditions path: artifacts.settings.enabled; в value допустима подстановка ${artifacts.settings.minimum}. Поля источника доступны через input, поля события — как раньше.
transform Синхронное чтение context.artifacts.settings, без сетевых запросов и await.
destination Подстановки в HTTP url, headers, body; в шаге назначения input: ${artifacts.settings} или вложенное поле вместо результата transform.

Числа обрабатываются как обычные JavaScript-числа; идентификаторы за пределами безопасного целого храните строками.

Полная подстановка в JSON ('${artifacts.settings.minimum}') сохраняет тип значения: число остаётся числом, объект — объектом. Внутри строки значение преобразуется в текст. URL и заголовок при полной подстановке должны получить строку. Поля объектов разделяются точками; индекс массива — числом (${artifacts.settings.items.0.id}). Для body HTTP-назначения явно заданный шаблон заменяет тело из результата transform; без body сохраняется прежнее поведение.

Движок загружает только подключённые артефакты и артефакты-источники в начале запуска, каждое имя — один раз. Все этапы этого запуска используют эти загруженные значения. Обновление артефакта другим клиентом или назначением будет видно следующему запуску; общей атомарной транзакции между разными именами нет. Изменение context.artifacts в JavaScript не записывает данные и не меняет значения подстановок в других этапах.

До 20 алиасов в artifacts; алиас начинается с латинской буквы и содержит до 64 латинских букв, цифр или _. Имена constructor, prototype, __proto__ зарезервированы. Всего до 50 разных входных имён, суммарно до 5 МиБ JSON. Отсутствующий артефакт, неподключённый алиас или отсутствующее поле в подстановке останавливает запуск с ошибкой. Условие exists можно использовать для необязательного поля существующего артефакта.

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

Проверочный запуск читает настоящие входные артефакты текущей компании, проверяет условия и transform, но не вызывает назначения и ничего не записывает. Значения доступны в ручных, плановых и событийных автоматизациях; для события source по-прежнему не указывается.