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

После подключения:

• пользователи смогут регистрироваться на сервисе с синхронизацией профиля через платформу;
• пользователь платформы сможет подключить сервис через интерфейс платформы;
• платформа сможет создавать пользователя на сервисе через API;
• изменения профиля и пароля смогут синхронизироваться между платформой и подключенными сервисами;
• владелец сервиса будет назначен единственным пользователем с ролью METASERVICE-ADMIN на сервисе.

<note important> Не путайте два разных направления доступа:

• Сервис → Платформа: сервис использует PLATFORM_API_URL и PLATFORM_API_KEY.
• Платформа → Сервис: платформа использует api_url сервиса и ключ, сгенерированный на сервисе.

</note>

Перед подключением убедитесь, что:

1. ShariX Open установлен и открывается в браузере.
2. На сервисе есть пользователь, который может зайти в кабинет администратора сервиса.
3. На платформе есть пользователь, который будет создавать запись сервиса.
4. Установлены и применены миграции всех подключенных модулей.
5. Сервис доступен с платформы по сети.
6. На сервисе в .env указан корректный PLATFORM_API_URL.

Пример настройки на сервисе:

PLATFORM_INTEGRATION=2
PLATFORM_API_URL=https://platform.example.org/my/api/
DEFAULT_CLIENT_ROLE=METASERVICE-CLIENT

Рекомендуемый режим для первичной настройки:

PLATFORM_INTEGRATION=2

Это подготовительный режим. В нем можно настраивать интеграцию, проверять ключи и API, не считая сервис полностью активным.

После успешной проверки можно перейти в активный режим:

PLATFORM_INTEGRATION=1

<note warning> PLATFORM_INTEGRATION на сервисе — это настройка администратора сервиса. Платформа не должна автоматически менять это значение в .env. </note>

Выполняется на сервере сервиса ShariX Open.

Откройте .env установленного сервиса и проверьте:

PLATFORM_INTEGRATION=2
PLATFORM_API_URL=https://platform.example.org/my/api/
DEFAULT_CLIENT_ROLE=METASERVICE-CLIENT

Если сервис должен регистрировать обычных пользователей как клиентов сервиса:

DEFAULT_CLIENT_ROLE=METASERVICE-CLIENT

Если сервис должен регистрировать пользователей только локально, без синхронизации:

DEFAULT_CLIENT_ROLE=METASERVICE-GUEST

Если сервис должен принимать заявки корпоративных клиентов:

DEFAULT_CLIENT_ROLE=METASERVICE-CORPCLIENT

<note important> Если указано METASERVICE-GUEST, пользователи при ручной регистрации создаются локально, без записи Client и без синхронизации с платформой. </note>

Выполняется в интерфейсе сервиса ShariX Open.

1. Войдите на сервис под пользователем с правами администратора сервиса.
2. Откройте кабинет метасервиса.
3. Нажмите кнопку генерации API-ключа для платформы.
4. Скопируйте полученный ключ.

Этот ключ нужен платформе, чтобы обращаться к API сервиса.

Пример того, куда платформа потом будет обращаться:

GET   https://open.example.org/my/api/v1/platform/health/
PATCH https://open.example.org/my/api/v1/platform/settings/
POST  https://open.example.org/my/api/v1/platform/users/register/
PATCH https://open.example.org/my/api/v1/platform/users/profile/

<note warning> В рабочем режиме ключ может быть показан только один раз после генерации. Скопируйте его сразу.

В отладочном режиме DEBUG=True ключ может дополнительно отображаться в кабинете сервиса, чтобы его было удобно перенести на платформу. </note>

Выполняется на Платформе ShariX.

1. Войдите на платформу под пользователем, который будет владельцем/представителем сервиса.
2. Откройте раздел создания сервиса.
3. Заполните данные сервиса:
   • название сервиса;
   • юридическое название;
   • ИНН;
   • реквизиты;
   • описание;
   • URL сайта сервиса;
   • API URL сервиса;
   • ключ доступа платформы к сервису.

Ключевые поля для интеграции:

Пример:

api_url=https://open.example.org/my/api/
dbsynce_key=ключ_сгенерированный_на_сервисе

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

PLATFORM_API_KEY

Этот ключ нужен сервису, чтобы обращаться к API платформы.

Если на платформе заполнены:

• api_url;
• dbsynce_key;
• платформенный API-ключ для сервиса,

то платформа автоматически пытается выполнить настройку сервиса.

Платформа вызывает API сервиса:

PATCH /my/api/v1/platform/settings/

На сервис передаются только:

{
  "metaservice_id": "<ID сервиса на платформе>",
  "platform_api_key": "<ключ, выданный платформой сервису>"
}

Сервис записывает в свой .env:

METASERVICE_ID=<ID сервиса на платформе>
PLATFORM_API_KEY=<ключ, выданный платформой сервису>

<note important> Платформа не перезаписывает PLATFORM_API_URL на сервисе. Этот URL задается администратором сервиса вручную. </note>

После обновления настроек платформа вызывает API сервиса и передает текущего пользователя платформы как администратора сервиса:

POST /my/api/v1/platform/users/register/

С ролью:

METASERVICE-ADMIN

Сервис должен:

• создать пользователя, если его еще нет;
• назначить ему роль METASERVICE-ADMIN;
• снять METASERVICE-ADMIN с тестового пользователя 2101, если он был;
• снять лишние права METASERVICE-ADMIN с других пользователей;
• оставить только одного METASERVICE-ADMIN.

Платформа вызывает:

GET /my/api/v1/platform/health/

И проверяет:

metaservice_admin_is_valid = true
metaservice_admin_count = 1

Если на сервисе больше одного METASERVICE-ADMIN, активная интеграция считается некорректной.

Выполняется на сервисе ShariX Open.

Проверьте .env сервиса:

PLATFORM_INTEGRATION=2
PLATFORM_API_URL=https://platform.example.org/my/api/
METASERVICE_ID=<ID сервиса на платформе>
PLATFORM_API_KEY=<ключ, выданный платформой сервису>

Проверьте, что в сервисе:

• появился или обновился пользователь-владелец сервиса;
• у него есть роль METASERVICE-ADMIN;
• у пользователя 2101 больше нет роли METASERVICE-ADMIN, если она была;
• в кабинете метасервиса нет предупреждения о нескольких METASERVICE-ADMIN.

Если используется Testkit, можно проверить endpoint:

GET /my/api/v1/platform/health/

Ожидаемый смысл ответа:

status=ok
metaservice_admin_is_valid=true
metaservice_admin_count=1
platform_api_key_configured=true

После успешной настройки можно перевести сервис из подготовительного режима в активный.

На сервисе в .env:

PLATFORM_INTEGRATION=1

После изменения .env перезапустите приложение сервиса.

На платформе сервис также должен быть в активном статусе интеграции.

Если на сервисе:

DEFAULT_CLIENT_ROLE=METASERVICE-CLIENT
PLATFORM_INTEGRATION=1

или:

PLATFORM_INTEGRATION=2

то при регистрации пользователь может выбрать синхронизацию с платформой.

Если пользователь выбрал синхронизацию:

• сервис пытается создать пользователя на платформе;
• если платформа успешно создала пользователя, на сервисе создается Client с is_global = true;
• если платформа недоступна, пользователь создается локально, а Client.is_global остается false;
• если пользователь уже существует на платформе, сервис предлагает перейти на платформу и подключить сервис там.

Если пользователь уже существует на платформе и хочет подключить сервис:

1. пользователь авторизуется на платформе;
2. открывает список активных сервисов;
3. выбирает нужный сервис;
4. нажимает подключение сервиса.

После этого платформа вызывает API сервиса и создает/обновляет пользователя на сервисе.

Если на сервисе:

DEFAULT_CLIENT_ROLE=METASERVICE-CORPCLIENT

то при регистрации:

• создается пользователь;
• назначается роль корпоративного клиента;
• создается Client в неактивном состоянии;
• создается заявка CorpClient;
• текущий пользователь становится представителем корпоративного клиента.

Состояние синхронизации пользователя на сервисе хранится в записи Client:

Если у пользователя нет записи Client, он считается локальным пользователем сервиса.

Пользователь может управлять синхронизацией в своем профиле, если:

• сервис подключен к платформе;
• PLATFORM_INTEGRATION равен 1 или 2;
• у пользователя есть запись Client;
• базовая роль регистрации допускает создание клиента.

Если у пользователя включена синхронизация:

• изменение профиля на сервисе отправляется на платформу;
• смена пароля на сервисе отправляется на платформу;
• платформа обновляет данные у себя;
• платформа пробует отправить изменения на другие сервисы, с которыми пользователь связан и где включена синхронизация.

Если один из связанных сервисов не принял изменение:

• операция для пользователя-инициатора не откатывается;
• профиль или пароль на инициирующем сервисе уже изменены;
• платформа переводит проблемный сервис в аварийный режим;
• пользователю может быть показано предупреждение со списком сервисов, где синхронизация не удалась.

Если активный сервис должен синхронизироваться с платформой, но API сервиса недоступен или возвращает ошибку, платформа может перевести сервис в статус:

3

Это означает:

error

В аварийном режиме сервис не считается корректно синхронизированным.

Чтобы вернуть сервис в рабочее состояние:

1. проверьте доступность API сервиса;
2. проверьте api_url на платформе;
3. проверьте dbsynce_key на платформе;
4. проверьте PLATFORM_API_URL на сервисе;
5. проверьте METASERVICE_ID и PLATFORM_API_KEY на сервисе;
6. проверьте, что на сервисе ровно один METASERVICE-ADMIN;
7. после исправления переведите статус интеграции обратно в активный.

1. Установлен ShariX Open.
2. В .env указан PLATFORM_API_URL.
3. В .env указан PLATFORM_INTEGRATION=2 для первичной настройки.
4. Сгенерирован ключ доступа платформы к сервису.
5. Скопирован сгенерированный ключ.

1. Создана запись сервиса.
2. Заполнен api_url сервиса.
3. В dbsynce_key вставлен ключ, сгенерированный на сервисе.
4. Платформа выдала сервису PLATFORM_API_KEY.
5. Платформа успешно записала на сервис METASERVICE_ID и PLATFORM_API_KEY.
6. Платформа назначила текущего пользователя единственным METASERVICE-ADMIN на сервисе.
7. Health-check сервиса проходит успешно.

1. На сервисе в .env появились METASERVICE_ID и PLATFORM_API_KEY.
2. PLATFORM_API_URL остался заданным вручную.
3. На сервисе ровно один METASERVICE-ADMIN.
4. Пользователь-владелец сервиса может зайти в кабинет сервиса.
5. Сервис можно перевести из PLATFORM_INTEGRATION=2 в PLATFORM_INTEGRATION=1.

Проверьте:

• правильно ли заполнен api_url на платформе;
• доступен ли сервис из сети платформы;
• заканчивается ли api_url на /my/api/;
• не блокирует ли доступ firewall;
• корректен ли ключ dbsynce_key.

Проверьте на сервисе:

PLATFORM_API_URL
METASERVICE_ID
PLATFORM_API_KEY
PLATFORM_INTEGRATION

Это не всегда ошибка.

Если пользователь выбрал синхронизацию на сервисе, но уже существует на платформе, он должен:

1. авторизоваться на платформе;
2. открыть список сервисов;
3. подключить нужный сервис через интерфейс платформы.

Сервис в таком состоянии не считается корректно настроенным для активной интеграции.

Нужно оставить одного администратора сервиса и снять роль METASERVICE-ADMIN с остальных пользователей.

В кабинете метасервиса должно отображаться предупреждение и кнопки для снятия лишних прав.

Если при открытии Testkit появляется ошибка вида:

relation "testkit_run" does not exist

нужно убедиться, что миграции модуля Testkit применены.

Обычно достаточно выполнить общий update/install, который запускает миграции. Если модуль был подключен позднее, проверьте, что приложение sharix_testkit действительно включено в настройки проекта и что его миграции применены.

1. На сервисе установить PLATFORM_INTEGRATION=2.
2. На сервисе указать PLATFORM_API_URL.
3. На сервисе сгенерировать ключ доступа платформы к сервису.
4. На платформе создать запись сервиса.
5. На платформе указать api_url сервиса.
6. На платформе вставить ключ сервиса в dbsynce_key.
7. Сохранить сервис на платформе.
8. Дождаться автоматической записи METASERVICE_ID и PLATFORM_API_KEY на сервис.
9. Проверить, что текущий пользователь стал единственным METASERVICE-ADMIN на сервисе.
10. Проверить health-check.
11. Перевести сервис в PLATFORM_INTEGRATION=1.
12. Провести тестовую регистрацию пользователя.
13. Провести тестовое подключение уже существующего пользователя платформы к сервису.
14. Провести тестовое изменение профиля и пароля.