#Launch URL и SSO

SSO позволяет открыть Smartica из МИС без повторного ввода логина и пароля. Запрос выполняет только доверенный бэкенд МИС.

#Endpoint

Канонический шаблон:

POST https://app.smartica.ai/api/integrations/{platform}/sso/token

Используйте точный URL, выданный при онбординге. {platform} — placeholder зарегистрированного адаптера; произвольная подстановка нового slug вернёт 404.

#Запрос

POST /api/integrations/{platform}/sso/token
Authorization: Bearer <SSO_KEY>
Content-Type: application/json
Accept: application/json

{
  "user_email": "doctor@clinic.ru",
  "user_full_name": "Иванов Иван Иванович",
  "encounter_id": "12345"
}

Рекомендуется всегда отправлять user_full_name. Для существующего активного пользователя оно не требуется, но это избавляет МИС от отдельной проверки первого входа.

Не передавайте platform, email и ФИО напрямую из неподтверждённых полей браузера. Получайте их на бэкенде из текущего пользователя и карточки приёма.

#Автоматическое создание врача

При SSO-запросе Smartica:

1. ищет пользователя по нормализованному email;
2. использует существующий аккаунт, если он доступен этой организации;
3. создаёт нового врача по user_email и user_full_name, если аккаунта нет;
4. восстанавливает ранее удалённый аккаунт по тем же данным;
5. проверяет, что интеграция включена для организации.

Новый врач сразу входит через доверенный SSO без отдельной регистрации и подтверждения email.

Если существующий email уже относится к другой организации Smartica, автоматический перенос запрещён: API вернёт 403 email_in_other_organization.

#Ответ 200

{
  "launch_url": "https://app.smartica.ai/launch?platform=your-mis&encounter_id=12345&t=<one_time_token>",
  "expires_in": 60
}

expires_in — фактическое время жизни ссылки в секундах. Не зашивайте значение 60 в логику: используйте значение ответа.

После ответа:

1. сразу перенаправьте браузер на launch_url через HTTP 302 или откройте его в новой вкладке;
2. передайте URL без изменений;
3. не извлекайте и не сохраняйте параметр t;
4. при открытии Smartica удалит токен из адресной строки редиректом на чистый URL.

#Свойства launch_url

• токен одноразовый;
• токен ограничен временем из expires_in;
• токен привязан к пользователю, platform и encounter_id;
• изменение encounter_id в URL делает вход недействительным;
• повторное открытие использованной или просроченной ссылки приводит к обычному экрану входа.

Если ссылка истекла до открытия, запросите новую. Не пытайтесь повторно использовать старую.

#Ошибки SSO

Все ошибки возвращаются в JSON. Для 422 дополнительно приходит объект errors.

Пример 422 для нового врача без ФИО:

{
  "message": "Неверные данные.",
  "errors": {
    "user_full_name": [
      "Для создания врача нужно ФИО (user_full_name)."
    ]
  }
}

Пример конфликта организации:

{
  "error": "email_in_other_organization",
  "message": "Этот email уже привязан к другой организации в Smartica. Обратитесь в поддержку Smartica для переноса аккаунта."
}

Не заменяйте конкретный message общим «не авторизован». Для 401, 403 и 422 покажите понятную ошибку и не повторяйте тот же запрос без изменения причины. Для сетевого сбоя или 5xx можно предложить врачу повторить запуск.

#Безопасность

• вызывайте endpoint только по HTTPS и только с бэкенда;
• храните SSO_KEY в менеджере секретов или переменных окружения сервера;
• используйте разные ключи для разных окружений;
• не помещайте SSO_KEY, токен или launch_url в frontend, аналитику, exception tracker и access-логи;
• не отправляйте launch_url в Referer на сторонние домены;
• ротируйте ключ через согласованный с Smartica процесс.

#Пример curl

Подставьте точный endpoint, полученный при онбординге:

SSO_ENDPOINT='https://app.smartica.ai/api/integrations/your-mis/sso/token'
SSO_KEY='replace-with-secret'

curl --fail-with-body --silent --show-error \
  --request POST "${SSO_ENDPOINT}" \
  --header "Authorization: Bearer ${SSO_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "user_email": "doctor@clinic.ru",
    "user_full_name": "Иванов Иван Иванович",
    "encounter_id": "12345"
  }'

#Отладка без SSO

Только для локальной проверки, если врач уже авторизован в Smartica:

const url = `https://app.smartica.ai/launch?platform=${platform}&encounter_id=${encounterId}`;
window.open(url, '_blank', 'noopener,noreferrer');

Не используйте этот вариант на общем тестовом или рабочем окружении.

#Связанные статьи

• Запуск из МИС
• Глоссарий и правила идентификаторов
• Авторизация, ошибки и повторная доставка