#Лимиты

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

#Форматы и длины полей

Поле	Ограничение
`encounter_id`	Строка до 255 символов. Только цифры или UUID в форме 8-4-4-4-12
`user_email`	Корректный email до 255 символов. Регистр не учитывается
`user_full_name`	Непустая строка до 255 символов
`template`	До 255 символов
`fields`	До 80 элементов в массиве
`fields[].id`	До 128 символов, непустой, уникальный внутри бланка
`fields[].label`	До 255 символов, непустой
`max_length` у `text`	По умолчанию 5000 символов. Меньше указать можно. Больше 5000 бланк не примет. Текст длиннее предела не отправляется
`max_length` у `string`	По умолчанию 500 символов, одна строка без переводов. Меньше указать можно. Больше 500 бланк не примет
`fields[].options`	Не больше 100 вариантов прямо в бланке. Более длинный список передайте справочником. Статья Справочники
Справочник `value-sets`	От 2 до 1000 элементов и до 8 МБ. В заполнение приёма целиком не передаётся. Один элемент и пустой справочник не принимаются
`fields[].value` в статье Протокол после правки врача	До 20 000 символов. Пустая строка допустима
`transcript` в сохранённой версии	До 200 000 символов, поле необязательное
`cursor`	До 512 символов

Превышение любого значения из таблицы вернёт 422. Разбивка по полям лежит в объекте errors.

В таблице только уникальность fields[].id не приводит к 422. Если в бланке два поля с одним id, приём врача не срывается. Мы берём первое вхождение и пропускаем остальные. В ответе мы возвращаем предупреждение duplicate_field_id. Подробности в статье Глоссарий.

#Частота запросов к smartica.ai

Лимиты считаются на пару «клиника + ключ», в минуту.

Запрос	Лимит
Получение SSO-ссылки	30 в минуту
Список записей	60 в минуту
Готовый протокол, привязка, подтверждение	120 в минуту

Неудачные попытки авторизации ограничены 30 в минуту на клинику. Если сработал этот лимит, ключ неверен. Перебор ключей не снимает лимит. Проверьте секрет.

При превышении приходит 429 с заголовком Retry-After. Дождитесь указанного времени. Не запускайте цикл немедленных повторов. Цикл продлевает блокировку.

#Частота опроса при `pull`

Лимит в 60 запросов к списку в минуту задаёт потолок, не целевую частоту. Частый опрос не ускоряет заполнение протокола. Как опрашивать список, описано в статье Если запросы не проходят.

#Время жизни и задержки

Что	Значение
Одноразовая ссылка для входа врача	60 секунд
Задержка перед началом заполнения после остановки записи	около 5 секунд
Timeout запросов smartica.ai к вашей МИС	30 секунд
Окно действия предыдущего ключа при ротации	72 часа

Время жизни ссылки приходит в поле expires_in ответа. Срок в ответе может отличаться от 60 секунд.

Timeout в 30 секунд задаёт верхний предел. После 30 секунд мы считаем запрос неуспешным. GET и PUT за доли секунды читают готовые данные и сохраняют payload. Тяжёлая обработка начинается после того, как вы приняли данные и ответили 200.

#Окно списка записей

Что	Значение
Глубина списка по умолчанию	30 дней
Максимальная глубина через `since`	90 дней
Размер страницы по умолчанию	50 записей
Максимальный размер страницы	100 записей

Запрос с since глубже 90 дней вернёт 422. Записи старше 90 дней через партнёрский API недоступны.

#Лимит перезаполнений

Один приём можно перезаполнить не более 10 раз. Счётчик растёт каждый раз, когда протокол генерируется заново, например когда врач дописывает приём.

При достижении лимита приём переходит в статус failed.

#Сохранённые версии протокола

На один приём можно сохранить не больше 100 версий. В эти 100 версий входят протоколы, которые smartica.ai отдала в МИС, и версии, которые вы прислали после сохранения у себя. Повтор последней сохранённой версии этой ревизии новую версию не тратит. При превышении приходит ответ 409 version_limit. Уже сохранённые версии остаются.

В запросе сохранённой версии повторяющийся fields[].id даёт ошибку 422. Для бланка при привязке и в SSO дубли не роняют запрос. Мы берём первое вхождение.

#Ротация ключа

При выпуске нового API-ключа клиники предыдущий продолжает работать 72 часа. За эти 72 часа новый ключ должен стоять во всех окружениях вашей МИС.

После 72 часов старый ключ перестаёт действовать. SSO возвращает 401. При pull протоколы перестают забираться.

#Телефонные звонки

Запись разговора и стенограмма описаны в статье Транскрибация телефонных звонков. Это не приём и не протокол.

Что	Ограничение
Файл	`mp3` и `wav`, до 150 МБ и 30 минут. Удаляется через 24 часа
`phone_call_id`	До 255 символов. Необязателен
Текст стенограммы	Доступен через `GET`, пока хранится запись о звонке, 30 дней
Запись о звонке	30 дней, затем `phone_call_id` можно использовать снова

Файл длиннее 30 минут — 422 audio_too_long. Нечитаемый файл — 422 audio_unreadable.

#Что не входит в контракт

Что	Статус
Аудиофайл записи	Не передаётся. Передача возможна только как отдельное расширение
Персональные данные пациента	Не передаются. Передавать персональные данные пациента нельзя
Заголовок `Idempotency-Key`	Не используется. Ключом операции служит `encounter_id`
Массовая привязка нескольких записей одним запросом	Не поддерживается. Привязка идёт по одной записи
Отдельный запрос за списком бланков	Не нужен. Бланк передаётся в теле запроса
Гарантированная повторная доставка на каждую ошибку	Не гарантируется. См. ниже
Гарантия ровно одной доставки	Не гарантируется. Ваш `PUT` должен быть идемпотентным по `encounter_id`

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

Контракт не гарантирует автоматический повтор каждого неуспешного запроса. Повтор происходит так:

После ошибки GET врач заново открывает приём.
После ошибки PUT врач нажимает повтор отправки в интерфейсе smartica.ai.
Новая запись или перезаполнение в том же приёме создаёт новый PUT.

PUT должен быть идемпотентным по encounter_id. МИС не должна рассчитывать на фиксированное число попыток.

Подробности в статье Авторизация и ошибки.

#Требования к вашему endpoint

Требование	Обязательность
HTTPS с публично доверенным сертификатом	Обязательно
Ответ `200` с валидным JSON-объектом	Обязательно
Кодировка UTF-8, поддержка многострочного текста	Обязательно
Ответ `204`, пустое тело или HTML	Считается ошибкой интеграции
Поддержка тела запроса в несколько мегабайт	Желательно. Длинная стенограмма бывает объёмной