#Диагностика: если что-то не работает

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

#Сначала проверьте базовое

Больше половины проблем на старте объясняются одним из пяти пунктов:

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

#Запросы к Smartica

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

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

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

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

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

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

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

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

Что делать: показать врачу текст из поля message и обратиться в поддержку Smartica для переноса аккаунта.

Частый случай: врач раньше регистрировался в Smartica сам, до подключения клиники.

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

Интеграция для этой организации выключена или не разрешено автоматическое создание врачей. Решается только на стороне Smartica — напишите в поддержку.

#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 из сессии текущего пользователя, а не из тела запроса браузера и не из карточки приёма, где может стоять другой врач.

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

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

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

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

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

Это валидная ситуация, а не ошибка. Smartica присылает только те поля, для которых нашлось содержательное значение. Пустые значения и заглушки вроде «не указано» отбрасываются.

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

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

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

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

Правила и примеры — в разделе про fields статьи GET: контекст приёма.

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

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

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

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

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

Вы очищаете поля, которых нет в массиве. Так делать нельзя: Smartica отдаёт только заполненные поля, а не весь бланк целиком. Всё, чего нет в fields, должно остаться нетронутым.

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

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

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

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

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

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

#Сценарий Import

#404 doctor_not_found

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

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

#409 no_transcript

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

#409 encounter_taken

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

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

#409 already_imported

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

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

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

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

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

#410 note_deleted

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

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

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

Достаточно опрашивать раз в 30–60 секунд: заполнение всё равно занимает от десятков секунд. Не опрашивайте каждую запись по отдельности — запросите список по статусу ready одним запросом.

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

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

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

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

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

• Авторизация, ошибки и повторная доставка
• Лимиты и ограничения
• Launch URL и SSO
• Import: импорт из Smartica
• Связаться с поддержкой