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

В интеграции участвуют две роли разработчика, а между ними находится администратор магазина.

• Провайдер интеграции. Объявляет интеграцию. Описывает опции, их группировку и валидацию, а также необязательную проверку соединения. Провайдером интеграции может быть любой плагин, провайдер или кастомный модуль, и всё это он объявляет в одном дескрипторе.
• Администратор магазина. Настраивает эти опции в админке как интеграцию: например, учётные данные, режимы или вебхуки. Без правок medusa-config и без редеплоя.
• Потребитель. Читает резолвнутые опции в рантайме.

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

Дескриптор: единое объявление метаданных интеграции, её опций, секций настроек, валидации и необязательной проверки соединения. Создаётся он через defineIntegration.

Например:

providers/integration-acme/services/acme-integration.ts
1import { defineIntegration, AbstractIntegrationProvider } from "@gorgo/medusa-integration"
2
3const descriptor = defineIntegration({
4  category: "payment",
5  displayName: "acme.name",
6  options: {
7    apiKey:  {
8      type: "string",
9      control: "secret",
10      secret: true,
11      required: true,
12      label: "acme.apiKey"
13    },
14    sandbox: {
15      type: "boolean",
16      control: "switch",
17      default: false,
18      label: "acme.sandbox"
19    },
20  },
21  sections: [
22    {
23      id: "credentials",
24      title: "acme.credentials",
25      options: ["apiKey", "sandbox"]
26    },
27  ],
28})
29
30export class AcmeIntegration extends AbstractIntegrationProvider {
31  static identifier = "acme"
32
33  get descriptor() {
34    return descriptor
35  }
36}

Дескриптор служит единым источником истины для интеграции. По нему модуль генерирует admin CRUD API, валидирует запись, рендерит UI настроек и определяет, что потребители получают в рантайме. Вам не нужно писать ни модели данных, ни роуты, ни формы.

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

• Любой тип провайдера: платежи, доставка, ERP, уведомления, контент и не только.
• Плагины: добавляйте плагину настраиваемые опции, не строя страницу настроек и слой данных.
• Кастомные модули и доработки админки: любой модуль Medusa, которому нужны настраиваемые из админки опции: API-ключи, режимы или фиче-флаги.

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

У каждой интеграции есть стабильный идентификатор, например acme, заданный как static identifier провайдера. Каждая регистрация адресуется по provider_id вида:

int_<identifier>[_<instanceId>]

• Один инстанс: вариант по умолчанию. У него нет id инстанса, поэтому его ключ выглядит как int_acme.
• Несколько инстансов: зарегистрируйте один и тот же провайдер несколько раз, каждый со своим id, например int_acme_eu и int_acme_us. Каждый инстанс настраивается независимо, поэтому поддерживается сразу несколько аккаунтов.

Потребитель получает опции по идентификатору и инстансу, поэтому один и тот же код может обращаться к нужному.

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

Модуль генерирует admin CRUD API из дескриптора и валидирует каждую запись. Валидация покрывает правила на уровне отдельной опции (типы, диапазоны, паттерны) вместе с правилами между секциями, охватывающими всю конфигурацию. Ничего писать под каждую интеграцию не нужно.

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

Опции с пометкой secret шифруются при хранении алгоритмом AES-256-GCM и никогда не попадают в браузер. Admin API маскирует их и сообщает лишь, задано значение или нет. Сохранение секрета пустым оставляет прежнее хранимое значение, а не стирает его.

Дескриптор может объявить необязательную проверку соединения, которая сверяет учётные данные со сторонним сервисом. Администраторы запускают её по требованию, а запланированная задача периодически перепроверяет настроенные интеграции.

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

Модуль генерирует админ-интерфейс интеграции из её дескриптора, поэтому строить страницы не нужно.

Опции группируются в секции настроек и рендерятся через LayoutComposer Medusa в виде карточек с изменяемым порядком, в одну или две колонки.

Когда сгенерированного Admin UI недостаточно, вы можете построить для своих опций любой интерфейс на кастомных admin-виджетах. Это обычные admin-виджеты Medusa на том же механизме defineWidgetConfig и зон внедрения, что вы уже используете в других местах, так что учить ничего нового не придётся. Модуль предоставляет зоны внедрения на странице каждой интеграции (например, gorgo.integration.<identifier>.main.after), и виджет, нацеленный на такую зону, получает готовый providerId и напрямую читает и пишет опции интеграции.

Метки, подсказки и заголовки в дескрипторе задаются как i18n-ключи. Поставляйте переводы вместе со своей интеграцией, и UI настроек локализуется автоматически.

Всё это построено на стандартном admin i18n Medusa, так что учить ничего нового не нужно. Регистрируйте переводы привычным способом, и ключи резолвятся по активному языку админки с откатом на английский, если ключ отсутствует. Кастомные виджеты локализуются так же, используя тот же каталог сообщений, что и сгенерированная форма.

• Чтение опций
• Перенос провайдера на модуль интеграций
• Руководство администратора