Если опубликованный модуль подключается к CRM с помощью пользовательских API-ключей, его существующие подключения можно перевести на простое подключение. При миграции каждый экземпляр модуля получает собственный API-ключ, связанный с ним в системе.
Перед началом миграции
Сначала реализуйте и настройте простое подключение по основной статье: включите его поддержку, подготовьте получение конфигурации через configUrl и обработку запроса подключения на registerUrl. При миграции существующего подключения эти обработчики не вызываются.
Убедитесь, что в партнерском кабинете включена опция «Поддерживается простое подключение», а поле «Доступные модулю разрешения» содержит все разрешения, которые будут запрошены при миграции. Система не создаст ключ, если запрос содержит хотя бы одно разрешение, отсутствующее в этом поле.
Проверьте простое подключение модуля в партнерском CRM-аккаунте.
Подготовьте список подключений. Для каждого подключения должны быть известны:
- адрес CRM-аккаунта;
- текущий пользовательский API-ключ;
- код экземпляра модуля
integrationModule[code]; - необходимые этому экземпляру разрешения.
Текущий ключ должен быть активен и иметь разрешение integration_write. Если в одном CRM-аккаунте зарегистрировано несколько экземпляров модуля, мигрируйте каждый код экземпляра отдельно.
Сначала проверьте миграцию на тестовом аккаунте, затем переходите к рабочим подключениям.
Важно!
Шаг 1. Получите новый API-ключ
Для каждого подключения вызовите метод POST /api/v5/integration-modules/{code}/update-scopes. Авторизуйте запрос текущим пользовательским ключом, с которым работает модуль.
Параметр {code} в адресе — это код конкретного экземпляра integrationModule[code], а не общий код опубликованного модуля integrationModule[integrationCode].
В параметре формы requires передайте JSON-строку со списком разрешений scopes. Список должен включать все разрешения, необходимые экземпляру модуля, и не выходить за пределы разрешений в партнерском кабинете. Для последующего изменения настроек экземпляра и обновления его разрешений новому ключу также потребуется integration_write. В примере ниже запрашиваются права на чтение и изменение интеграций и заказов; замените их на разрешения вашего модуля.
После успешного вызова система связывает новый ключ с указанным экземпляром. Изменять настройки этого экземпляра и обновлять его разрешения можно будет только с помощью нового ключа. Старый пользовательский ключ остаётся активным.
Важно!
update-scopes создаёт новый ключ. Не настраивайте автоматические повторы запроса с прежним ключом: если ответ потеряется, например из-за разрыва соединения, экземпляр уже может быть связан с новым ключом. В такой ситуации обратитесь в поддержку и укажите адрес аккаунта и код экземпляра модуля, но не передавайте ключ.curl --request POST \
'https://example.retailcrm.ru/api/v5/integration-modules/my-module/update-scopes' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'apiKey=<текущий API-ключ>' \
--data-urlencode 'requires={"scopes":["integration_read","integration_write","order_read","order_write"]}'
Успешный ответ содержит новый API-ключ:
{
"success": true,
"apiKey": "<новый API-ключ>"
}
Шаг 2. Проверьте и сохраните новый ключ
Получив новый ключ, выполните с ним контрольные обращения к API и убедитесь, что доступны все необходимые модулю операции. Для изменения настроек экземпляра уже требуется новый ключ; другие обращения переводите на него после проверки.
Проверьте как минимум:
- чтение и изменение данных в пределах запрошенных разрешений;
- изменение настроек и активности модуля;
- работу фоновых задач и очередей, использующих API CRM.
После успешной проверки сохраните новый ключ в защищённом хранилище модуля и отметьте подключение как мигрированное. Переключение должно охватывать все процессы, которые работают с этим экземпляром: веб-запросы, фоновые задачи, очереди и задания по расписанию.
Если контрольные обращения завершаются ошибкой, проверьте запрошенные разрешения и настройки модуля в партнерском кабинете. Сохраните полученный ключ: экземпляр уже связан с ним, поэтому прежний ключ не подойдёт для изменения его настроек или повторного вызова update-scopes. Не деактивируйте старый ключ до завершения миграции.
Шаг 3. Прекратите использовать старый ключ
После сохранения нового ключа прекратите использовать старый во всех процессах, которые работают с этим экземпляром. Проверьте по журналам и метрикам, что обращения выполняются с новым ключом. Для контроля используйте безопасный внутренний идентификатор или необратимый отпечаток ключа: не записывайте сам ключ в журналы.
Важно!
API-ключ нельзя удалить из системы — его можно только деактивировать.
Если один старый ключ используется несколькими модулями
Вызовите update-scopes отдельно для каждого экземпляра, который использует общий пользовательский ключ. Каждый экземпляр получит собственный связанный ключ.
Не деактивируйте общий старый ключ, пока на отдельные ключи не переведены все использующие его модули и экземпляры. После миграции последнего подключения проверьте отсутствие обращений и только затем деактивируйте общий ключ.
Возможные ошибки
| Сообщение или ответ API | Причина | Что проверить |
|---|---|---|
Not enabled simple connection | Для модуля не включено простое подключение | Опцию «Поддерживается простое подключение» в партнерском кабинете |
Failed to update scopes, в errors — Module requires not available scopes: … | Запрошены разрешения, которых нет в настройках модуля | Поле «Доступные модулю разрешения» и содержимое requires.scopes |
Scopes can only be updated using integration module related API key | Экземпляр уже связан с другим ключом | Используется ли текущий ключ этого экземпляра, а не старый или ключ другого модуля |
Errors in the entity format | Список scopes отсутствует или пуст | Список scopes в JSON-строке параметра requires |
404 Not Found | Экземпляр модуля или опубликованный модуль не найден | Адрес аккаунта, integrationModule[code] и код опубликованного модуля |
| Ошибка авторизации | Ключ неактивен или не имеет нужного разрешения | Наличие разрешения integration_write и актуальность ключа |
Если после миграции потребуется изменить набор разрешений, используйте раздел «Обновление разрешений подключённого модуля».