Command Palette

Search for a command to run...

Дескриптор провайдера интеграций

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

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

defineIntegration

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

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

Этот дескриптор объявляет и , сгруппированные в одну секцию . сразу выбрасывает ошибку при загрузке в двух случаях: если секция ссылается на id параметра, которого нет в , и если параметра типа смешивает строки и числа.


Свойства дескриптора

принимает следующие свойства:

Loading...

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


Секции

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

Loading...

Поля параметра

Каждый параметр в представляет собой объект вида . Поле определяет доступные значения и остальные поля, общие для всех типов:

Loading...

Дополнительные поля по типу параметра

У некоторых типов есть свои поля сверх общих:

  • : , ,
  • :
  • : , , , , ,
  • : ,
Loading...

Сгенерированный CRUD и валидация

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

Когда срабатывает каждое правило и как тестировать правила дескриптора, читайте в руководстве Валидация параметров интеграции, а сгенерированные роуты описаны в справочнике API-роуты Admin.


Включена и заполнена

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


Секреты и шифрование

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

Внимание: 

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

Значения секретных параметров не попадают и в историю изменений. Для них история показывает только, что значение задано, заменено или удалено. Значения остальных параметров она хранит как есть.

Внимание: 

Параметр с учётными данными без пометки показывается в Admin и хранится в истории изменений открытым текстом. При запуске модуль пишет в лог предупреждение о каждом параметре, название которого похоже на учётные данные, но не помечено . Предупреждение пишется один раз на идентификатор провайдера, даже если провайдер зарегистрирован несколько раз. Похожим считается название, в котором без учёта регистра встречается , , , , или . и совпадают и с подчёркиванием или дефисом между словами, например или . Совпадение ищется внутри названия, поэтому подходят и , а и не подходят.

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

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

Ошибка остаётся в одном случае. Модуль считает сохранённую строку зашифрованной, если она начинается с или похожа на значение, зашифрованное версией модуля 0.x. Такое значение записано в стандартном base64 (, , , , и для выравнивания), длиной не меньше 40 символов и кратной 4, а после декодирования занимает не меньше 29 байт. Значение открытым текстом такого вида в параметре, который вы только что пометили , не расшифруется, и чтение интеграции завершится ошибкой, описанной в разделе Параметры Модуля интеграций. Чтобы восстановить работу, удалите сохранённые настройки через роут и введите их заново. Чтобы этого избежать, решите, секретный ли параметр, до того как администратор магазина сохранит его значение.

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


Проверка соединения

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

Добавьте в дескриптор. Он получает уже итоговые (расшифрованные) параметры и возвращает статус:

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 if (!res.ok) {
9 return { status: "failed", message: `My responded with ${res.status}` }
10 }
11
12 return { status: "passed" }
13 },
14})

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

Если статус не , Admin показывает в уведомлении, а при отсутствии сообщения сам статус. Результат всегда показывает одно и то же уведомление об успехе, что бы ни содержало .

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


Получение параметров во время выполнения

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


Списки значений между версиями

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

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

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

Материалы

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