Synchra.24
menu_bookҚұжаттама
Практические материалы по запуску и развитию

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

folderАвтоматтандыру

Қателерді тексеру және іздеу

Конфигурацияны қалай тексеруге, қауіпсіз тест жүргізуге, қадам деректерін оқуға және типтік қателерді жоюға болады.

Аударма әзірге қолжетімсіз. Түпнұсқа көрсетілді.

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

Три вида проверки

Действие Что происходит Отправка в назначение
Проверить конфигурацию Проверяется синтаксис YAML/JSON, обязательные поля, URL, cron и JavaScript. HTTP-запросы не выполняются. Нет
Проверочный запуск Выполняются источники и JavaScript-обработчик. Показываются полученные данные, результат и логи. Нет
Запустить Выполняется полный сценарий: источники, обработчик и назначения. Создаётся запись в истории. Да

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

Результат проверочного запуска

Модальное окно содержит три блока.

Получено из источника

Показывает фактический ответ источника после декодирования формата. Для steps выводятся данные каждого источника под его id.

Проверьте:

  • действительно ли вернулись нужные записи;
  • совпадают ли названия и вложенность полей;
  • правильно ли распознаны XML, CSV или кодировка;
  • не вернулась ли HTML-страница ошибки вместо данных.

После обработчика

Показывает значение, которое вернула функция transform. Именно оно будет сериализовано и отправлено в назначение при рабочем запуске.

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

Логи обработчика

Здесь выводятся console.log, console.info, console.warn и console.error, а также ошибка выполнения функции.

function transform(input, context) {
  var rows = Array.isArray(input) ? input : [];
  console.info("Получено записей:", rows.length);

  var valid = rows.filter(function (row) {
    return row.id && row.name;
  });

  console.info("Подготовлено записей:", valid.length);
  console.warn("Пропущено записей:", rows.length - valid.length);
  return valid;
}

Не выводите содержимое токенов, пароли и персональные данные. Известные секреты маскируются, но безопаснее вовсе не передавать их в лог.

История запусков

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

Типовой порядок диагностики:

  1. Откройте последний неуспешный запуск.
  2. Определите этап ошибки: источник, обработчик или назначение.
  3. Выполните Проверочный запуск.
  4. Сравните фактический вход с ожиданиями функции.
  5. После исправления снова проверьте конфигурацию и только затем выполните полный запуск.

Частые ошибки

Сообщение или симптом Причина Что сделать
invalid yaml или field ... not found Ошибка отступов, двоеточий или неизвестное поле. Используйте пробелы, запустите форматирование и сверьте название поля с конфигурацией автоматизации.
only pipeline versions 1 and 2 are supported Указана другая версия или пропущено version. Используйте version: 1, а для событийного триггера — version: 2.
event triggers require pipeline version 2 Событийный запуск описан в схеме версии 1. Замените верхнее поле на version: 2.
trigger.cron is required или invalid trigger.cron Для расписания нет корректного выражения из пяти полей. Проверьте минуту, час, день месяца, месяц и день недели.
trigger.cron must not run more often than every 30 minutes Расписание запускает автоматизацию чаще одного раза в 30 минут. Увеличьте интервал, например используйте */30 * * * * вместо */15 * * * *.
invalid trigger.timezone Неизвестное имя часового пояса. Используйте IANA-имя, например Europe/Moscow.
use either source/destination or steps, not both Смешаны простой и расширенный режимы. Оставьте либо source + destination, либо steps.
secret ... is not configured Переменная удалена, переименована или не создана. Создайте переменную с точным именем из ${secrets.NAME}.
Запрос к приватному или локальному адресу запрещён URL ведёт во внутреннюю сеть, localhost или служебный адрес. Используйте безопасно опубликованный HTTPS endpoint или интеграционный шлюз.
HTTP-статус вне диапазона 200–299 Внешний сервис вернул ошибку авторизации, данных или метода. Проверьте URL, метод, заголовки и права технической учётной записи.
Ответ превышает лимит Источник вернул более 5 МБ. Добавьте фильтр, период, пагинацию или отдельные автоматизации.
Неверные символы в тексте Не совпала кодировка. Для старых выгрузок 1С попробуйте encoding: windows-1251.
CSV стал одним столбцом Указан неправильный разделитель. Задайте options.delimiter, например ";".
CSV без названий полей В файле нет заголовка или неверно задан header. Используйте header: true для первой строки с именами либо обработайте массив значений согласно формату источника.
XML-поле иногда объект, иногда массив В XML встретился один или несколько одноимённых элементов. В обработчике приводите значение к массиву через вспомогательную функцию asArray.
javascript must define function transform Функция отсутствует или объявлена в неподдерживаемой форме. Объявите function transform(input, context) { ... }.
script timeout Код выполняется дольше лимита. Уберите тяжёлые циклы, сократите данные или увеличьте timeout_seconds максимум до 5.
scheduled automation exceeded the 60-second execution limit Плановый запуск целиком выполнялся дольше 60 секунд. Сократите объём данных, число шагов и повторов или разделите обмен на несколько автоматизаций. Ручные и проверочные запуски этим пределом не ограничиваются.
В назначение ушёл пустой объект Обработчик ничего не вернул или input шага указывает на отсутствующее поле. Добавьте return и проверьте ${transform.output.field} в результате проверки.
CSV-назначение не принимает результат Обработчик вернул объект вместо массива объектов. Верните массив строк будущей таблицы.

Проверка назначения

Поскольку проверочный запуск не вызывает назначения, сначала направьте рабочий запуск в тестовый endpoint внешней системы или используйте отдельную тестовую автоматизацию. Убедитесь, что:

  • метод и URL верны;
  • токен имеет право записи;
  • request.format соответствует ожиданиям API;
  • результат обработчика имеет нужную структуру;
  • повторный запуск не создаёт нежелательные дубликаты.

Для защиты от дублей передавайте внешний идентификатор записи и, если API поддерживает это, используйте идемпотентную операцию обновления.

Событие из собственного сервиса

Симптом Что проверить
В предпросмотре нет запуска в истории Это ожидаемо: {preview: true, accepted: false} означает имитацию без рабочей отправки. Проверяйте опубликованный сервис.
Событие отсутствует или отключено Сохраните сервис, создайте или включите определение во вкладке События. Код использует определение, а не создаёт его.
SDK не находит имя события В emitEvent передавайте локальное имя report_ready, а в trigger.event — полный код custom.service_42.report_ready.
Получен event_id, но результата нет Событие принято в очередь, но сценарий ещё может ожидать или завершиться ошибкой. Проверьте включение автоматизации, её компанию, условия и историю запусков.
Ответ 409 при отправке Ключ операции уже использован с другим событием или payload. Не заменяйте ключ автоматически; выясните, какая операция уже была принята.
Ответ 429 Превышена частота, объём или ёмкость очереди. Подождите указанный срок. При повторе той же операции используйте прежний requestKey и неизменный payload.
Ответ 503 Временно недоступна проверка или приём события. Покажите ошибку и дайте повторить позже, сохранив ключ операции.
При включении автоматизации сообщается о лимите Для одного пользовательского события допускается до 20 включённых сценариев. Отключите лишние привязки.
Вызов не работает на телефоне Новый метод пока поддерживается встроенным веб-движком, но не мобильным мостом.

Если ответ потерялся, повтор с тем же ключом и данными вернёт прежний event_id с признаком duplicate; это не новая операция. Защита действует не менее 24 часов. Не добавляйте бесконечные повторы и не создавайте новый ключ на каждую попытку.

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

Контрольный список перед включением

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

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

Ошибки входных артефактов

Проверочный запуск читает подключённые настоящие артефакты компании, но не вызывает назначения. read artifact ...: not found означает, что имя из artifacts или источника отсутствует в этой компании; сначала создайте его. Ошибка отсутствующего поля означает неверный алиас или путь ${artifacts.alias.field}. Проверьте регистр и структуру JSON; для необязательного поля в условии используйте exists. JSON-значение null допустимо, отсутствие артефакта — ошибка. Ошибка 404 при setArtifact не создаёт новое имя. Ошибки 403 проверяйте по лицензии API и праву admin_edit_provider_integrations, 409 — по квоте. Подробные правила.

Проблемы импорта ZIP

Для автоматизации нужен automation.json, файл YAML/JSON-конфигурации и .js-обработчик. Пакет сервиса с service.json или одиночный YAML не подходит для ZIP-импорта. Ошибка версии означает несовместимый формат пакета или pipeline. Исправьте файл, заново упакуйте ZIP и выберите его повторно; при ошибке проверки запись не создаётся.

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

Уведомления MAX

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

Симптом Что сделать
Общий бот ещё не подключён Сохраните автоматизацию выключенной; настройка отправки появится после подключения бота оператором Synchra24.
Бот не отвечает на /chatid Проверьте, что команда отправлена в групповой чат или канал, у бота есть право писать, а общий бот доступен. Ответ на команду ограничен одним сообщением в минуту на чат.
Код не подходит Введите последний полученный шестизначный код в течение 10 минут. После пяти неверных попыток запросите новый, учитывая ограничение частоты.
Нельзя включить автоматизацию Убедитесь, что имя назначения совпадает с подтверждённым подключением этой компании. Для готовых расширений обычно используется default.
Сообщение не пришло после события Проверьте включение, условия и историю. Для MAX автоматического повтора нет: при неопределённом результате сначала проверьте чат.
Бот удалён или заменён Добавьте действующего бота с правом отправки и заново подтвердите подключение.
Отключены сразу несколько автоматизаций Удаление подключения останавливает отправку у всех автоматизаций, использующих это имя. Сами автоматизации при этом могут оставаться включёнными и показывать ошибку назначения.

Правила подключения и ограничения.