В этом справочнике перечислены API-роуты, которые Модуль интеграций добавляет в /admin/integrations. Medusa Admin пользуется ими на всех страницах интеграций, а ваши скрипты и собственные виджеты тоже могут ими пользоваться.

Как и любые роуты Medusa в /admin, они требуют аутентифицированного пользователя Admin или секретный ключ API. Роут с :provider_id отвечает 404 с типом not_found и сообщением Unknown integration "<id>", если под этим ключом не зарегистрирован ни один провайдер.

Роуты, которые принимают тело или параметры запроса, проверяют их строго. На неизвестный ключ или значение вне допустимого диапазона они отвечают 400 с сообщением, которое начинается с Invalid request. Тело проверяется раньше провайдера, поэтому на неверное тело для неизвестного провайдера роут тоже отвечает 400.

Роуты, которые меняют настройки, передают в воркфлоу аутентифицированного автора, а также IP-адрес, клиент и ID запроса, чтобы в истории изменений был указан автор.

GET /admin/integrations принимает такие параметры запроса:

• q – ищет по идентификатору провайдера или инстанса. Переведённые названия Admin ищет на своей стороне.
• category – одна категория, например payment.
• limit – от 1 до 1000, по умолчанию 20.
• offset – по умолчанию 0.

Роут возвращает { integrations, count, limit, offset, categories }. Каждый элемент integrations содержит provider_id, identifier, instance_id и category инстанса, i18n-ключи display_name и description, icon, данные пакета version, author и author_url, флаги has_test_connection, is_configured, is_enabled и is_complete, а также last_test_status. categories перечисляет категории всех зарегистрированных инстансов независимо от фильтров.

POST /admin/integrations/:provider_id принимает тело с такими полями:

• values – необязательный. Значения параметров для сохранения, где ключом служит идентификатор параметра. Без него параметры не записываются, например когда вы меняете только metadata.
• section_id – необязательный. С ним записываются только параметры этой секции. Без него записываются все отправленные ключи, которые объявлены в дескрипторе.
• title – необязательный. Название сохранённой записи или null, чтобы очистить его.
• metadata – необязательный. Объединяется с сохранёнными метаданными по ключам, как у любой сущности Medusa. Ключ со значением в виде пустой строки удаляется, а null очищает метаданные. Метаданные не относятся к настройкам, поэтому история изменений их не показывает.

Например, чтобы сохранить секцию с учётными данными интеграции int_my:

1curl -X POST "http://localhost:9000/admin/integrations/int_my" \
2  -H "Authorization: Bearer {token}" \
3  -H "Content-Type: application/json" \
4  --data '{ "section_id": "credentials", "values": { "apiKey": "sk_test_123", "sandbox": true } }'

В ответ приходит { integration }, сохранённая запись без секретов. apiKey из запроса упоминается в ней только по имени, в configured_secrets. Если значение не проходит валидацию, роут отвечает 400, а в сообщении каждая проблема записана как <идентификатор параметра>: <сообщение>. На неизвестный section_id роут тоже отвечает 400 с типом invalid_data и сообщением Unknown section "<id>".

POST /admin/integrations/:provider_id/enable принимает тело { is_enabled } с обязательным булевым полем is_enabled и возвращает { integration }. Для зарегистрированного провайдера, у которого ещё ничего не сохранено, роут отвечает 404 с типом not_found и сообщением Integration "<id>" is not configured. Если установить состояние, в котором интеграция уже находится, роут ответит 200 и ничего не запишет в историю изменений.

DELETE /admin/integrations/:provider_id не принимает тело и возвращает { id, object: "integration", deleted: true }, где id содержит ключ инстанса. Роут отвечает 200, даже если ничего не было сохранено.

POST /admin/integrations/:provider_id/test-connection не принимает тело и для зарегистрированного провайдера всегда отвечает 200 с { status, message? }, где status равно passed, failed или skipped. Для интеграции, которая не настроена, выключена или не завершена, роут возвращает failed с сообщением Not configured, а если тест выбросил ошибку, то failed с сообщением этой ошибки. Если в дескрипторе нет проверки соединения, результат skipped с сообщением No test configured.

GET /admin/integrations/:provider_id, POST /admin/integrations/:provider_id и роут enable возвращают сохранённую запись в таком виде. Значения секретов сервер никогда не отдаёт.

Medusa Admin показывает этот объект в секции JSON на странице интеграции.

GET /admin/integrations/:provider_id оборачивает её в { descriptor, integration, is_complete, version, author, author_url }. integration равно null до первого сохранения, а descriptor содержит дескриптор, подготовленный для Admin, с секциями, полями и раскладкой.

---

История доступна только для чтения, и эти роуты принимают только GET. POST или DELETE на /admin/integrations/changes попадает в роуты с :provider_id, которые воспринимают changes как ключ инстанса и отвечают 404 (400 для POST с неверным телом).

Оба роута со списком принимают такие параметры запроса:

• fields – список полей через запятую, которые нужно вернуть. Роуты со списком не возвращают ip, user_agent и request_id, пока вы не запросите их.
• limit – от 1 до 100, по умолчанию 20.
• offset – по умолчанию 0.
• order – поле для сортировки, с - впереди для обратного порядка. По умолчанию -created_at.
• provider_id – один или несколько ключей инстансов. Роут одной интеграции его игнорирует.
• change_type – одно или несколько значений из created, updated, enabled, disabled и deleted.
• actor_id – один или несколько идентификаторов пользователей. system обозначает все изменения, сделанные не пользователем Admin.
• created_at – диапазон дат с операторами вроде $gte и $lte.
• q – ищет по email автора или названию ключа API и по provider_id.
• q_fields, q_providers – вместе с q находят ещё и изменения, которые затронули один из этих идентификаторов или ключей меток параметров или относятся к одному из этих инстансов. Admin заполняет их тем, что совпало с q в переведённых названиях.

Роуты возвращают { integration_changes, count, offset, limit }, по умолчанию сначала новые.

GET /admin/integrations/changes/:id возвращает { integration_change }, одно изменение со всеми полями, включая ip, user_agent и request_id. Роут принимает fields и отвечает 404 для неизвестного идентификатора.

GET /admin/integrations/changes/actors возвращает { users, system }. Каждый элемент users имеет вид { id, label }, а список отсортирован по label. В label попадает текущее имя пользователя, а если его нет, то текущий email, затем email, сохранённый с изменениями пользователя, а иначе null. system равно true, если какое-либо изменение сделал не пользователь Admin, а, например, ключ API или код, выполненный без запроса.

GET /admin/integrations/changes/fields возвращает { fields }, по одному { field, label } на каждую пару идентификатора параметра и ключа метки, которые упоминаются в истории, включая параметры и интеграции, которых уже нет. field содержит идентификатор параметра или @title для названия записи, а label содержит ключ метки, сохранённый вместе с изменением, или null.

Все роуты сверяют diff с текущим дескриптором. Значение параметра, который стал секретным после записи изменения, возвращается как { secret: true, op: "hidden" }. Изменения провайдера, который больше не зарегистрирован, возвращаются в том виде, в каком были сохранены.

---

GET /admin/integrations/catalog возвращает { integrations }. Каждый элемент является записью каталога Gorgo с полями installed и provider_id, которые равны false и null, если интеграция не зарегистрирована в проекте.

GET /admin/integrations/license-status возвращает { packages }, последний результат проверки для каждого лицензируемого пакета, о котором знает процесс. Сюда входит и пакет, в котором нет провайдера интеграции, и тогда его identifiers пуст. Роут отдаёт то, что нашла последняя проверка, и не обращается к сервису лицензий.

POST /admin/integrations/license-status/recheck проверяет лицензии сразу и возвращает свежие результаты в том же виде, но только в том процессе, который получил запрос. Остальные процессы сервера проверяют по своему расписанию. Как лицензируются платные плагины, читайте в разделе Лицензии на платные плагины.