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

---

Хук воркфлоу importOnecProductsWorkflow (import-onec-products). Вызывается на каждую пачку каталога, до 100 товаров, до сравнения с товарами Medusa. Каталог в 10 000 товаров вызовет его 100 раз.

src/workflows/hooks/onec-catalog.ts
1import { StepResponse } from "@medusajs/framework/workflows-sdk"
2import { importOnecProductsWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"
3
4importOnecProductsWorkflow.hooks.setProducts(async ({ products, properties }, { container }) => {
5  // ...
6
7  return new StepResponse({ products })
8})

Обработчик получает товары пачки и свойства классификатора:

В product обмен записывает title, description, handle, external_id, type_id, status, metadata, category_ids и sales_channels, а thumbnail и images только когда 1С прислала картинки. Поля subtitle, weight, length, height, width, origin_country, hs_code, mid_code, material, collection_id и discountable обмен не заполняет. Их может задать обработчик, и импорт запишет их так же, как остальные.

Верните new StepResponse({ products }). Обработчик может поправить product и убрать товар из пачки. Чего он сделать не может:

• вернуть товар, которого не было в пачке, или один товар дважды;
• поменять existing;
• удалить или поменять external_id и metadata.onec.id у нового товара, потому что без них следующий обмен заведёт товар заново;
• поменять external_id и metadata.onec.id у существующего товара. Удалить эти ключи можно, тогда поля останутся как есть.

После хука плагин сравнивает product с existing и пишет только поля, которые отличаются. Товар без existing он создаёт. Убранный из пачки товар в этом обмене не создаётся и не обновляется.

---

Хук воркфлоу importOnecPricesWorkflow (import-onec-prices). Воркфлоу запускается внутри импорта предложений, поэтому хук вызывается на каждую пачку предложений, до 100 товаров со всеми их предложениями, до сверки с Medusa.

src/workflows/hooks/onec-prices.ts
1import { StepResponse } from "@medusajs/framework/workflows-sdk"
2import { importOnecPricesWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"
3
4importOnecPricesWorkflow.hooks.setPriceLists(async ({ priceLists }, { container }) => {
5  // ...
6
7  return new StepResponse({ priceLists })
8})

Обработчик получает по элементу на каждый нерозничный тип цен из offers.xml. Розничный тип плагин пишет в цену варианта, и в хук он не попадает:

Верните new StepResponse({ priceLists }). Ключ, который обработчик добавит в priceList, например rules или status, импорт запишет, если он отличается от записанного. Ограничения такие:

• нельзя вернуть тип цен, которого не было в пачке, или один тип дважды;
• нельзя поменять existing;
• цена должна относиться к варианту из этой пачки, amount должен быть числом, и двух цен в одной валюте у варианта быть не может.

После хука плагин создаёт прайс-листы новых типов цен и помечает их metadata.onec.price_type_id. У существующих он пишет изменившиеся ключи priceList и сверяет цены по варианту и валюте, добавляя новые, обновляя изменившиеся и удаляя лишние. Убранный из списка тип цен в этой пачке не трогается вовсе, ни прайс-лист, ни его цены.

---

Хук воркфлоу exportOnecOrdersWorkflow (export-onec-orders). Вызывается один раз на выгрузку заказов в 1С, до сборки XML. В выгрузку попадают неотменённые заказы, которые ещё не выгружались и не пришли из 1С.

src/workflows/hooks/onec-orders.ts
1import { StepResponse } from "@medusajs/framework/workflows-sdk"
2import { exportOnecOrdersWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"
3
4exportOnecOrdersWorkflow.hooks.setOrders(async ({ orders }, { container }) => {
5  // ...
6
7  return new StepResponse({ orders })
8})

Обработчик получает каждый заказ вместе с документом CommerceML, которым тот уйдёт в 1С:

У документа есть и поля date, time, operation, role, currency, rate и sum. Их тоже можно поправить, они уходят в XML как есть.

Верните new StepResponse({ orders }). Обработчик может поправить document и убрать заказ из выгрузки. Вернуть заказ, которого в выгрузке не было, вернуть заказ дважды или поменять document.id нельзя.

После хука плагин собирает из документов orders.xml и отдаёт его 1С. Отметку о выгрузке заказы получают, только когда 1С подтвердит приём. Убранный из выгрузки заказ отметку не получит и попадёт в следующую выгрузку.

---

Хук есть у двух воркфлоу, exportOnecCatalogWorkflow (export-onec-catalog) и exportOnecOrdersWorkflow (export-onec-orders). Вызывается один раз на выгрузку, когда XML уже собран. У выгрузки заказов он идёт после setOrders. Это резервный способ для того, чего нет в модели товара или документа, например для версии схемы, которую ждёт ваша конфигурация 1С.

src/workflows/hooks/onec-payload.ts
1import { StepResponse } from "@medusajs/framework/workflows-sdk"
2import { exportOnecCatalogWorkflow, exportOnecOrdersWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"
3
4exportOnecCatalogWorkflow.hooks.setPayload(async ({ payload }) => {
5  // ...
6
7  return new StepResponse({ payload })
8})
9
10exportOnecOrdersWorkflow.hooks.setPayload(async ({ payload }) => {
11  // ...
12
13  return new StepResponse({ payload })
14})

Это два разных хука, и каждый регистрируется у своего воркфлоу. Обработчик получает XML строкой:

Верните new StepResponse({ payload }) со строкой. Без обработчика в 1С уходит XML плагина. Какие заказы получат отметку о выгрузке, решает setOrders, а не этот хук.

---

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

readRequisite(source, name): string | undefined

Первое значение реквизита из ЗначенияРеквизитов по его Наименованию. Имя сравнивается точно, с пробелами и регистром. У 1С это свободный текст, и Полное наименование с ПолноеНаименование разные реквизиты. Если реквизита нет, функция вернёт undefined.

readProperty(source, properties, nameOrId): string[]

Значения свойства из ЗначенияСвойств. Свойство ищется по Ид или по имени, а значения-справочники разворачиваются через properties из входных данных хука. По имени собираются все одноимённые свойства, потому что 1С может завести своё свойство «Бренд» под каждую категорию. Если значения нет, функция вернёт пустой массив.

---