Обмен с 1С выполняется в воркфлоу Medusa, и в нескольких из них плагин предоставляет хуки. Обработчик хука получает то, что обмен собирается записать в Medusa или отправить в 1С, и возвращает исправленную версию. Так вы переносите реквизиты 1С в поля товара, дописываете в заказ данные, которых нет в Medusa, или включаете прайс-лист для группы покупателей, не меняя код плагина.

---

Импортируйте воркфлоу из @gorgo-store/medusa-erp-1c/workflows, а типы входных данных и результата хуков и функции чтения реквизитов и свойств 1С из @gorgo-store/medusa-erp-1c/hooks.

---

Зарегистрируйте обработчик в файле внутри src/workflows/hooks вашего проекта Medusa. Medusa загрузит его при запуске сервера. Например, этот обработчик не пускает в магазин услуги из 1С:

src/workflows/hooks/onec-catalog.ts
1import { StepResponse } from "@medusajs/framework/workflows-sdk"
2import { importOnecProductsWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"
3import { readRequisite } from "@gorgo-store/medusa-erp-1c/hooks"
4
5importOnecProductsWorkflow.hooks.setProducts(async ({ products }) => {
6  return new StepResponse({
7    products: products.filter(({ source }) => readRequisite(source, "ВидНоменклатуры") !== "Услуга"),
8  })
9})

Обработчик получает товары пачки и возвращает их в StepResponse, оставив только те, у которых реквизит «ВидНоменклатуры» не «Услуга». readRequisite читает реквизит товара 1С по его наименованию, так что разбирать CommerceML самому не нужно.

---

Каждый хук, кроме setPayload, получает массив элементов. Элемент сводит в одно место всё, что нужно для решения:

• source – запись, из которой строится результат. На импорте это запись 1С, на выгрузке заказ Medusa.
• existing – текущая запись Medusa. Она есть только на импорте и только у записи, которая уже есть в Medusa.
• Поле цели – то, что обмен запишет или отправит. У товара это product, у типа цен priceList и prices, у заказа document.

Обработчик правит поле цели и возвращает элементы. setPayload устроен иначе. Он получает готовый XML строкой и нужен для того, чего нет в модели товара или документа, например для версии схемы, которую ждёт ваша конфигурация 1С.

---

• Верните new StepResponse({ <массив> }). Плагин берёт только массив, остальные ключи входных данных возвращать не нужно.
• Уберите элемент, чтобы не писать запись в этом обмене. Убранный из выгрузки заказ не получит отметку о выгрузке и уйдёт в следующей.
• Удалите ключ из product или priceList, чтобы не трогать поле. Так значение, заданное в Medusa Admin, переживёт обмен. Документ заказа уходит в 1С целиком, и удалённый ключ даст в orders.xml пустой узел, поэтому в документе меняйте значения, а не удаляйте их.
• Не добавляйте элементы и не меняйте ключи сопоставления. Товар сопоставляется по Ид 1С до хука, а 1С узнаёт заказ по Ид документа. Плагин проверяет это и останавливает обмен ошибкой с именем хука.
• Возвращайте тот же результат на те же входные данные. Иначе повторный обмен будет каждый раз заново переписывать каталог.

---

Medusa разрешает только один обработчик на хук во всём приложении. Второй, зарегистрированный на тот же хук, остановит запуск сервера с ошибкой Cannot define multiple hook handlers for the setProducts hook. Соберите все правки проекта для одного хука в одном обработчике и вызывайте их внутри него по очереди.

---

Обработчик выполняется внутри шага воркфлоу, и пока он работает, 1С ждёт ответа. setProducts и setPriceLists вызываются на каждую пачку, так что каталог в 10 000 товаров вызовет каждый из них сто раз. Вход и результат хука движок воркфлоу копирует, и всё, что вы допишете в элемент, копируется вместе с ним.

Вот что стоят три вида обработчика setProducts:

Замер сделан на каталоге из 1 000 товаров и 4 000 предложений, то есть на 10 пачках, с локальной PostgreSQL, где запрос стоит около миллисекунды. В таблице медианы трёх прогонов, у запроса на каждый товар один прогон. Повторный импорт почти ничего не пишет, поэтому цена обработчика в нём заметнее всего. На удалённой базе каждый запрос дороже на сетевую задержку, и разница растёт.

Чтобы обработчик не замедлял обмен:

• Делайте один запрос на пачку. Соберите ключи всех элементов, сделайте один query.graph с фильтром по массиву и разложите ответ в Map.
• Не раздувайте элемент. Справочники, которые нужны только обработчику, держите в локальных переменных, а не в элементе.
• Пишите в базу из обработчика только с компенсацией. Вторым аргументом регистрации хука передайте функцию отката, а то, что ей нужно, передайте вторым аргументом StepResponse. Плагин фиксирует пачки по одной, и пачка, завершившаяся ошибкой, откатывает только себя.
• Не завязывайте результат на порядок пачек. После неудачи 1С повторяет обмен целиком, и пачки могут прийти в другом составе.

Запрос на каждый товар выглядит так. На пачку из 100 товаров это 100 запросов:

1for (const item of products) {
2  const [brand] = readProperty(item.source, properties, "Бренд")
3  const { data } = await query.graph({
4    entity: "product_collection",
5    fields: ["id"],
6    filters: { title: brand },
7  })
8  // ...
9}

Один запрос на пачку получает то же самое для всех товаров сразу:

1const titles = products.flatMap(({ source }) => readProperty(source, properties, "Бренд"))
2const { data } = await query.graph({
3  entity: "product_collection",
4  fields: ["id", "title"],
5  filters: { title: titles },
6})
7const collectionIdByTitle = new Map(data.map((collection) => [collection.title, collection.id]))

Полный пример с таким запросом есть на странице Примеры хуков.

Запустите сервер с LOG_LEVEL=debug. Плагин пишет в журнал длительность каждого шага импорта каталога, и шаг хука называется так же, как хук:

[1C Integration] import: import-onec-products › setProducts 35 ms

setPriceLists выполняется внутри дочернего воркфлоу импорта предложений, поэтому его время входит в общую строку import-onec-offers finished in … ms. Выгрузки по шагам в журнал не пишутся.

---