#Быстрый старт

Ниже — минимальный путь до первого сквозного теста. Не начинайте с подстановки произвольного {platform}: сначала Smartica должна зарегистрировать подключение вашей МИС.

#1. Получите параметры подключения

Напишите на support@smartica.ai или через форму связи и передайте:

  • название МИС и клиники;
  • тестовый и рабочий базовые URL МИС;
  • контакт разработчика;
  • предполагаемую схему авторизации Smartica → МИС.

После согласования и активации адаптера Smartica передаст:

  • platform;
  • точный SSO endpoint для каждого окружения;
  • секретный SSO_KEY;
  • параметры тестового стенда и сетевого доступа.

Подробнее: Онбординг партнёра.

#2. Реализуйте два endpoint в МИС

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

/api/smartica/encounters/{encounter_id}

#GET — отдать контекст

{
  "encounter_id": "12345",
  "user_email": "doctor@clinic.ru",
  "template": "Кардиолог",
  "fields": [
    { "id": "complaints", "label": "Жалобы" },
    { "id": "diagnosis", "label": "Диагноз (основной)" }
  ]
}

#PUT — принять результат

{
  "encounter_id": "12345",
  "fields": [
    { "id": "complaints", "value": "Жалобы на головную боль..." },
    { "id": "diagnosis", "value": "Гипертоническая болезнь I ст." }
  ],
  "transcript": "Полная стенограмма разговора..."
}

Текущий адаптер Smartica использует HTTP Basic по HTTPS. Если вашей МИС нужна другая схема, согласуйте её до разработки — она не включается автоматически.

Полные контракты:

#3. Добавьте кнопку «Smartica» и серверный SSO

По клику бэкенд МИС, а не браузер, вызывает точный endpoint, полученный при онбординге:

POST https://app.smartica.ai/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: для существующего пользователя поле не требуется, но для первого входа по SSO без него Smartica вернёт 422.

Успешный ответ:

{
  "launch_url": "https://app.smartica.ai/launch?platform=…&encounter_id=12345&t=…",
  "expires_in": 60
}

Сразу откройте launch_url врачу через HTTP-редирект или новую вкладку. Не разбирайте и не собирайте этот URL самостоятельно.

Подробнее: Launch URL и SSO.

#Ускорение: готовый промпт для ИИ-агента

Если у ИИ-агента есть доступ к репозиторию МИС и возможность запускать тесты, он может подготовить большую часть интеграции. Сначала получите точный SSO endpoint и параметры подключения: агент не должен придумывать их самостоятельно.

Документация Smartica для агентов:

  • индекс: https://smartica.ai/llms.txt;
  • статьи интеграции — сырой Markdown по URL с суффиксом .md (без HTML-обёртки).

Перед запуском замените значения в <угловых скобках>. Не вставляйте в промпт реальные секреты, данные пациентов или рабочие credentials — передайте только имена переменных окружения.

Ты работаешь в репозитории медицинской информационной системы:
- название: <MIS_NAME>
- стек и версии: <STACK_AND_VERSIONS>
- точный SSO endpoint Smartica: <SSO_ENDPOINT_FROM_SMARTICA>
- зарегистрированный platform: <PLATFORM_FROM_SMARTICA>
- модель/таблица приёма: <ENCOUNTER_MODEL_OR_TABLE>
- модель/таблица врача: <DOCTOR_MODEL_OR_TABLE>

Нужно реализовать интеграцию МИС со Smartica.

Сначала:
1. Открой https://smartica.ai/llms.txt — это канонический индекс документации.
2. Из секции «Интеграция с МИС» загрузи нужные статьи как Markdown
   (URL оканчиваются на .md). Не парси HTML-страницы /help, если доступен .md.
3. Обязательно прочитай:
   - https://smartica.ai/help/integrations/glossary.md
   - https://smartica.ai/help/integrations/launch-and-sso.md
   - https://smartica.ai/help/integrations/mis-api-get-encounter.md
   - https://smartica.ai/help/integrations/mis-api-export-encounter.md
   - https://smartica.ai/help/integrations/authentication-and-errors.md
4. Изучи структуру проекта, существующие conventions, auth, валидацию,
   обработку ошибок и тесты.
5. Найди текущий способ проверки доступа врача к приёму.
6. Составь короткий план и перечисли недостающие обязательные данные.
7. Если неизвестны точный endpoint, схема хранения протокола или auth
   входящих запросов, остановись и задай вопросы. Не выдумывай контракт.

Реализуй:

1. Серверный запуск Smartica
- Добавь кнопку/действие «Smartica» в карточку приёма.
- Браузер передаёт бэкенду только ID текущего приёма.
- Бэкенд проверяет авторизацию врача и доступ к приёму.
- Бэкенд получает email и ФИО врача из доверенных данных МИС.
- Бэкенд вызывает точный SSO endpoint методом POST:
  Authorization: Bearer <значение переменной SMARTICA_SSO_KEY>
  Content-Type: application/json
  Accept: application/json
- JSON: user_email, user_full_name, encounter_id.
- encounter_id всегда передавай строкой.
- Верни браузеру redirect на launch_url или безопасно открой его в новой вкладке.
- Не собирай launch_url самостоятельно.

2. GET /api/smartica/encounters/{encounter_id}
- Защити endpoint HTTP Basic по HTTPS.
- Credentials читай из SMARTICA_BASIC_USERNAME и
  SMARTICA_BASIC_PASSWORD.
- Найди приём и проверь его доступность для интеграции.
- Верни 200 JSON:
  encounter_id, user_email, template,
  fields: [{ id, label }].
- fields[].id должны быть уникальными и стабильными.
- fields[].label должны быть человекочитаемыми.
- Для ошибок возвращай подходящий non-2xx и безопасный JSON message.

3. PUT /api/smartica/encounters/{encounter_id}
- Используй только PUT и ту же HTTP Basic авторизацию.
- Валидируй encounter_id, fields и transcript.
- Проверь совпадение ID в URL и JSON.
- В одной транзакции обнови переданные fields по id.
- Не очищай поля, отсутствующие в массиве.
- Замени сохранённую стенограмму полной версией transcript.
- Сделай обработку идемпотентной по encounter_id:
  повторный payload не создаёт новую карточку, протокол или вложение.
- Верни 200 JSON:
  { "encounter_id": "...", "status": "saved" }.
- Не возвращай 204, HTML или пустое тело.

4. Конфигурация и безопасность
- Секреты только в env/config; добавь placeholders в .env.example.
- Не помещай ключи, Basic credentials, launch_url или SSO token
  во frontend, логи и тексты ошибок.
- Не логируй медицинские данные целиком.
- Не ослабляй TLS и существующую авторизацию.
- Не меняй несвязанный код и зависимости без необходимости.

5. Тесты
- Успешная выдача контекста через GET.
- 401 для неверного Basic.
- 404 для неизвестного encounter_id.
- Успешный PUT с полями и transcript.
- Повторный одинаковый PUT не создаёт дубликат.
- Отсутствующие в PUT поля не очищаются.
- Несовпадающие ID в URL и JSON отклоняются.
- SSO вызывается только сервером и передаёт user_full_name.
- Секреты отсутствуют в клиентском bundle и ответах.

После реализации:
1. Запусти formatter, линтер, целевые тесты и сборку frontend, если он менялся.
2. Исправь введённые тобой ошибки.
3. Покажи список изменённых файлов.
4. Кратко опиши принятые решения и команды проверки.
5. Отдельно перечисли всё, что требует параметров или подтверждения Smartica.

После работы агента разработчик должен проверить diff, авторизацию, миграции и тесты, а затем выполнить контрольный приём. ИИ не заменяет приёмочный прогон.

#4. Прогоните один контрольный приём

  1. Создайте тестовый приём с уникальным encounter_id.
  2. Убедитесь, что GET вручную возвращает 200 и корректный JSON.
  3. Откройте карточку приёма и нажмите «Smartica».
  4. Проверьте вход без повторной авторизации.
  5. Запишите короткий разговор, остановите запись и дождитесь обработки.
  6. Проверьте входящий PUT, значения полей и полную стенограмму.
  7. Повторите тот же PUT и убедитесь, что МИС обновила приём без дубликата.
  8. Добавьте ещё одну запись в тот же приём и проверьте обновление результата.

#5. Минимальный чеклист готовности

  • Получены точные URL, platform и SSO_KEY
  • encounter_id передаётся JSON-строкой и не переиспользуется для другого приёма
  • SSO вызывается только с бэкенда; секреты отсутствуют во фронтенде и логах
  • GET возвращает стабильный template, уникальные fields[].id и понятные fields[].label
  • user_email в SSO и GET относится к одному врачу
  • PUT обновляет существующий приём по encounter_id и не создаёт дубликаты
  • Успешные GET и PUT возвращают JSON; 204 No Content не используется
  • Ошибки не содержат stack trace, SQL, токены или другие секреты

Расширенный чеклист: Онбординг партнёра.

← Все статьи: Интеграция с МИС Поиск по базе знаний