#Подключение партнёра

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

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

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

#Сколько это занимает

Ориентировочно:

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

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

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

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

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

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

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

Договариваемся о том, что нельзя будет легко поменять потом:

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

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

Секреты передаются через согласованный защищённый канал. Храните их только на сервере.

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

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

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

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

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

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

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

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

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

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

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

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

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

Последний пункт экономит больше всего времени: если для проверки прихода PUT приходится каждый раз лезть в логи, отладка растягивается на часы.

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

Исключение: если этот email уже относится к другой организации в Smartica — например, врач регистрировался у нас сам, — 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 — самое опасное изменение: оно тихо ломает сопоставление, и данные начинают попадать не в те поля. Если ключ всё-таки надо изменить, предупредите нас заранее.