#Авторизация, ошибки и повторная доставка

В интеграции два независимых направления. Не используйте один секрет для обоих.

#МИС → Smartica

SSO-запрос:

Authorization: Bearer <SSO_KEY>

SSO_KEY выдаётся после регистрации адаптера. Он должен находиться только на сервере МИС.

Полный контракт, rate limit и коды ошибок: Launch URL и SSO.

#Smartica → МИС

Текущий адаптер отправляет:

Authorization: Basic <base64(login:password)>
Accept: application/json

HTTP Basic безопасен только внутри HTTPS-соединения. Используйте:

• отдельную техническую учётную запись без интерактивного входа;
• длинный уникальный пароль;
• минимальные права только на согласованные GET и PUT;
• разные credentials для тестового и рабочего окружений;
• плановую ротацию с согласованным окном переключения.

Bearer, API key в нестандартном заголовке, mTLS и подпись запроса не поддерживаются автоматически. Если они обязательны, это нужно согласовать до подключения адаптера.

#Сетевой доступ

• endpoint МИС должен иметь валидный публично доверенный TLS-сертификат;
• не отключайте проверку TLS;
• если используется IP allowlist, запросите актуальные адреса Smartica при онбординге;
• не включайте allowlist по предположению: неверный список приведёт к timeout или 403;
• согласуйте VPN, proxy и DNS до сквозного теста.

#Контракт успешного ответа МИС

Для GET и PUT возвращайте:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

Тело должно быть валидным JSON-объектом. 204 No Content, пустое тело и HTML считаются ошибкой интеграции, даже если HTTP-код относится к 2xx.

#Формат ошибки МИС

Рекомендуемый ответ:

{
  "message": "Приём не найден"
}

Smartica может сохранить текст ошибки для диагностики и показать его пользователю. Поэтому message должен быть понятным и безопасным.

Никогда не включайте:

• stack trace;
• SQL и внутренние пути;
• логины, пароли, токены;
• полные персональные данные пациента;
• фрагменты конфигурации сервера.

#Коды ответов API МИС

Любой non-2xx, сетевой сбой, timeout или невалидный JSON означает ошибку текущей операции.

#Повторная доставка

Текущий контракт не гарантирует автоматический сетевой retry для каждого неуспешного GET или PUT.

Фактические способы повторения:

• после ошибки GET врач повторно открывает приём;
• после ошибки PUT врач запускает повтор отправки в интерфейсе Smartica;
• новая запись или повторная генерация в том же приёме создаёт новый PUT.

Из этого следуют два обязательных правила:

1. PUT должен быть идемпотентным по encounter_id.
2. МИС не должна рассчитывать ни на exactly-once доставку, ни на фиксированное число попыток.

Подробнее о слиянии полей и стенограммы: PUT: запись протокола.

#Timeout

Текущий HTTP timeout Smartica для API МИС — 30 секунд. Это верхний предел, а не рекомендуемое время ответа.

• GET должен быстро читать готовые данные приёма;
• PUT должен быстро сохранять данные;
• тяжёлую внутреннюю обработку МИС лучше выполнять после надёжного сохранения payload;
• не отвечайте 200, пока payload не принят устойчиво.

#Обработка ошибок SSO в МИС

Обычный вход в Smartica можно предложить как временный fallback только при сетевой или временной серверной ошибке. Он не исправляет неверный SSO_KEY, конфликт организации или невалидный encounter_id.

#Health check

Можно реализовать отдельный endpoint:

GET /api/smartica/health

{
  "status": "ok"
}

Он не входит в обязательный протокол и не вызывается Smartica автоматически. Передайте его команде Smartica, если хотите использовать для ручного smoke-теста.

#Диагностика

Проверяйте по порядку:

1. правильное ли окружение и хост;
2. совпадает ли encounter_id в SSO, URL и JSON;
3. доступен ли endpoint с согласованной сети;
4. валиден ли TLS-сертификат;
5. возвращается ли Content-Type: application/json;
6. нет ли 204, HTML или proxy-страницы вместо JSON;
7. идемпотентен ли повторный PUT.

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

• Launch URL и SSO
• GET: контекст приёма
• PUT: запись протокола
• Онбординг партнёра