#Если запросы не проходят

Найдите свой симптом. Дальше идите по шагам.

#Сначала проверьте пять частых причин

Пять причин закрывают больше половины проблем на старте:

1. Подключение ещё не активировано. Пока smartica.ai не зарегистрировала вашу клинику, любой запрос возвращает 404, включая верный URL.
2. Перепутаны контуры. Ключ тестового контура не работает на рабочем, и наоборот. Адреса контуров в статье Тестовая площадка.
3. Перепутаны секреты. Ключ клиники для запросов к smartica.ai и логин с паролем для запросов smartica.ai к вам различаются.
4. encounter_id передан числом, а не строкой. Должно быть "12345", а не 12345.
5. Перепутаны идентификаторы в Import. В адресе наш smartica_encounter_id. В теле ваш encounter_id.

#Запросы к smartica.ai

#Любой запрос возвращает 404

Незарегистрированный platform правильного формата даёт такой же 404, как опечатка. Отличить незарегистрированный platform от опечатки можно только через поддержку.

#SSO возвращает 401

Ключ неверен или не передан.

• Проверьте заголовок Authorization: Bearer <ключ>. Перед ключом стоят слово Bearer и пробел.
• Проверьте, что ключ не обрезан при копировании и не содержит переводов строки.
• Проверьте, что используется ключ того контура, в который идёт запрос.
• Если ключ недавно перевыпускали, старый действует ещё 72 часа. Потом старый ключ перестаёт работать.

Не повторяйте запрос автоматически. Неудачные попытки авторизации ограничены 30 в минуту на клинику. Цикл повторов даёт 429.

#SSO возвращает 403 email_in_other_organization

Этот email уже используется в smartica.ai, но принадлежит врачу другой клиники. Автоматически перенести аккаунт нельзя. Так smartica.ai защищается от захвата чужой учётной записи.

Есть и другой случай. Врач регистрировался в smartica.ai сам. Автосоздание врачей для вашей клиники выключено. При включённом автосоздании мы присоединяем этого врача к клинике. Ошибки нет.

Покажите врачу текст из поля message. Обратитесь в поддержку smartica.ai.

#SSO возвращает 403 integration_not_enabled

Интеграция для вашей клиники выключена. Включить интеграцию может только smartica.ai. Напишите в поддержку.

#SSO возвращает 422

Ошибка в переданных данных. Точная причина всегда в объекте errors.

Пример ответа при первом входе без ФИО:

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

#SSO возвращает 429

Превышен лимит в 30 запросов в минуту. Дождитесь времени из заголовка Retry-After.

Если лимит срабатывает при обычной работе, запрос за ссылкой уходит не один раз на клик. Проверьте повторную отправку формы и автоматический повтор запроса при ошибке.

#SSO возвращает 503

Интеграция или SSO ещё не настроены на нашей стороне. Покажите врачу временную ошибку. Обратитесь в поддержку.

#Вход врача

#Врач попадает на обычный экран входа вместо приёма

Ссылка одноразовая и живёт около минуты. Причины по частоте:

1. Ссылка уже была использована. Повторно открыть ссылку нельзя. Запросите новую.
2. Ссылка истекла. Между получением и открытием прошло больше expires_in секунд. Открывайте ссылку сразу. Не складывайте ссылку в очередь. Не отправляйте ссылку письмом.
3. Ссылку изменили. Любая правка параметров, включая encounter_id, делает вход недействительным. Передавайте URL без изменений.
4. Ссылка сохранена и переиспользуется. Каждый запуск требует нового запроса за ссылкой.

#Врач вошёл, но приём не подготовился

Не удалось получить контекст приёма. Проверьте свой GET:

curl --fail-with-body --silent --show-error \
  --user 'LOGIN:PASSWORD' \
  --header 'Accept: application/json' \
  'https://mis.example.ru/api/for-smartica/encounters/12345'

Ответ обязан быть:

• код 200.
• заголовок Content-Type: application/json.
• валидный JSON-объект.
• с непустыми template и fields.

Типичные поломки:

• сервер отдаёт HTML-страницу ошибки.
• прокси возвращает свою заглушку.
• ответ приходит с 204 или пустым телом.
• JSON синтаксически невалиден.

Если проблема была временной, исправьте endpoint. Попросите врача открыть приём заново.

#Врач вошёл под чужим аккаунтом

Email в SSO-запросе и в ответе GET должны относиться к одному врачу. Убедитесь, что бэкенд берёт email из сессии текущего пользователя. Не берите email из тела запроса браузера. Не берите email из карточки приёма. В карточке может стоять другой врач.

#Возврат результата

#PUT не приходит вообще

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

1. Какой режим доставки у вашего подключения. При pull мы PUT не отправляем. Забирать результат должны вы. Уточните режим в поддержке, если не помните.
2. Запись действительно завершена. Врач останавливает запись и ждёт обработки. PUT уходит только после заполнения протокола.
3. Ваш endpoint доступен из интернета. Проверьте endpoint с машины вне вашей сети. Проверка из внутренней сети не подходит.
4. Сертификат TLS валиден и публично доверен. Самоподписанный сертификат не принимается. Проверку TLS мы не отключаем.
5. Нет IP-фильтра. Если у вас allowlist, запросите у нас актуальные адреса. Неверный список даёт timeout или 403.
6. Статус отправки в интерфейсе smartica.ai. Врач видит статус у себя в smartica.ai. Там же есть кнопка повтора.

#PUT приходит, но массив fields пустой

Пустой fields — валидный ответ, не ошибка. smartica.ai присылает только те поля, для которых нашлось содержательное значение. Пустые значения и заглушки вроде «не указано» отбрасываются.

Пустой fields означает, что в разговоре не нашлось материала для полей бланка. Например, запись слишком короткая. Стенограмму сохраните и при пустом fields.

Если пустой fields приходит регулярно при обычных приёмах, проблема почти всегда в label. По названиям полей непонятно, что в них писать. Смотрите следующий раздел.

#Поля заполняются не тем содержанием

Качество заполнения определяется двумя вещами: template и fields[].label.

Раздел про fields в статье Бланк приёма содержит правила и примеры.

Один факт в двух полях — не ошибка. Не ошибка и факт, который не пришёл ни в одно поле, когда для него в бланке нет поля. Подробности в разделе Что попадает в поле.

#В МИС появились дубликаты приёмов

Ваш PUT не идемпотентен. Повторы приходят при обычной работе. Врач нажимает повтор отправки, дописывает приём, или протокол заполняют заново.

Ищите существующий приём по encounter_id и обновляйте приём. Не создавайте новую запись. Отправьте один и тот же запрос дважды курлом. В МИС должен остаться один приём.

Ещё одна причина. encounter_id переиспользуется для разных приёмов. Один ID принадлежит ровно одному приёму навсегда.

#После записи результата часть полей опустела

Вы очищаете поля, которых нет в массиве. Так делать нельзя. smartica.ai отдаёт только заполненные поля, не весь бланк. Поля, которых нет в fields, оставьте как есть.

Правило одно для входящего PUT при push и для протокола, который вы забираете при pull.

#Стенограмма приходит обрезанной

Проверьте ограничение на размер тела запроса на своей стороне: в веб-сервере, в прокси и в приложении. Длинный приём даёт объёмный текст. Рассчитывайте на несколько мегабайт.

#Текст приходит с испорченной кодировкой

Значения содержат кириллицу, переводы строк и могут содержать разметку списков. Убедитесь, что вся цепочка работает в UTF-8. Многострочный текст сохраняйте с переводами строк.

Если МИС показывает содержимое как HTML, экранируйте значения на своей стороне. Значения — обычный текст.

#Сценарий Import

#404 doctor_not_found

Врача с таким email нет в вашей клинике в smartica.ai. Создать врача в этом запросе не удалось. Проверьте:

• email указан без опечаток.
• вы передали user_full_name (в query для списка и в теле для import). Без ФИО нового врача завести нельзя.
• если ФИО передано, а ошибка остаётся, для клиники выключено автосоздание врачей. Напишите в поддержку smartica.ai.
• email не принадлежит врачу другой клиники. В этом случае приходит 403 email_in_other_organization.

#409 no_transcript

У записи ещё нет стенограммы. Расшифровка не закончилась, или запись пустая. Подождите и повторите запрос. В форме выбора показывайте врачу только записи со статусом awaiting_import. У этих записей стенограмма уже есть.

#409 encounter_taken

Этот encounter_id уже занят другой записью smartica.ai. Один приём МИС может быть связан только с одной записью.

Если привязка была ошибочной, используйте перепривязку с rebind: true на исходной записи. Не занимайте тот же ID второй записью.

#409 already_imported

Запись уже привязана к другому приёму МИС. Если перепривязка нужна, повторите запрос с rebind: true.

#409 revision_mismatch при подтверждении

Пока вы сохраняли протокол, smartica.ai успела перезаполнить протокол. Ваша копия устарела.

Заберите протокол заново. Обновите сохранённые данные. Подтвердите актуальную ревизию. Актуальный номер приходит в поле revision того же ответа с ошибкой.

Если ошибка повторяется постоянно, проверьте revision. Передавайте revision из последнего ответа, не старое сохранённое значение.

#410 encounter_deleted

Врач удалил запись в smartica.ai. Уберите запись из своей очереди. Ничего не сохраняйте.

#429 при опросе в режиме pull

Слишком частый опрос. Лимит на список — 60 запросов в минуту. Лимит на чтение — 120.

Частый опрос не ускоряет заполнение протокола. Не опрашивайте каждую запись отдельно. Запросите список по статусу ready одним запросом на врача.

#Как собрать информацию для поддержки

Если ничего не помогло, напишите на support@smartica.ai и приложите:

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

Не присылайте API-ключи, пароли, launch_url целиком и стенограммы с данными пациентов.

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

• Авторизация и ошибки
• Лимиты
• Ссылка для входа врача
• Запись вне МИС (Import)
• Поддержка