Начало работы с 1С:Предприятие для Medusa

В этом руководстве вы узнаете, как установить плагин 1С:Предприятие, подключить его к Medusa и настроить обмен в 1С.

• Medusa v2.17.2 или новее
• Node.js v22.23.4, v24.22.1, v26.12.1 или новее
• Модуль интеграций v0.1.4 или новее
• Лицензионный ключ Gorgo – подайте заявку на бету
• Конфигурация 1С, которая поддерживает обмен с сайтом по протоколу CommerceML

Пакеты @gorgo-store опубликованы не в общем реестре npm, а в реестре registry.gorgojs.com. Укажите менеджеру пакетов этот реестр для пакетов @gorgo-store и передайте ему лицензионный ключ. Yarn 2 и новее читает настройки из .yarnrc.yml, npm и pnpm из .npmrc:

1npmScopes:
2  gorgo-store:
3    npmRegistryServer: "https://registry.gorgojs.com"
4    npmAuthToken: "${GORGO_LICENSE}"

Для Yarn и npm ключ берётся из переменной окружения GORGO_LICENSE, поэтому сам ключ не попадает в репозиторий проекта. Задайте эту переменную на своей машине и в CI, то есть везде, где устанавливаются зависимости.

Начиная с версии 11.5.3, pnpm не подставляет переменные окружения в адреса реестров и ключи из .npmrc проекта. Поэтому в .npmrc для pnpm указан только адрес реестра, а ключ сохраните в пользовательских настройках pnpm. Выполните эту команду на своей машине и в CI до установки зависимостей:

pnpm config set //registry.gorgojs.com/:_authToken "$GORGO_LICENSE"

Команда записывает ключ в настройки pnpm вашего пользователя, а не в проект, так что в репозиторий он тоже не попадает.

Установите плагин вместе с Модулем интеграций:

yarn add @gorgo/medusa-integration @gorgo-store/medusa-erp-1c

Зарегистрируйте плагин и его провайдер интеграции в medusa-config.ts вашего приложения Medusa:

medusa-config.ts
1// ...
2
3module.exports = defineConfig({
4  // ...
5  plugins: [
6    // ...
7    {
8      resolve: "@gorgo/medusa-integration",
9      options: {
10        providers: [
11          {
12            resolve: "@gorgo-store/medusa-erp-1c/providers/integration-1c",
13            options: {},
14          },
15        ],
16      },
17    },
18    {
19      resolve: "@gorgo-store/medusa-erp-1c",
20      options: {},
21    },
22  ],
23})

Конфигурация регистрирует две вещи:

• Провайдер интеграции в @gorgo/medusa-integration. Благодаря ему настройки 1С появляются в Medusa Admin в Настройки → Интеграции → 1С:Предприятие.
• Сам плагин. Он добавляет адрес обмена для 1С, виджеты панели администратора и воркфлоу обмена.

Модуль интеграций хранит настройки в собственных таблицах. Выполните следующую команду, чтобы применить миграции базы данных:

yarn medusa db:migrate

Обмен запускает сама 1С, поэтому настраивать его нужно на её стороне. В настройках обмена с сайтом в вашей конфигурации 1С укажите:

• Адрес сайта – https://<адрес бэкенда Medusa>/hooks/erp/1c
• Пользователь – email пользователя Medusa Admin
• Пароль – пароль этого пользователя

Плагин проверяет логин и пароль так же, как Medusa Admin при входе. Создайте для обмена отдельного пользователя. Тогда в 1С не будет храниться пароль сотрудника, а этого пользователя можно будет удалить или сменить ему пароль, не затрагивая остальных.

Сжатие и размер частей файла настраивать не нужно. Плагин сам сообщает 1С, что принимает zip-архивы и части файла до 1 МБ. Из полученных файлов он сначала импортирует каталог (import*.xml), затем предложения (offers*.xml) и заказы (orders*.xml).

Плагин узнаёт запись Medusa по Ид из 1С, а не по названию или артикулу:

• Товар – по Ид товара в metadata.onec.id товара Medusa.
• Вариант – по Ид товара и Ид характеристики в metadata.onec.id варианта. Предложение на товар целиком становится вариантом без Ид характеристики.

Поэтому переименование товара или смена артикула в 1С не создают дублей в Medusa.

Артикул предложения плагин записывает в SKU варианта, пока этот SKU не занят другим вариантом. В 1С артикул не обязан быть уникальным, а в Medusa SKU уникален, поэтому вариант с занятым артикулом плагин сохраняет без SKU и пишет об этом в журнал. Сам артикул вариант хранит всегда, в metadata.onec.article, и именно его плагин отправляет в <Артикул> при выгрузке каталога и заказов в 1С. Чтобы заполнять SKU по-своему, используйте хук setVariants, как в примере Свой SKU при занятом артикуле.

Ярлык (handle) нового товара плагин собирает из названия транслитом и части Ид. У Ид в виде GUID это первая группа, другой Ид идёт целиком. Например, товар «Фильтр масляный» с Ид ed1cf3b2-b655-11f1-85e2-fa163e2913c2 получит ярлык filtr-maslyanyj-ed1cf3b2, поэтому у товаров с одинаковым названием ярлыки не совпадают. Ярлык существующего товара плагин не меняет, пока не включена настройка Обновлять ярлык при переименовании товара в 1С, подробнее в разделе Редактирование правил обмена.

Записи обмена в журнале Medusa начинаются с [1C Integration]. После каждой порции каталога и предложений плагин пишет строку прогресса:

[1C Integration] import: progress catalog 40% (200/500 products, batch 2/5)

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

Если артикул предложения уже занят SKU другого варианта, плагин пишет предупреждение:

[1C Integration] import: Offer d4f9a3f0-6e9b-11f0-8be5-fa163e2913c2#7a1f86c0-7355-11f0-8fc6-fa163e2913c2: article "123" is already the SKU of variant variant_01JB2K8R4M, the variant is saved without a SKU and keeps the article in metadata.

Тот же конфликт на следующих обменах плагин пишет на уровне debug, чтобы журнал не повторял одни и те же предупреждения.

Если обмен завершается ошибкой, 1С получает ответ failure с причиной, и та же причина попадает в журнал. Чтобы видеть длительность каждого шага импорта, включите уровень журнала debug, например переменной окружения LOG_LEVEL=debug.