Как составить свой сценарий

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

Один сценарий соответствует одному пункту меню терминала — например «Приёмка», «Инвентаризация», «Списание брака».

Сценарий описывается текстом в формате JSON — с фигурными скобками. Этот текст и редактируется. Ниже приведены готовые блоки: их достаточно скопировать и изменить подписи.

1. Откройте раздел «Сценарии операций».
2. Нажмите «Новый сценарий». Откроется редактор с заполненной заготовкой.
3. Замените текст в большом поле на свой.
4. Впишите название сценария вверху и выберите тип операции.
5. Нажмите «Сохранить как новый сценарий».

Чтобы изменить готовый сценарий, откройте его из списка, отредактируйте текст и нажмите «Сохранить изменения». Прежняя версия сохраняется в истории.

Каждый сценарий устроен одинаково: сверху общие данные, ниже — список шагов. Пустой каркас:

{
  "id": "moy-scenarij-1",
  "name": "Мой сценарий",
  "operation_type": "receive",
  "version": 1,
  "start_step": "shag_1",
  "steps": [

  ]
}

Назначение полей:

id

Имя сценария латинскими буквами без пробелов, уникальное (например priyomka-bez-zakaza). Впоследствии изменять не требуется.

name

Название, отображаемое в кабинете и на терминале. Указывается по-русски.

operation_type

Тип операции (см. раздел «Какие бывают операции»).

version

Указывается 1; далее номер версии ведётся автоматически.

start_step

id первого шага.

steps

Список блоков шагов; блоки указываются между квадратными скобками через запятую.

Необязательные поля верхнего уровня

visible_role

Роль (группа) работника, которому виден этот сценарий на терминале. Без поля сценарий виден всем. Например "visible_role": "operator" — пункт меню увидят только работники с ролью operator (роль задаётся в карточке пользователя терминала). Совпадение точное: работник с ролью admin сценарий с ролью operator не увидит.

visible_users

Список работников по их логину, которым виден сценарий. Без поля виден всем. Удобнее заполнять не вручную, а галочками: в блоке «Доступ пользователям» отметьте нужных работников — список запишется автоматически. Если заданы и visible_role, и visible_users, сценарий увидят только работники, подходящие под оба условия.

no_soft_keyboard

"no_soft_keyboard": true — экранная клавиатура не всплывает. Удобно на ТСД со встроенным сканером. Ставится в двух местах:

• в корне — клавиатура отключается на всех полях сценария;
• внутри конкретного шага — только на нём. Так чаще и нужно: на шаге сканирования клавиатуру отключают, а на шаге «Количество» оставляют, чтобы число можно было ввести с клавиатуры.

allow_unplanned_items

Только для сценариев по заказу. По умолчанию работник может добавить только товары из заказа; посторонний товар терминал отклоняет с ошибкой «нет в плане заказа». "allow_unplanned_items": true — разрешено добавлять товары сверх заказа. На сценарии без заказа не влияет.

block_overpick

true — нельзя собрать больше плана: как только факт по позиции превысит план, терминал отклонит скан и не добавит лишнее. По умолчанию выключено (перебор только подсвечивается в конце). Работает только при наличии плана.

restrict_to_supplier_products

Только для приёмки, привязанной к документу. true — работник добавит только товары того поставщика, что указан в документе. Список берётся из МойСклад по полю «Поставщик» в карточке товара. Если поле пустое, ограничивать нечем — терминал ничего не блокирует. Снять ограничение можно тем же allow_unplanned_items.

document_list

Ограничивает и упорядочивает список документов на старте сценария. Внутри:

• status — статус документа по названию из МойСклад (регистр и пробелы не важны).
• sort — порядок по дате: date_desc (новые сверху, по умолчанию) или date_asc.
• conducted — yes (только проведённые), no (только черновики), any (все). Когда задано, переключатель «Показать все» на терминале скрывается.

Пример: { "status": "СБОРКА", "sort": "date_desc", "conducted": "yes" }.

bind_document

Как сценарий работает с уже созданным документом, к которому привязывается. Внутри: mode (write — писать и проводить, по умолчанию; readonly — только читать), plan_from_document (показывать позиции документа как «План»), fact_baseline (document или zero), set_status (поменять статус на финише), comment_on_short (записать расхождения в комментарий), only_with_supplier. Только для сценариев, привязанных к документу; с create_document не используется.

auto_save_interval_sec

Период автосохранения в секундах при работе с одним документом с нескольких терминалов. По умолчанию 0 — строки уходят при сканировании. Для нескольких терминалов разумно 15–60 секунд. В кабинете задаётся в блоке «Автосохранение во время работы».

weighed_barcode

Настройка весового товара (штрихкод печатают весы с зашитым весом). Без поля действует стандартный формат. При другом формате весов задают value_type (weight/price), value_digits, divisor, prefix, enabled. Вес подставляется только если товар отмечен весовым в МойСклад.

finish_conduct

Проводить ли документ в конце. По умолчанию документ проводится автоматически. "finish_conduct": false — документ останется черновиком, его проверят и проведут в офисе.

Пример каркаса с полями:

{
  "id": "moy-scenarij-1",
  "name": "Мой сценарий",
  "operation_type": "receive",
  "version": 1,
  "start_step": "shag_1",
  "visible_role": "operator",
  "no_soft_keyboard": true,
  "steps": [

  ]
}

В поле operation_type указывается одно из значений:

Шаги для приёмки, отгрузки, инвентаризации и перемещения совпадают: отсканировать товар и ввести количество. Различается значение operation_type вверху — от него зависит, какой документ создаётся в МойСклад.

Сценарии создания документов

Отдельная группа. В обычном сценарии документ уже существует (его завели в офисе), а терминал лишь набирает в него позиции. В сценарии создания документа всё наоборот: документ создаёт сам терминал — заранее в офисе ничего заводить не нужно. Работник выбирает склад, затем — то, что нужно операции (контрагента, второй склад или ничего), сканирует товары и вводит количество. В конце документ сохраняется в МойСклад черновиком.

Заказы покупателя и поставщику — это заказы, а не складская операция: движения товара они не делают, цена позиций не заполняется (0). Эти сценарии не появляются в аккаунте сами — их добавляют вручную (готовые блоки — в разделе «Готовые примеры»). Запуск требует современной версии приложения терминала: на старом терминале пункт в меню не появится.

Каждый блок — один шаг. Нужные блоки копируются в список steps. В блоках изменяются только русские тексты: title — надпись на экране, tts — что терминал произносит вслух. Остальные поля остаются без изменений. У каждого блока есть id — его имя, по нему блоки ссылаются друг на друга. При вставке двух однотипных блоков задайте им разные id.

Блок «Сканирование товара»

Работник сканирует штрихкод, терминал находит товар в базе.

{
  "id": "scan_tovar",
  "type": "scan",
  "field": "barcode",
  "title": "Отсканируйте штрихкод товара",
  "tts": "Отсканируйте штрихкод",
  "required": true,
  "next": "kolichestvo",
  "resolve": {
    "search_types": ["barcode", "article", "fuzzy"],
    "targets": { "assortment_id": "id", "assortment_name": "name" },
    "required": true
  }
}

Изменяются title и tts. Блок resolve отвечает за поиск товара и остаётся без изменений. В next указывается id следующего блока.

Авто-количество. Если на шаге скана поставить "auto_quantity": true, отдельный шаг «Количество» не нужен: после того как скан нашёл товар, терминал сам добавляет +1 и возвращается на шаг скана (один скан = одна единица). Множитель по упаковке ("pack_multiplier": true) учитывает упаковки: штрихкод единицы — +1, штрихкод коробки — её количество из карточки. Весовой товар распознаётся на том же шаге сканирования и включается полем weighed_barcode в корне.

Блок «Количество»

Работник называет или вводит число.

{
  "id": "kolichestvo",
  "type": "number",
  "field": "quantity",
  "title": "Сколько штук?",
  "tts": "Сколько штук?",
  "required": true,
  "min": 0,
  "next": "zavershenie",
  "pre_actions": [
    { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity"] }
  ]
}

Изменяются title и tts. Строка pre_actions добавляет товар в документ и остаётся без изменений.

Блок «Вопрос да/нет»

Терминал задаёт вопрос, работник отвечает «да» или «нет». Типичное применение — цикл «добавить ещё товар».

{
  "id": "eshchyo",
  "type": "confirm",
  "field": "more_items",
  "title": "Добавить ещё товар?",
  "tts": "Добавить ещё товар?",
  "required": true,
  "next_map": { "true": "scan_tovar", "false": "zavershenie" }
}

Здесь вместо next используется next_map: при ответе «да» (true) — один блок, при «нет» (false) — другой.

Блок «Ввод текста»

Работник диктует или вводит произвольный текст — например причину списания.

{
  "id": "prichina",
  "type": "text",
  "field": "reason",
  "title": "Назовите причину списания",
  "tts": "Назовите причину",
  "required": true,
  "next": "eshchyo"
}

Блок «Выбор из списка»

Работник выбирает один из заранее заданных вариантов.

{
  "id": "vybor",
  "type": "select",
  "field": "action",
  "title": "Что сделать с товаром?",
  "tts": "Выберите действие",
  "required": true,
  "options": ["Принять", "Отклонить"],
  "next": "zavershenie"
}

Список вариантов задаётся в options. Сценарий можно направить по выбранному варианту, заменив next на next_map с перечислением вариантов.

Блок «Завершение»

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

{
  "id": "zavershenie",
  "type": "finish",
  "title": "Готово",
  "tts": "Готово"
}

Блоки выстраиваются в цепочку. Связь задаётся полем next — это id блока, к которому переходит сценарий. Например, чтобы после сканирования запросить количество, а затем завершить: у блока сканирования "next": "kolichestvo"; у блока количества "next": "zavershenie"; блок завершения далее ничего не вызывает.

Для ветвления (по ответу «да/нет» или по выбранному варианту) вместо next используется next_map, где для каждого ответа указан свой блок.

Чтобы добавить шаг в середину:

1. Скопируйте подходящий блок и задайте ему новый уникальный id.
2. Вставьте его в список steps (блоки отделяются запятой).
3. У предыдущего блока в next укажите id нового блока.
4. У нового блока в next укажите, куда переходить дальше.

Первый блок цепочки указывается вверху в start_step.

Пример 1. Простая приёмка

Отсканировать товар → ввести количество → завершить.

{
  "id": "primer-priyomka-1",
  "name": "Простая приёмка",
  "operation_type": "receive",
  "version": 1,
  "start_step": "scan_tovar",
  "steps": [
    {
      "id": "scan_tovar",
      "type": "scan",
      "field": "barcode",
      "title": "Отсканируйте штрихкод товара",
      "tts": "Отсканируйте штрихкод",
      "required": true,
      "next": "kolichestvo",
      "resolve": {
        "search_types": ["barcode", "article", "fuzzy"],
        "targets": { "assortment_id": "id", "assortment_name": "name" },
        "required": true
      }
    },
    {
      "id": "kolichestvo",
      "type": "number",
      "field": "quantity",
      "title": "Сколько штук?",
      "tts": "Сколько штук?",
      "required": true,
      "min": 0,
      "next": "zavershenie",
      "pre_actions": [
        { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity"] }
      ]
    },
    { "id": "zavershenie", "type": "finish", "title": "Приёмка завершена", "tts": "Приёмка завершена" }
  ]
}

Пример 2. Приёмка нескольких товаров

После количества терминал спрашивает «добавить ещё?» и при ответе «да» возвращается к сканированию.

{
  "id": "primer-priyomka-2",
  "name": "Приёмка нескольких товаров",
  "operation_type": "receive",
  "version": 1,
  "start_step": "scan_tovar",
  "steps": [
    {
      "id": "scan_tovar",
      "type": "scan",
      "field": "barcode",
      "title": "Отсканируйте штрихкод товара",
      "tts": "Отсканируйте штрихкод",
      "required": true,
      "next": "kolichestvo",
      "resolve": {
        "search_types": ["barcode", "article", "fuzzy"],
        "targets": { "assortment_id": "id", "assortment_name": "name" },
        "required": true
      }
    },
    {
      "id": "kolichestvo",
      "type": "number",
      "field": "quantity",
      "title": "Сколько штук?",
      "tts": "Сколько штук?",
      "required": true,
      "min": 0,
      "next": "eshchyo",
      "pre_actions": [
        { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity"] }
      ]
    },
    {
      "id": "eshchyo",
      "type": "confirm",
      "field": "more_items",
      "title": "Добавить ещё товар?",
      "tts": "Добавить ещё товар?",
      "required": true,
      "next_map": { "true": "scan_tovar", "false": "zavershenie" }
    },
    { "id": "zavershenie", "type": "finish", "title": "Приёмка завершена", "tts": "Приёмка завершена" }
  ]
}

Пример 3. Списание с указанием причины

Отсканировать товар → количество → причина → «добавить ещё?» → завершить.

{
  "id": "primer-spisanie-1",
  "name": "Списание брака",
  "operation_type": "loss",
  "version": 1,
  "start_step": "scan_tovar",
  "field_mappings": [
    { "line_field": "reason", "ms_target": "reason" }
  ],
  "steps": [
    {
      "id": "scan_tovar",
      "type": "scan",
      "field": "barcode",
      "title": "Отсканируйте товар для списания",
      "tts": "Отсканируйте товар",
      "required": true,
      "next": "kolichestvo",
      "resolve": {
        "search_types": ["barcode", "article", "fuzzy"],
        "targets": { "assortment_id": "id", "assortment_name": "name" },
        "required": true
      }
    },
    {
      "id": "kolichestvo",
      "type": "number",
      "field": "quantity",
      "title": "Сколько списать?",
      "tts": "Сколько списать?",
      "required": true,
      "min": 0,
      "next": "prichina"
    },
    {
      "id": "prichina",
      "type": "text",
      "field": "reason",
      "title": "Назовите причину списания",
      "tts": "Назовите причину",
      "required": true,
      "next": "eshchyo",
      "pre_actions": [
        { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity", "reason"] }
      ]
    },
    {
      "id": "eshchyo",
      "type": "confirm",
      "field": "more_items",
      "title": "Добавить ещё товар?",
      "tts": "Добавить ещё товар?",
      "required": true,
      "next_map": { "true": "scan_tovar", "false": "zavershenie" }
    },
    { "id": "zavershenie", "type": "finish", "title": "Списание завершено", "tts": "Списание завершено" }
  ]
}

Строка field_mappings вверху переносит причину в документ МойСклад.

Пример 4. Сценарии создания документов

Готовые сценарии, в которых терминал сам создаёт документ. Откройте «Новый сценарий», вставьте текст и сохраните. Тексты (title, tts) можно менять, остальное лучше оставить как есть. Документ во всех случаях сохраняется черновиком ("finish_conduct": false); запуск требует современной версии приложения ("min_client_version": 2).

Создание приёмки

Перед стартом работник выбирает склад и поставщика, затем сканирует товары.

{
  "id": "default-create-receive-v1",
  "name": "Создание приёмки",
  "operation_type": "receive",
  "version": 1,
  "start_step": "scan_barcode",
  "incremental_save": true,
  "steps": [
    {
      "id": "scan_barcode",
      "type": "scan",
      "field": "barcode",
      "title": "Отсканируйте штрихкод товара",
      "required": true,
      "next": "quantity",
      "next_map": {
        "готово": "confirm_finish",
        "завершить": "confirm_finish",
        "стоп": "confirm_finish"
      },
      "tts": "Отсканируйте штрихкод",
      "resolve": {
        "search_types": ["barcode", "article", "fuzzy"],
        "targets": {
          "assortment_id": "id",
          "assortment_name": "name",
          "gtin": "gtin",
          "marking_mode": "marking_mode"
        },
        "required": true
      }
    },
    {
      "id": "quantity",
      "type": "number",
      "field": "quantity",
      "title": "Укажите количество",
      "required": true,
      "next": "scan_barcode",
      "min": 0,
      "tts": "Сколько штук?",
      "pre_actions": [
        { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity"] }
      ]
    },
    {
      "id": "confirm_finish",
      "type": "confirm",
      "field": "confirm_finish",
      "title": "Завершить приёмку?",
      "required": true,
      "next_map": { "false": "scan_barcode", "true": "finish" },
      "tts": "Завершить приёмку?"
    },
    {
      "id": "finish",
      "type": "finish",
      "field": "",
      "title": "Приёмка создана",
      "required": false,
      "tts": "Приёмка создана"
    }
  ],
  "min_client_version": 2,
  "create_document": { "pick_agent": true },
  "finish_conduct": false
}

Создание перемещения

Перед стартом — склад-источник и склад-приёмник (второй должен отличаться от первого).

{
  "id": "default-create-move-v1",
  "name": "Создание перемещения",
  "operation_type": "move",
  "version": 1,
  "start_step": "scan_barcode",
  "incremental_save": true,
  "steps": [
    {
      "id": "scan_barcode",
      "type": "scan",
      "field": "barcode",
      "title": "Отсканируйте штрихкод товара",
      "required": true,
      "next": "quantity",
      "next_map": {
        "готово": "confirm_finish",
        "завершить": "confirm_finish",
        "стоп": "confirm_finish"
      },
      "tts": "Отсканируйте штрихкод",
      "resolve": {
        "search_types": ["barcode", "article", "fuzzy"],
        "targets": {
          "assortment_id": "id",
          "assortment_name": "name",
          "gtin": "gtin",
          "marking_mode": "marking_mode"
        },
        "required": true
      }
    },
    {
      "id": "quantity",
      "type": "number",
      "field": "quantity",
      "title": "Укажите количество",
      "required": true,
      "next": "scan_barcode",
      "min": 0,
      "tts": "Сколько штук?",
      "pre_actions": [
        { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity"] }
      ]
    },
    {
      "id": "confirm_finish",
      "type": "confirm",
      "field": "confirm_finish",
      "title": "Завершить перемещение?",
      "required": true,
      "next_map": { "false": "scan_barcode", "true": "finish" },
      "tts": "Завершить перемещение?"
    },
    {
      "id": "finish",
      "type": "finish",
      "field": "",
      "title": "Перемещение создано",
      "required": false,
      "tts": "Перемещение создано"
    }
  ],
  "min_client_version": 2,
  "create_document": { "pick_target_store": true },
  "finish_conduct": false
}

Создание списания

Перед стартом — только склад. «Создание оприходования» устроено так же, отличается только operation_type (enter) и текстами.

{
  "id": "default-create-loss-v1",
  "name": "Создание списания",
  "operation_type": "loss",
  "version": 1,
  "start_step": "scan_barcode",
  "incremental_save": true,
  "steps": [
    {
      "id": "scan_barcode",
      "type": "scan",
      "field": "barcode",
      "title": "Отсканируйте штрихкод товара",
      "required": true,
      "next": "quantity",
      "next_map": {
        "готово": "confirm_finish",
        "завершить": "confirm_finish",
        "стоп": "confirm_finish"
      },
      "tts": "Отсканируйте штрихкод",
      "resolve": {
        "search_types": ["barcode", "article", "fuzzy"],
        "targets": {
          "assortment_id": "id",
          "assortment_name": "name",
          "gtin": "gtin",
          "marking_mode": "marking_mode"
        },
        "required": true
      }
    },
    {
      "id": "quantity",
      "type": "number",
      "field": "quantity",
      "title": "Укажите количество",
      "required": true,
      "next": "scan_barcode",
      "min": 0,
      "tts": "Сколько штук?",
      "pre_actions": [
        { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity"] }
      ]
    },
    {
      "id": "confirm_finish",
      "type": "confirm",
      "field": "confirm_finish",
      "title": "Завершить списание?",
      "required": true,
      "next_map": { "false": "scan_barcode", "true": "finish" },
      "tts": "Завершить списание?"
    },
    {
      "id": "finish",
      "type": "finish",
      "field": "",
      "title": "Списание создано",
      "required": false,
      "tts": "Списание создано"
    }
  ],
  "min_client_version": 2,
  "create_document": {},
  "finish_conduct": false
}

Создание заказа покупателя

Перед стартом — склад и покупатель. Движения товара нет, цена позиций — 0.

{
  "id": "default-create-customerorder-v1",
  "name": "Создание заказа покупателя",
  "operation_type": "customerorder",
  "version": 1,
  "start_step": "scan_barcode",
  "incremental_save": true,
  "steps": [
    {
      "id": "scan_barcode",
      "type": "scan",
      "field": "barcode",
      "title": "Отсканируйте штрихкод товара",
      "required": true,
      "next": "quantity",
      "next_map": {
        "готово": "confirm_finish",
        "завершить": "confirm_finish",
        "стоп": "confirm_finish"
      },
      "tts": "Отсканируйте штрихкод",
      "resolve": {
        "search_types": ["barcode", "article", "fuzzy"],
        "targets": {
          "assortment_id": "id",
          "assortment_name": "name",
          "gtin": "gtin",
          "marking_mode": "marking_mode"
        },
        "required": true
      }
    },
    {
      "id": "quantity",
      "type": "number",
      "field": "quantity",
      "title": "Укажите количество",
      "required": true,
      "next": "scan_barcode",
      "min": 0,
      "tts": "Сколько штук?",
      "pre_actions": [
        { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity"] }
      ]
    },
    {
      "id": "confirm_finish",
      "type": "confirm",
      "field": "confirm_finish",
      "title": "Завершить заказ покупателя?",
      "required": true,
      "next_map": { "false": "scan_barcode", "true": "finish" },
      "tts": "Завершить заказ покупателя?"
    },
    {
      "id": "finish",
      "type": "finish",
      "field": "",
      "title": "Заказ покупателя создан",
      "required": false,
      "tts": "Заказ покупателя создан"
    }
  ],
  "min_client_version": 2,
  "create_document": { "pick_agent": true },
  "finish_conduct": false
}

Создание заказа поставщику

Перед стартом — склад и поставщик. Как и заказ покупателя: движения товара нет, цена — 0.

{
  "id": "default-create-purchaseorder-v1",
  "name": "Создание заказа поставщику",
  "operation_type": "purchaseorder",
  "version": 1,
  "start_step": "scan_barcode",
  "incremental_save": true,
  "steps": [
    {
      "id": "scan_barcode",
      "type": "scan",
      "field": "barcode",
      "title": "Отсканируйте штрихкод товара",
      "required": true,
      "next": "quantity",
      "next_map": {
        "готово": "confirm_finish",
        "завершить": "confirm_finish",
        "стоп": "confirm_finish"
      },
      "tts": "Отсканируйте штрихкод",
      "resolve": {
        "search_types": ["barcode", "article", "fuzzy"],
        "targets": {
          "assortment_id": "id",
          "assortment_name": "name",
          "gtin": "gtin",
          "marking_mode": "marking_mode"
        },
        "required": true
      }
    },
    {
      "id": "quantity",
      "type": "number",
      "field": "quantity",
      "title": "Укажите количество",
      "required": true,
      "next": "scan_barcode",
      "min": 0,
      "tts": "Сколько штук?",
      "pre_actions": [
        { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity"] }
      ]
    },
    {
      "id": "confirm_finish",
      "type": "confirm",
      "field": "confirm_finish",
      "title": "Завершить заказ поставщику?",
      "required": true,
      "next_map": { "false": "scan_barcode", "true": "finish" },
      "tts": "Завершить заказ поставщику?"
    },
    {
      "id": "finish",
      "type": "finish",
      "field": "",
      "title": "Заказ поставщику создан",
      "required": false,
      "tts": "Заказ поставщику создан"
    }
  ],
  "min_client_version": 2,
  "create_document": { "pick_agent": true },
  "finish_conduct": false
}

«Создание отгрузки» (demand, склад и покупатель) и «Создание оприходования» (enter, только склад) устроены так же. Чтобы получить их, возьмите подходящий блок выше и поменяйте id, name, operation_type и тексты: отгрузка — из блока приёмки, оприходование — из блока списания.

Раздел отвечает на типовые вопросы по сценариям из предыдущего пункта, где документ создаёт сам терминал. Под конкретную задачу меняются, как правило, два места: поле finish_conduct вверху — проводить документ сразу или оставить черновиком, — и для списания добавляется шаг «Причина».

Задача 1. Терминал сам создаёт отгрузку — без заявки из офиса

Заранее заводить отгрузку в МойСклад не нужно. Работник открывает пункт меню, выбирает склад и покупателя, сканирует товар и вводит количество — на «Завершить» отгрузка создаётся в МойСклад. Это делает связка "operation_type": "demand" и "create_document": { "pick_agent": true }. Готовый блок — в Задаче 2.

Задача 2. Отгрузка сохраняется проведённой (списывает остаток)

За проведение отвечает finish_conduct. Значение "finish_conduct": true (либо строку можно вовсе убрать — по умолчанию документ проводится) означает: на «Завершить» отгрузка не только создаётся, но и проводится, остаток списывается сразу. Готовый блок отгрузки с проведением:

{
  "id": "sozdanie-otgruzki",
  "name": "Создание отгрузки",
  "operation_type": "demand",
  "version": 1,
  "start_step": "scan_barcode",
  "incremental_save": true,
  "steps": [
    {
      "id": "scan_barcode",
      "type": "scan",
      "field": "barcode",
      "title": "Отсканируйте штрихкод товара",
      "required": true,
      "next": "quantity",
      "next_map": {
        "готово": "confirm_finish",
        "завершить": "confirm_finish",
        "стоп": "confirm_finish"
      },
      "tts": "Отсканируйте штрихкод",
      "resolve": {
        "search_types": ["barcode", "article", "fuzzy"],
        "targets": {
          "assortment_id": "id",
          "assortment_name": "name",
          "gtin": "gtin",
          "marking_mode": "marking_mode"
        },
        "required": true
      }
    },
    {
      "id": "quantity",
      "type": "number",
      "field": "quantity",
      "title": "Укажите количество",
      "required": true,
      "next": "scan_barcode",
      "min": 0,
      "tts": "Сколько штук?",
      "pre_actions": [
        { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity"] }
      ]
    },
    {
      "id": "confirm_finish",
      "type": "confirm",
      "field": "confirm_finish",
      "title": "Завершить отгрузку?",
      "required": true,
      "next_map": { "false": "scan_barcode", "true": "finish" },
      "tts": "Завершить отгрузку?"
    },
    {
      "id": "finish",
      "type": "finish",
      "field": "",
      "title": "Отгрузка создана",
      "required": false,
      "tts": "Отгрузка создана"
    }
  ],
  "min_client_version": 2,
  "create_document": { "pick_agent": true },
  "finish_conduct": true
}

Задача 3. Приёмка остаётся черновиком, без галочки «Проведено»

Обратный случай: приёмку набирают на терминале, а проводит её оператор в офисе — уже после того, как приедет весь довоз. Для этого ставят "finish_conduct": false — документ сохранится черновиком, галочка «Проведено» в МойСклад снята. Готовый блок «Создание приёмки» из раздела «Готовые примеры» уже собран именно так — менять ничего не нужно. Если у какого-то сценария документ проводится сам, а нужен черновик — добавьте вверху строку "finish_conduct": false.

Задача 4. Создание списания с указанием причины

Списание браков часто требует причину. Её добавляют так же, как в «Примере 3»: отдельным шагом text с полем reason и строкой field_mappings вверху, которая переносит причину в позицию документа МойСклад. Причину делают обязательной ("required": true) — пустую терминал не пропустит. Готовый блок:

{
  "id": "sozdanie-spisaniya-s-prichinoy",
  "name": "Создание списания с причиной",
  "operation_type": "loss",
  "version": 1,
  "start_step": "scan_barcode",
  "incremental_save": true,
  "field_mappings": [
    { "line_field": "reason", "ms_target": "reason" }
  ],
  "steps": [
    {
      "id": "scan_barcode",
      "type": "scan",
      "field": "barcode",
      "title": "Отсканируйте штрихкод товара",
      "required": true,
      "next": "quantity",
      "next_map": {
        "готово": "confirm_finish",
        "завершить": "confirm_finish",
        "стоп": "confirm_finish"
      },
      "tts": "Отсканируйте штрихкод",
      "resolve": {
        "search_types": ["barcode", "article", "fuzzy"],
        "targets": {
          "assortment_id": "id",
          "assortment_name": "name",
          "gtin": "gtin",
          "marking_mode": "marking_mode"
        },
        "required": true
      }
    },
    {
      "id": "quantity",
      "type": "number",
      "field": "quantity",
      "title": "Укажите количество",
      "required": true,
      "next": "reason",
      "min": 0,
      "tts": "Сколько штук?"
    },
    {
      "id": "reason",
      "type": "text",
      "field": "reason",
      "title": "Назовите причину списания",
      "required": true,
      "next": "scan_barcode",
      "tts": "Назовите причину списания",
      "pre_actions": [
        { "type": "collect_items", "fields": ["assortment_id", "assortment_name", "quantity", "reason"] }
      ]
    },
    {
      "id": "confirm_finish",
      "type": "confirm",
      "field": "confirm_finish",
      "title": "Завершить списание?",
      "required": true,
      "next_map": { "false": "scan_barcode", "true": "finish" },
      "tts": "Завершить списание?"
    },
    {
      "id": "finish",
      "type": "finish",
      "field": "",
      "title": "Списание создано",
      "required": false,
      "tts": "Списание создано"
    }
  ],
  "min_client_version": 2,
  "create_document": {},
  "finish_conduct": false
}

Порядок шагов: отсканировать товар → количество → причина → снова сканирование (или слово «готово», чтобы завершить). Строка collect_items стоит на шаге «Причина» — товар добавляется в документ уже вместе с причиной.

Общее для всех сценариев создания: чтобы пункт появился в меню терминала, нужна современная версия приложения ("min_client_version": 2), и сценарий должен быть включён на аккаунте — сами эти сценарии не появляются, их добавляют вручную. Инвентаризацию «с нуля» терминал пока не создаёт: для неё документ заводят в МойСклад.

Допустимо изменять:

• надписи на экране (title) и голосовые подсказки (tts);
• название сценария (name) и тип операции (operation_type);
• порядок шагов и связи между ними (next, next_map);
• минимальное количество (min), варианты выбора (options);
• кому виден сценарий (visible_role, visible_users), отключение клавиатуры (no_soft_keyboard), автосохранение (auto_save_interval_sec);
• проводить ли документ или оставить черновиком (finish_conduct).

Остаются без изменений:

• блок resolve (поиск товара);
• строка pre_actions с collect_items (добавление товара в документ);
• строка field_mappings.

Требуют отдельной настройки с нашей стороны: работа с ячейками (адресное хранение), маркировка «Честный знак», перенос в документ дополнительных полей кроме количества и причины, сборка или приёмка по заказу. Для подключения обратитесь к нам.

Для простых сценариев из раздела «Блоки» эти значения менять не нужно — блоки уже заполнены правильно. Справочник нужен, если хочется понять, что означает каждое поле, или собрать нестандартный сценарий.

Тип шага (type)

Поиск товара/ячейки (resolve)

Блок resolve на шаге scan запускает поиск после ввода. Поля: search_types — список способов поиска (первый сработавший выигрывает); targets — куда записать найденное; required — true: если ничего не нашлось, шаг блокируется ошибкой.

Значения targets (слева — имя поля в сценарии, выбирается свободно; справа — что записать):

Типовой targets для товара: { "assortment_id": "id", "assortment_name": "name" }.

Предшаги (pre_actions)

merge_key — по каким полям строки сливаются (числа суммируются), по умолчанию assortment_id. no_merge: true — каждая фиксация = отдельная строка (серийный/поштучный учёт).

Перенос полей в документ (field_mappings)

Каждый элемент — { "line_field": "<поле строки>", "ms_target": "<поле позиции>" }. Неизвестные ms_target молча игнорируются. Это продвинутая настройка — для маркировки и ячеек её обычно настраиваем мы.

Проверка ввода (validation)

Условный переход (next_map)

next — безусловный переход. next_map — переход по значению ввода: "значение": "id шага". Значение сверяется как текст: для confirm это "true"/"false", для select — выбранный вариант, для scan/text — введённое значение. Если совпадения нет, используется next.

Редактор проверяет сценарий перед сохранением и выводит сообщение. Частые сообщения и их причины:

Если сообщение об ошибке непонятно либо сценарий сохранён, но на терминале работает не так, как ожидалось, — направьте нам текст сценария.