Базовый флоу и обработка методов

В статье кратко разберём, как работает тиражируемая интеграция REGOS: как её создать, как REGOS вызывает ваш обработчик, какие базовые методы бывают и в каких сценариях они приходят.

1. Создание интеграции и тестирование

1) Создайте интеграцию в профиле разработчика:
https://apps.regos.uz/developers/integrations

2) После создания интеграция получает статус «Черновик», и вам будут доступны Client ID и Client Secret.

3) Чтобы ваша интеграция могла выполнять запросы к REGOS API, получите access_token через Client Credentials Flow и передавайте его в запросах в заголовке:
Authorization: Bearer <access_token>

Документация по токену:
https://docs.regos.uz/ru/sso/avtorizaciya-oauth/client-credentials-flow

2. Как REGOS вызывает методы

REGOS сам инициирует вызовы базовых методов и отправляет POST на URL, который вы указали в поле «URL обработчика» при создании интеграции.

Общая документация по базовым методам:
https://docs.regos.uz/ru/integration/methods/base

Ключевая сущность здесь — connected_integration_id. Это уникальный идентификатор подключения интеграции к конкретному аккаунту REGOS. По сути, это ваш “ключ” для того, чтобы понять: какой именно аккаунт сейчас вызвал обработчик. Его почти всегда имеет смысл сохранить у себя в базе, чтобы дальше правильно сопоставлять аккаунт REGOS с сущностями в вашей системе.

Запросы “из интеграции” в REGOS API выполняются через gateway:
https://integration.regos.uz/gateway/out/{connected_integration_id}/v1/{Method}

Ещё момент из практики: не пытайтесь делать тяжёлую работу прямо внутри входящего запроса. У вызовов есть ограничение по времени (таймаут), поэтому лучше быстро принять событие, положить задачу в очередь/фоновую обработку и вернуть 200 OK.

3. Когда вызываются базовые методы

Основные сценарии и рекомендации по обработке.

3.1. Connect

Документация:
https://docs.regos.uz/ru/integration/methods/base/connect

Когда вызывается: пользователь подключает интеграцию к своему аккаунту.

В момент подключения REGOS пришлёт вам connected_integration_id и дату подключения. connected_integration_id — самое важное: сохраните его. Если вы дальше планируете сопоставлять аккаунты, включать платную интеграцию/биллинг, инициировать запросы в REGOS API — без этого идентификатора будет сложно.

3.2. Disconnect

Документация:
https://docs.regos.uz/ru/integration/methods/base/disconnect

Когда вызывается: пользователь удаляет интеграцию из аккаунта.

По факту это сигнал “интеграцию больше не используют”. REGOS снова передаст connected_integration_id, чтобы вы могли у себя корректно выключить всё, что связано с этим подключением: остановить синхронизации, отменить фоновые задачи, закрыть доступ к платным функциям (если они завязаны на активность интеграции).

3.3. Reconnect

Документация:
https://docs.regos.uz/ru/integration/methods/base/reconnect

Когда вызывается: пользователь переустанавливает интеграцию.

Переустановка обычно нужна в двух случаях:
— поменялся connected_integration_id (например, по соображениям безопасности);
— вы обновили интеграцию и хотите, чтобы изменения (например, список настроек) корректно применились в аккаунте.

В Reconnect приходит новый connected_integration_id, а старый приезжает в поле previous_integration_id. Это сделано специально, чтобы вы могли у себя “перепривязать” подключение и не потерять связь с аккаунтом.

Что обычно делают: находят запись по previous_integration_id, переносят на новый ID, а старый помечают как неактуальный.

3.4. UpdateSettings

Документация:
https://docs.regos.uz/ru/integration/methods/base/updatesettings

Когда вызывается: пользователь изменил настройки интеграции в интерфейсе REGOS.

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

Ваша задача тут простая: принять эти значения и применить их у себя. Например: включить/выключить какой-то функционал, поменять токен Telegram-бота, фильтры, режим работы и т.д.

API-метод редактирования настроек, который инициализировал событие UpdateSettings:
https://docs.regos.uz/ru/api/integrations/connectedintegrationsetting/edit

3.5. HandleWebhook

Документация:
https://docs.regos.uz/ru/integration/methods/base/handlewebhook

Когда вызывается: в REGOS произошло событие, на которое интеграция подписана.

HandleWebhook — это уже “боевые” события. Внутри data.action вы увидите тип события, а в data.data — полезную нагрузку (иногда минимальную, например только id). Дальше вы решаете, что делать: подтянуть детали из API, обновить вашу систему, отправить данные дальше.

Если в обработке вебхука есть сетевые запросы или тяжёлая логика — лучше снова не делать это синхронно в одном запросе. Приняли событие → поставили задачу в очередь → вернули 200 OK.