Command Palette

Search for a command to run...

Провайдер Модуля интеграций

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

Что такое провайдер Модуля интеграций

Провайдер Модуля интеграций объявляет интеграцию: её параметры, их группировку в секции настроек и необязательную проверку соединения. Администратор магазина настраивает её в Admin, без правок и без повторного развёртывания.

Модуль интеграций не зависит от типа провайдера, поэтому, в отличие от встроенных коммерческих модулей Medusa, он не поставляется с провайдером по умолчанию или провайдером-заглушкой. Провайдером Модуля интеграций может быть любой плагин, провайдер или собственный модуль. Полный список сценариев смотрите в разделе Где можно применять Модуль интеграций.

Каждый провайдер, зарегистрированный в параметре Модуля интеграций, представлен в базе данных моделью данных .


Создание собственного провайдера Модуля интеграций

Провайдер Модуля интеграций представляет собой модуль, чей сервис расширяет , импортированный из . Как и у других провайдеров Medusa, один модуль может регистрировать несколько сервисов провайдера Модуля интеграций, каждый со своим , и каждый становится отдельным провайдером.

объявляет следующие члены класса:

Вот минимальная форма провайдера со всеми членами класса из таблицы выше, кроме тех, что уже реализует базовый класс:

providers/integration-my/services/my-integration.ts
1import { AbstractIntegrationProviderService } from "@gorgo/medusa-integration"
2
3class MyIntegrationProvider extends AbstractIntegrationProviderService {
4 static identifier = "my"
5
6 static validateOptions(options: Record<string, unknown>) {
7 // необязательная fail-fast проверка
8 }
9
10 get descriptor() {
11 return descriptor
12 }
13}
14
15export default MyIntegrationProvider

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

Если у подкласса есть собственный конструктор, он должен передать в все три аргумента, , и . Иначе вернёт , даже для именованного инстанса.

Прежнее имя было . Пакет по-прежнему экспортирует его как устаревший алиас, сохранит во всех версиях 2.x и удалит в версии 3.0.

Полный пошаговый пример с кодом смотрите в разделе Как создать провайдер Модуля интеграций.


Регистрация провайдеров Модуля интеграций

Настройка провайдеров Модуля интеграций

Модуль интеграций принимает параметр , в котором вы настраиваете провайдеры, зарегистрированные в вашем приложении, а также параметр , используемый для секретных полей модуля. Точную структуру смотрите в шаге 4 руководства «Как создать провайдер Модуля интеграций».

Регистрация при старте приложения

При старте приложения Medusa Модуль интеграций регистрирует каждый провайдер из параметра . Сначала Medusa проверяет и каждой записи. Затем модуль вызывает провайдера с записи и объединяет класса с записи в ключ . Это тот же формат, что используется для этого инстанса в базе данных. Модуль регистрирует провайдер в своём контейнере под этим ключом, а контейнер создаёт инстанс через .

Для каждой записи шаги идут в таком порядке:

Если проверка или не проходит, приложение останавливается при старте, и неверная запись до ключа не доходит. Запись, прошедшая проверки, становится инстансом в контейнере модуля, а Admin показывает каждый зарегистрированный инстанс, настроенный или нет, в разделе Настройки → Интеграции.

Зарегистрировав все провайдеры, модуль пишет в лог предупреждение о каждом параметре, название которого похоже на учётные данные, но который не помечен . Как модуль обращается с секретами, описано на странице Дескриптор провайдера интеграций.

Ошибки регистрации

Medusa останавливает приложение при старте, если запись в нарушает одно из этих правил, и ошибка называет проблему:

  • У двух записей одинаковые идентификатор и , в том числе у двух записей без . В этом случае Medusa выводит ошибку , где вместо стоит идентификатор.
  • У класса сервиса нет . В этом случае Medusa выводит ошибку , где берётся из сервиса или, если его нет, из пути к модулю провайдера.
  • Экспорт по умолчанию модуля провайдера не содержит ни одного сервиса. В этом случае Medusa выводит ошибку , где это значение записи.

Чтобы избежать первой ошибки, задайте каждому инстансу провайдера собственный . Как образует ключ, описано на странице Основные концепции.

Модель данных

Инстанс зарегистрированного провайдера Модуля интеграций представлен в приложении Medusa моделью данных .

Внимание: 

Собственный модели служит лишь её внутренним идентификатором записи, таким же, как у любой другой модели данных Medusa. Это не то же самое, что , поле, которое хранит ключ из раздела Инстансы и их идентификаторы.

Запись хранит инстанса, его , настройки администратора магазина в с зашифрованными секретными параметрами, флаг и результат последней проверки соединения. Модуль создаёт запись при первом сохранении любой секции, поэтому зарегистрированный провайдер без записи показывается в Admin как Не настроено. Все свойства модели перечислены в справочнике Модели данных Модуля интеграций.

История изменений инстанса хранится в отдельной модели данных , которая не связана с и переживает её. Подробнее на странице История изменений настроек.

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

Вы можете удалить зарегистрированный провайдер Модуля интеграций, удалив его запись из параметра в . В отличие от отключения интеграции из Admin, это не затрагивает сохранённую запись. Провайдер перестаёт регистрироваться, поэтому модуль больше не может найти его запись по . Интеграция исчезает из списка в Admin, а её сохранённые данные становятся недоступны через собственные admin-роуты Модуля интеграций. Её записи остаются в истории изменений всех интеграций.

Внимание: 

Удалите интеграцию из Admin, прежде чем убирать провайдер из , а не наоборот. Как только провайдер исчезает из конфигурации, его запись становится недостижима, в том числе через сам роут удаления, и остаётся в базе данных без возможности удалить её из Admin. Обычный порядок удаления описан в разделе Удаление интеграции.

То же происходит, если изменить записи или класса, потому что меняется ключ . У нового ключа нет сохранённой записи , поэтому инстанс показывается как Не настроено, а настройки остаются в базе данных под старым ключом, недоступные из Admin. Есть два выхода:

  • Верните старую запись, удалите интеграцию из Admin и только потом уберите запись или замените её на новый.
  • Запустите из своего кода, передав старый ключ как . Ему не нужно, чтобы провайдер был зарегистрирован, поэтому он удалит настройки, хранящиеся под этим ключом, а интеграцию можно будет настроить заново под новым.

Входные данные воркфлоу и путь импорта описаны на странице Воркфлоу Модуля интеграций.

Чтобы временно прекратить использование провайдера, сохранив его настройки и возможность быстро вернуть его обратно, отключите интеграцию из Admin вместо удаления провайдера из . Как это сделать, описано на странице Управление интеграциями в Medusa Admin.

Материалы

Изменено 12 ноября 2026 г.·Редактировать страницу