Command Palette

Search for a command to run...

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

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

Что такое Модуль интеграций? 

Модуль интеграций позволяет любому плагину описывать свои параметры в виде схемы, а администраторам магазина настраивать их в Admin, без правок и без повторного развёртывания приложения Medusa. Он генерирует UI, предоставляет CRUD API и валидацию, поэтому вам не нужно писать свои модели данных, роуты, формы или воркфлоу.

Схема показывает, что вы создадите в этом руководстве и как связаны его части:

регистрирует определение провайдера, то есть файл , который вызывает . Определение объявляет класс сервиса со и . Модуль интеграций превращает дескриптор в страницу в разделе Настройки → Интеграции, где администратор магазина заполняет параметры. Ваш код получает их через .

Пример реализации

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

Если вам нужен пример реальной реализации, посмотрите провайдер платежей YooKassa в репозитории Medusa Integrations.


1. Создайте директорию провайдера

Начните с создания новой директории для вашего провайдера Модуля интеграций. Для плагина она размещается в , например .

Если плагина у вас ещё нет, создайте его вместе с проектом-примером командой .


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

Создайте файл , который объявляет дескриптор провайдера интеграций и сам сервис.

Структура проекта плагина Medusa после создания файла сервиса

providers/integration-my/services/my-integration.ts
1import {
2 AbstractIntegrationProviderService
3} from "@gorgo/medusa-integration"
4
5class MyIntegrationProvider extends AbstractIntegrationProviderService {
6 // TODO add methods
7}
8
9export default MyIntegrationProvider

Родительский класс, который вы расширяете здесь, , абстрактный, поэтому подкласс обязан реализовать его свойство (объявленное через ). Классу также нужен : на него рассчитывает загрузчик.

identifier

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

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

Пример

providers/integration-my/services/my-integration.ts
1class MyIntegrationProvider extends AbstractIntegrationProviderService {
2 static identifier = "my"
3 // ...
4}

Загрузчик читает это статическое поле, чтобы собрать ключ, под которым регистрируется ваш инстанс: , либо без ID.

descriptor

Класс провайдера обязан реализовать свойство . Дескриптор содержит единое описание параметров, их группировку в секции настроек и метод проверки соединения (опционально). Создайте его через .

Общий обзор дескриптора смотрите в разделе Основные концепции. Полный справочник по каждому полю (, , , , , , и другие), по типу, приведён в разделе Дескриптор провайдера интеграций. Какие правила можно объявить, описывает руководство Валидация параметров интеграции, а переводы для i18n-ключей описаны в руководстве Локализация интеграции.

Пример

providers/integration-my/services/my-integration.ts
1import {
2 AbstractIntegrationProviderService,
3 defineIntegration,
4 z
5} from "@gorgo/medusa-integration"
6
7const 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})
34
35export type MyOptions = z.infer<typeof descriptor.optionsSchema>
36
37export class MyIntegrationProvider extends AbstractIntegrationProviderService {
38 // ...
39 get descriptor() {
40 return descriptor
41 }
42}
43
44export default MyIntegrationProvider

описывает итоговый набор параметров: собирает из объекта , и поскольку у указан , а у задан , оба поля в становятся обязательными.

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

validateOptions

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

Пример

providers/integration-my/services/my-integration.ts
1class MyIntegrationProvider extends AbstractIntegrationProviderService {
2 // ...
3 static validateOptions(options: Record<string, unknown>) {
4 // необязательная fail-fast проверка options.providers[].options
5 }
6}

Собственный базового класса ничего не делает (), поэтому переопределять его не обязательно. Тип возврата показывает, что метод либо ничего не возвращает, либо выбрасывает исключение, чтобы прервать загрузку.

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

testConnection

В отличие от , который проверяет конфигурацию провайдера в , проверяет сами параметры интеграции (например, API-ключ), обращаясь к стороннему сервису. Администратор магазина запускает эту проверку из Admin, а запланированная задача раз в сутки заново проверяет каждую включённую интеграцию. Объявите её прямо в дескрипторе.

Пример

providers/integration-my/services/my-integration.ts
1const descriptor = defineIntegration({
2 // ...
3 testConnection: async ({ options }) => {
4 const res = await fetch("https://api.my.com/ping", {
5 headers: { Authorization: `Bearer ${options.apiKey}` },
6 })
7
8 return res.ok
9 ? { status: "passed" }
10 : { status: "failed", message: `My responded with ${res.status}` }
11 },
12})

принимает одно из значений . Возврат считается обычным результатом, а не ошибкой. Если выбросит исключение, модуль запишет проверку как с текстом ошибки, поэтому администратор магазина увидит результат в Admin в любом случае.


3. Создайте файл определения модуля провайдера

Создайте файл со следующим содержимым:

Структура проекта плагина Medusa после создания файла с определением провайдера

providers/integration-my/index.ts
1import { ModuleProvider } from "@medusajs/framework/utils"
2import { INTEGRATION_MODULE } from "@gorgo/medusa-integration"
3import MyIntegrationProvider from "./services/my-integration"
4
5export default ModuleProvider(INTEGRATION_MODULE, {
6 services: [MyIntegrationProvider],
7})

Это экспортирует определение провайдера, указывая, что является его сервисом.


4. Подключите провайдер

Чтобы использовать провайдер Модуля интеграций, добавьте его в массив модуля интеграций в и укажите сам плагин в . Замените на из вашего плагина:

medusa-config.ts
1module.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 ищет относительный путь от директории приложения, поэтому тот же путь не сработает для провайдера в плагине.

Внимание: 

Пока у провайдера один инстанс, не указывайте, как в примере выше. Тогда провайдер регистрируется под ключом , то есть , а потребитель получает его параметры с . Добавляйте , только если регистрируете провайдер несколько раз, по одному на инстанс. Ключ тогда принимает вид , например , и потребитель должен передать то же значение как . Иначе бросит исключение, потому что под ключом ничего не зарегистрировано. Подробнее об инстансах читайте в разделе Инстансы и их идентификаторы.

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

.env
INTEGRATION_ENCRYPTION_KEY=supersecret

Подходит любое непустое значение. Модуль преобразует его через SHA-256 в 32-байтовый ключ AES-256-GCM, поэтому используйте значение с высокой энтропией, например .


5. Протестируйте

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

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

providers/payment-my/services/my-payment.ts
1import { resolveIntegrationOptions } from "@gorgo/medusa-integration"
2import type { MyOptions } from "../../integration-my/services/my-integration"
3
4const options = await resolveIntegrationOptions<MyOptions>({
5 identifier: "my",
6})

Возвращённые типизированы как , уже расшифрованные и проверенные. По умолчанию вызов выбрасывает , если интеграция не настроена, выключена или не заполнена.

Подробнее о том, как получить параметры интеграции из роута, подписчика или шага воркфлоу, читайте в разделе Чтение параметров.

Материалы

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