#Подключение

Подключение ведёте вы вместе с командой smartica.ai. Подключение включает регистрацию, обмен секретами, настройку вашего API и приёмочный тест.

Одной выдачи platform недостаточно. Пока подключение не активировано с нашей стороны, запросы возвращают 404.

Для старта напишите на support@smartica.ai или откройте статью Поддержка.

#Срок подключения

Ориентировочные сроки:

Этап	Кто ведёт	Обычный срок
Заявка и подтверждение	smartica.ai	1–2 рабочих дня
Согласование контракта	Обе стороны	1–3 рабочих дня
Разработка на стороне МИС	Вы	От нескольких часов до недели
Приёмочный прогон	Обе стороны	1 день

Разработку можно начинать параллельно с согласованием. Контракт от согласования почти не зависит.

#Этап 1. Заявка

В первом сообщении укажите:

название МИС и клиники.
контакт технического специалиста.
предполагаемые адреса тестового и рабочего окружений.
как доступен ваш API: из интернета, через VPN или по IP allowlist.
желаемые сроки тестирования.

smartica.ai подтверждает, что подключение возможно. smartica.ai назначает технический контакт с нашей стороны.

#Этап 2. Фиксация контракта

Зафиксируйте то, что потом меняется только по согласованию:

Тема	Что фиксируем
Сценарии	Launch, Import или оба
Доставка	`push`. Мы вызываем ваш `PUT`. `pull`. Вы забираете протокол и подтверждаете
Идентификатор	Формат `encounter_id` и в каких границах он уникален
SSO	Точный адрес, `platform`, обязательные поля запроса
`GET` и `PUT`	Финальные адреса на вашей стороне
Import	Глубина списка записей и вид формы привязки
Авторизация	Схема, отдельные секреты для окружений, порядок ротации
Сеть	DNS, TLS, VPN или IP allowlist
Данные	Куда ваша МИС сохраняет стенограмму и многострочные значения
Ошибки	Формат безопасного тела ответа и контакт для инцидентов

Для запросов smartica.ai → МИС доступны три схемы: HMAC-подпись (самая защищённая), Bearer-токен (по умолчанию) и HTTP Basic (совместимость). Если нужны mTLS или OAuth, скажите до начала реализации. Эти схемы требуют доработки на нашей стороне. Сравнение схем в статье Авторизация и ошибки.

Передавайте секреты только через согласованный защищённый канал. Храните секреты только на сервере.

#Подсказка по выбору конфигурации

Если сомневаетесь, начните с Launch и push и передайте бланк в SSO-запросе. Тогда на вашей стороне один входящий endpoint (PUT) и один исходящий вызов. Остальные части добавляйте позже.

Режим pull выбирайте, если МИС стоит в закрытом контуре и входящие запросы из интернета невозможны.

#Этап 3. Что передаёте вы

Базовые адреса тестового и рабочего окружений.
Финальные пути GET и PUT с плейсхолдером {id}.
Учётные данные тестового API через защищённый канал.
Тестовый encounter_id, доступный через ваш API.
Email и ФИО тестового врача.
Реальный пример ответа из статьи Бланк приёма.
Куда вы сохраняете данные из статьи Запись протокола в карту.
Контакт разработчика для разбора ошибок.

Не отправляйте пароли, ключи и персональные данные обычным письмом, если защищённый канал ещё не согласован.

#Этап 4. Что передаёт smartica.ai

Параметр	Описание
`platform`	Зарегистрированный идентификатор вашей клиники
SSO endpoint	Точный адрес вида `/api/v1/integrations/{platform}/sso/token`
API-ключ клиники	Секрет для SSO и, при `pull`, для забора протоколов
Режим доставки	`push` или `pull`
Адрес окружения	Тестовое или рабочее приложение smartica.ai
Сетевые параметры	Адреса, с которых приходят запросы, если список вам нужен

Используйте разные секреты для тестового и рабочего контуров. Разные секреты не дают тестовому прогону записать данные в реальную карту.

Разработку и приёмку ведите на тестовом контуре. Адрес, правила и переход на рабочий контур описаны в статье Тестовая площадка.

#Этап 5. Подготовка тестовых данных

Для контрольного прогона подготовьте:

приём с уникальным encounter_id в поддерживаемом формате.
врача с валидными email и ФИО.
непустой template.
минимум два поля с уникальными id и понятными label.
место, где входящий PUT виден сразу, без поиска по логам.

Если PUT приходится искать в логах, отладка занимает часы.

Аккаунт врача заранее создавать в smartica.ai не нужно. При первом входе по SSO мы создаём аккаунт автоматически, если переданы email и ФИО.

Врача, который уже регистрировался в smartica.ai сам, мы при первом входе присоединяем к вашей клинике. Так происходит, пока для клиники включено автосоздание врачей. По умолчанию автосоздание включено.

Исключение. Если email принадлежит врачу другой клиники в smartica.ai, SSO возвращает 403. Такие случаи решайте через поддержку.

#Этап 6. Приёмочный прогон

Интеграцию можно включать, когда подтверждены все пункты:

SSO вызывается с бэкенда и возвращает рабочую ссылку
Новый врач входит без отдельной регистрации
Существующий врач попадает в свой прежний аккаунт
GET возвращает ожидаемый приём, бланк и поля
После записи МИС получает PUT с полями и полной стенограммой
Повторный одинаковый PUT не создаёт дубликат
Поля, отсутствующие в PUT, не затираются
Повторная запись в том же приёме обновляет существующие данные
Ошибки 401, 403, 404, 422, 429 и временный 5xx отображаются понятно
Успешные ответы содержат JSON, 204 No Content не используется
Секреты и ссылка для входа отсутствуют в клиентском коде и логах
Проверены оба окружения, секреты у них разные

При режиме pull дополнительно:

Список записей обходится постранично по next_cursor
Протокол забирается и сохраняется корректно
Подтверждение отправляется только после реального сохранения
Ошибка 409 revision_mismatch приводит к повторному забору, а не к игнорированию

#Правила изменений после запуска

Не меняйте путь, схему авторизации, формат ID, значения fields[].id и смысл template без согласования.
Добавлять новые поля можно, если их id уникальны, а label однозначны.
Ломающие изменения сначала проверяйте на тестовом окружении.
Аудиофайл в контракт не входит. Если он нужен, согласуйте отдельное расширение.

Смена fields[].id ломает сопоставление без явной ошибки. Данные начинают попадать не в те поля. Если fields[].id всё-таки надо изменить, предупредите нас заранее.