В этом руководстве вы узнаете, как создать провайдер Medusa для управления своими настройками через Модуль интеграций.
Модуль интеграций позволяет любому плагину описывать свои параметры в виде схемы, а администраторам магазина настраивать их в Admin, без правок и без повторного развёртывания приложения Medusa. Он генерирует UI, предоставляет CRUD API и валидацию, поэтому вам не нужно писать свои модели данных, роуты, формы или воркфлоу.
Схема показывает, что вы создадите в этом руководстве и как связаны его части:
регистрирует определение провайдера, то есть файл , который вызывает . Определение объявляет класс сервиса со и . Модуль интеграций превращает дескриптор в страницу в разделе Настройки → Интеграции, где администратор магазина заполняет параметры. Ваш код получает их через .
При разработке своего провайдера Модуля интеграций бывает полезно посмотреть, как устроен готовый провайдер.
Если вам нужен пример реальной реализации, посмотрите провайдер платежей YooKassa в репозитории Medusa Integrations.
Начните с создания новой директории для вашего провайдера Модуля интеграций. Для плагина она размещается в , например .
Если плагина у вас ещё нет, создайте его вместе с проектом-примером командой .
Создайте файл , который объявляет дескриптор провайдера интеграций и сам сервис.

providers/integration-my/services/my-integration.ts1import {2 AbstractIntegrationProviderService3} from "@gorgo/medusa-integration"45class MyIntegrationProvider extends AbstractIntegrationProviderService {6 // TODO add methods7}89export default MyIntegrationProvider
Родительский класс, который вы расширяете здесь, , абстрактный, поэтому подкласс обязан реализовать его свойство (объявленное через ). Классу также нужен : на него рассчитывает загрузчик.
Каждый провайдер Модуля интеграций имеет уникальный идентификатор. По нему администратор настраивает провайдер, а потребитель получает его параметры.
Выберите идентификатор, который не занят другим провайдером. Если два провайдера объявили один идентификатор, модуль при запуске пишет в лог предупреждение с названиями обоих, а начиная с версии 3.0 откажется запускаться.
providers/integration-my/services/my-integration.ts1class MyIntegrationProvider extends AbstractIntegrationProviderService {2 static identifier = "my"3 // ...4}
Загрузчик читает это статическое поле, чтобы собрать ключ, под которым регистрируется ваш инстанс: , либо без ID.
Класс провайдера обязан реализовать свойство . Дескриптор содержит единое описание параметров, их группировку в секции настроек и метод проверки соединения (опционально). Создайте его через .
Общий обзор дескриптора смотрите в разделе Основные концепции. Полный справочник по каждому полю (, , , , , , и другие), по типу, приведён в разделе Дескриптор провайдера интеграций. Какие правила можно объявить, описывает руководство Валидация параметров интеграции, а переводы для i18n-ключей описаны в руководстве Локализация интеграции.
providers/integration-my/services/my-integration.ts1import {2 AbstractIntegrationProviderService,3 defineIntegration,4 z5} from "@gorgo/medusa-integration"67const descriptor = defineIntegration({8 category: "payment",9 displayName: "my.name",10 options: {11 apiKey: {12 type: "string",13 control: "secret",14 secret: true,15 required: true,16 minLength: 1,17 label: "my.apiKey"18 },19 sandbox: {20 type: "boolean",21 control: "switch",22 default: false,23 label: "my.sandbox"24 },25 },26 sections: [27 {28 id: "credentials",29 title: "my.credentials",30 options: ["apiKey", "sandbox"]31 },32 ],33})3435export type MyOptions = z.infer<typeof descriptor.optionsSchema>3637export class MyIntegrationProvider extends AbstractIntegrationProviderService {38 // ...39 get descriptor() {40 return descriptor41 }42}4344export default MyIntegrationProvider
описывает итоговый набор параметров: собирает из объекта , и поскольку у указан , а у задан , оба поля в становятся обязательными.
Обязательный параметр типа принимает и пустую строку, поэтому у указан ещё и . Пустой ключ не проходит проверку, и интеграция остаётся незаполненной, пока администратор не введёт значение. Какие правила можно объявить, описывает руководство Валидация параметров интеграции.
Как и другие провайдеры Medusa, провайдер Модуля интеграций может объявить статический , чтобы проверить свою конфигурацию из уже при загрузке приложения.
providers/integration-my/services/my-integration.ts1class MyIntegrationProvider extends AbstractIntegrationProviderService {2 // ...3 static validateOptions(options: Record<string, unknown>) {4 // необязательная fail-fast проверка options.providers[].options5 }6}
Собственный базового класса ничего не делает (), поэтому переопределять его не обязательно. Тип возврата показывает, что метод либо ничего не возвращает, либо выбрасывает исключение, чтобы прервать загрузку.
На практике у провайдера Модуля интеграций почти всегда . Реальные настройки администратор задаёт в Admin, а не в , поэтому здесь нужен реже, чем у других провайдеров Medusa.
В отличие от , который проверяет конфигурацию провайдера в , проверяет сами параметры интеграции (например, API-ключ), обращаясь к стороннему сервису. Администратор магазина запускает эту проверку из Admin, а запланированная задача раз в сутки заново проверяет каждую включённую интеграцию. Объявите её прямо в дескрипторе.
providers/integration-my/services/my-integration.ts1const descriptor = defineIntegration({2 // ...3 testConnection: async ({ options }) => {4 const res = await fetch("https://api.my.com/ping", {5 headers: { Authorization: `Bearer ${options.apiKey}` },6 })78 return res.ok9 ? { status: "passed" }10 : { status: "failed", message: `My responded with ${res.status}` }11 },12})
принимает одно из значений . Возврат считается обычным результатом, а не ошибкой. Если выбросит исключение, модуль запишет проверку как с текстом ошибки, поэтому администратор магазина увидит результат в Admin в любом случае.
Создайте файл со следующим содержимым:

providers/integration-my/index.ts1import { ModuleProvider } from "@medusajs/framework/utils"2import { INTEGRATION_MODULE } from "@gorgo/medusa-integration"3import MyIntegrationProvider from "./services/my-integration"45export default ModuleProvider(INTEGRATION_MODULE, {6 services: [MyIntegrationProvider],7})
Это экспортирует определение провайдера, указывая, что является его сервисом.
Чтобы использовать провайдер Модуля интеграций, добавьте его в массив модуля интеграций в и укажите сам плагин в . Замените на из вашего плагина:
medusa-config.ts1module.exports = defineConfig({2 // ...3 plugins: [4 {5 resolve: "@gorgo/medusa-integration",6 options: {7 encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,8 providers: [9 {10 resolve: "<your-plugin-package>/providers/integration-my",11 options: {},12 },13 ],14 },15 },16 {17 resolve: "<your-plugin-package>",18 options: {},19 },20 // ...21 ],22})
По записи в загрузчик создаёт инстанс . Её состоит из имени пакета плагина и пути к провайдеру, , и опирается на экспорт в плагина.
Вторая запись указывает сам плагин. Medusa загружает расширения Admin из плагина, такие как переводы и виджеты, только для пакетов из . Без этой записи провайдер всё равно регистрируется, но Admin не загрузит переводы плагина, и на странице интеграции вместо читаемых текстов появятся ключи вроде .
Такое значение подходит для провайдера в плагине. Провайдер, который находится в самом приложении Medusa, регистрируется по пути от директории приложения, например , и записи в не требует. Medusa ищет относительный путь от директории приложения, поэтому тот же путь не сработает для провайдера в плагине.
Пока у провайдера один инстанс, не указывайте, как в примере выше. Тогда провайдер регистрируется под ключом , то есть , а потребитель получает его параметры с . Добавляйте , только если регистрируете провайдер несколько раз, по одному на инстанс. Ключ тогда принимает вид , например , и потребитель должен передать то же значение как . Иначе бросит исключение, потому что под ключом ничего не зарегистрировано. Подробнее об инстансах читайте в разделе Инстансы и их идентификаторы.
Далее добавьте секретный ключ шифрования в переменные окружения. Модуль интеграций использует его, чтобы зашифровать секреты перед сохранением в базу данных:
.envINTEGRATION_ENCRYPTION_KEY=supersecret
Подходит любое непустое значение. Модуль преобразует его через SHA-256 в 32-байтовый ключ AES-256-GCM, поэтому используйте значение с высокой энтропией, например .
Запустите сервер и откройте Настройки → Интеграции в Medusa Admin. Интеграция появится в списке. Заполните параметры, затем выберите Проверить соединение в меню действий у названия интеграции, чтобы вызвать .
Чтобы прочитать сохранённые параметры, используйте , передав тот же , который объявляет ваш класс провайдера:
providers/payment-my/services/my-payment.ts1import { resolveIntegrationOptions } from "@gorgo/medusa-integration"2import type { MyOptions } from "../../integration-my/services/my-integration"34const options = await resolveIntegrationOptions<MyOptions>({5 identifier: "my",6})
Возвращённые типизированы как , уже расшифрованные и проверенные. По умолчанию вызов выбрасывает , если интеграция не настроена, выключена или не заполнена.
Подробнее о том, как получить параметры интеграции из роута, подписчика или шага воркфлоу, читайте в разделе Чтение параметров.