#Типы полей бланка

Поля бланка хранят разные данные. В «Жалобах» лежит абзац текста, в «Температуре» число, в «Дате следующего визита» дата, в «Группе здоровья» один вариант из списка. Тип поля говорит smartica.ai, в каком виде вернуть значение в протоколе. Тогда МИС записывает значение без разбора: число приходит числом, дата строкой YYYY-MM-DD, вариант из списка своим кодом.

Тип задаётся атрибутом type у поля. Передать его можно в Launch, в Import и в бланке, который smartica.ai запрашивает у вас. Поле без type приходит текстом с разметкой Markdown.

Для полей с измерениями сначала посмотрите медицинские величины. Для температуры, давления, пульса, роста, веса и частых анализов там есть готовые пресеты. Список собран по справочникам Минздрава России: «Витальные параметры» из ФНСИ и Федеральному справочнику лабораторных исследований (ФСЛИ). У каждого пресета указан код из этих справочников, по нему пресет легко сопоставить с полем вашей МИС. Укажите у поля preset, и smartica.ai сама подставит тип, единицу и границы.

Каждое новое поле проверьте до первого приёма запросом из раздела Проверка бланка. Позже smartica.ai об ошибке в схеме уже не сообщит.

#Типы

Каждый тип описан ниже в своём разделе. В разделе есть таблица атрибутов, пример поля в бланке и то же поле в протоколе. В протоколе у поля остаются только id и value. unit, min, max и options в протокол не попадают.

Атрибуты id, label, section и hint есть у любого типа. Они повторены в таблице каждого раздела.

label — это подпись поля, как на бланке врача. По ней smartica.ai понимает, что искать в разговоре. Подпись «Жалобы» понятна сама по себе. Подпись «Норма» без раздела непонятна. Напишите в label «Объективный статус. Норма» или передайте раздел отдельно в section.

id должен быть уникальным внутри бланка. Если у двух полей один id, smartica.ai заполняет первое поле и пропускает остальные. Ответа 422 при этом нет, но в warnings приходит код duplicate_field_id.

Неизвестный type, например widget, smartica.ai считает текстом и добавляет в warnings код unknown_field_type.

Для полей с измерениями тип можно не задавать. Достаточно указать preset, подробнее в разделе Медицинские величины.

#Текст

text — свободный текст из одного или нескольких абзацев, например «Жалобы» или «Анамнез». Это тип по умолчанию: поле без type тоже текст.

format задаёт, в каком виде придёт текст. По умолчанию это Markdown, и разметка в value сохраняется.

{
  "id": "complaints",
  "label": "Жалобы"
}

{
  "id": "complaints",
  "value": "**Кашель** с мокротой."
}

plain убирает разметку. Звёздочек в value нет. Абзацы разделены пустой строкой, а пункт списка начинается с «- ».

{
  "id": "complaints",
  "label": "Жалобы",
  "type": "text",
  "format": "plain"
}

{
  "id": "complaints",
  "value": "Кашель с мокротой."
}

html отдаёт текст тегами p, br, ul, ol, li, strong и em. Других тегов, атрибутов и скриптов в значении нет.

{
  "id": "complaints",
  "label": "Жалобы",
  "type": "text",
  "format": "html"
}

{
  "id": "complaints",
  "value": "<p><strong>Кашель</strong> с мокротой.</p>"
}

Выше три варианта одного поля. В бланке у поля только один format.

#Строка

string — одна короткая строка без разметки, например «Профессия» или «Основная жалоба». Переводы строк и разметка из ответа пропадают. Для абзацев используйте text.

{
  "id": "complaint_short",
  "label": "Жалоба",
  "type": "string"
}

{
  "id": "complaint_short",
  "value": "Кашель с мокротой."
}

#Целое число

integer — целое число, например вес в килограммах или число беременностей.

{
  "id": "weight",
  "label": "Вес",
  "type": "integer",
  "min": 1,
  "max": 300,
  "unit": "кг"
}

{
  "id": "weight",
  "value": 72
}

unit — единица, в которой ваша МИС хранит число. Поле «Рост» с unit «см» и поле «Рост» с unit «м» получат разные числа. Если врач назвал другую единицу той же величины, smartica.ai пересчитает число в unit поля. «1,5 л» в поле с unit «мл» придёт числом 1500.

Если число меньше min или больше max, поле приходит в skipped с причиной out_of_range.

Дробный ответ smartica.ai не округляет. 72.4 в поле integer в протокол не попадёт. Если нужны дроби, используйте decimal.

Ответ с несколькими числами или с границей вместо значения тоже не попадает в протокол. Это, например, «2–3», «120/80» или «до 38». smartica.ai не выбирает одно число за врача. Поле приходит в skipped с причиной not_a_number, а в text лежат слова врача.

{"id": "resp_rate", "reason": "not_a_number", "text": "18–20"}

Если ваша МИС хранит такие ответы, объявите поле как string. Тогда «18–20» придёт в value строкой.

#Десятичное число

decimal — число с дробной частью, например температура или результат анализа.

{
  "id": "temperature",
  "label": "Температура",
  "type": "decimal",
  "precision": 1,
  "min": 34,
  "max": 42,
  "unit": "°C"
}

{
  "id": "temperature",
  "value": 37.8
}

precision — число знаков после запятой. Ответ «37,8» при precision 1 приходит числом 37.8. Ответ с большим числом знаков smartica.ai округляет до precision.

unit, min и max работают так же, как у целого числа. Диапазон вроде «37–38» decimal тоже не принимает. Поле приходит в skipped с причиной not_a_number и словами врача. Если такой ответ нужен в протоколе, объявите поле как string.

#Логическое значение

boolean — ответ «да» или «нет», например «Аллергия есть» или «Курит».

{
  "id": "allergy",
  "label": "Аллергия есть",
  "type": "boolean"
}

{
  "id": "allergy",
  "value": false
}

false приходит в протокол и означает ответ «нет». Если врач об этом не говорил, поле приходит в skipped с причиной no_data.

В value у boolean только true или false. Свои подписи, например «было» и «не было», передать нельзя. Для них используйте select с двумя вариантами в options. Тогда в value придёт ваш код, а в label подпись.

#Дата

date — дата, например начало заболевания или следующий визит.

Дата приходит строкой YYYY-MM-DD. Врач говорит «3 ноября 2026», в протоколе 2026-11-03. Неполная дата, например «с марта», в протокол не попадает.

{
  "id": "onset",
  "label": "Начало заболевания",
  "type": "date"
}

{
  "id": "onset",
  "value": "2026-11-03"
}

#Время

time — время суток, например время осмотра.

Время приходит строкой HH:MM, без секунд. Ответ «9:05» приходит как 09:05.

{
  "id": "visit_time",
  "label": "Время осмотра",
  "type": "time"
}

{
  "id": "visit_time",
  "value": "09:05"
}

#Список

select — выбор из заданных вами вариантов, например сторона, группа здоровья или общее состояние.

Варианты задаются одним из двух способов:

• options — список прямо в поле. Подходит для короткого списка.
• value_set — имя справочника, который вы загрузили заранее. Подходит для длинного списка и для списка, общего для нескольких бланков.

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

#Варианты в поле

Каждый вариант в options состоит из value и label. value — ваш код варианта, label — его подпись. В одном поле не больше 100 вариантов, и value в них не повторяются.

{
  "id": "side",
  "label": "Сторона",
  "type": "select",
  "options": [
    {"value": "left", "label": "Слева"},
    {"value": "right", "label": "Справа"}
  ]
}

Врач сказал «слева». В протокол приходят код и подпись выбранного варианта.

{"id": "side", "value": "left", "label": "Слева"}

Здесь label — подпись выбранного варианта, а не название поля.

Поле без multiple принимает один вариант. Если врач назвал несколько, главный приходит в value, а остальные в extra_values того же поля.

{
  "id": "side",
  "value": "left",
  "label": "Слева",
  "extra_values": [
    {"value": "right", "label": "Справа"}
  ]
}

#Справочник

С value_set поле ссылается на справочник по имени. Справочник загружается заранее, отдельным запросом. smartica.ai берёт слова врача и сама находит для них вариант в справочнике, с учётом синонимов. Подпись в протоколе берётся из справочника. Это справочник вариантов для полей бланка, а не справочник направлений и услуг.

{
  "id": "condition",
  "label": "Состояние",
  "type": "select",
  "value_set": "conditions"
}

{
  "id": "condition",
  "value": "good",
  "label": "Удовлетворительное"
}

Размер справочника и другие пределы описаны в статье Справочники.

#Несколько вариантов

Чтобы получить несколько вариантов, передайте multiple со значением true. Тогда value приходит массивом. Первым в массиве идёт основной вариант.

{
  "id": "conditions",
  "label": "Состояние",
  "type": "select",
  "multiple": true,
  "value_set": "conditions"
}

{
  "id": "conditions",
  "value": [
    {"value": "good", "label": "Удовлетворительное"},
    {"value": "poor", "label": "Тяжёлое"}
  ]
}

#Ответ не из списка

Если слова врача не подошли ни к одному варианту, поле приходит в skipped с причиной not_in_options. Чтобы вместо этого получить слова врача, передайте allow_other со значением true. В протоколе будет текст врача и признак "other": true.

{
  "id": "general_condition",
  "label": "Общее состояние",
  "type": "select",
  "allow_other": true,
  "options": [
    {"value": "good", "label": "Удовлетворительное"},
    {"value": "poor", "label": "Тяжёлое"}
  ]
}

{
  "id": "general_condition",
  "value": "Вялый",
  "label": "Вялый",
  "other": true
}

Если врач назвал несколько вариантов, "other": true стоит только у тех, которых нет в списке. Это касается и элементов extra_values, и массива value у поля с multiple.

{
  "id": "conditions",
  "value": [
    {"value": "good", "label": "Удовлетворительное"},
    {"value": "Вялый", "label": "Вялый", "other": true}
  ]
}

allow_other работает и со справочником. Если справочник с таким именем ещё не загружен, поле с allow_other тоже получит слова врача. Без allow_other такое поле придёт в skipped с причиной value_set_missing.

smartica.ai отвечает 422, если у select нет ни options, ни value_set. Тот же ответ приходит, если указаны оба.

#Таблица

table — таблица с заданными вами столбцами, например препараты и дозы.

Столбец описывается почти как поле. Атрибуты столбца:

В ячейке столбца select один вариант. Поэтому multiple у столбца даёт ответ 422.

format задаёт вид таблицы в протоколе. Неизвестный format smartica.ai заменяет на markdown и добавляет в warnings код unknown_text_format.

Без format таблица приходит строкой Markdown. Шапка собирается из label столбцов.

{
  "id": "dosage",
  "label": "Дозировка",
  "type": "table",
  "columns": [
    {"id": "who", "label": "Кому", "type": "string"},
    {"id": "dose", "label": "Доза, мг", "type": "integer"}
  ]
}

Так выглядит value:

| Кому | Доза, мг |
| --- | --- |
| Взрослый | 500 |
| Ребёнок | 250 |

С format html то же поле приходит строкой HTML. В ней только теги table, thead, tbody, tr, th и td, без атрибутов и стилей.

{
  "id": "dosage",
  "value": "<table><thead><tr><th>Кому</th><th>Доза, мг</th></tr></thead><tbody><tr><td>Взрослый</td><td>500</td></tr><tr><td>Ребёнок</td><td>250</td></tr></tbody></table>"
}

С format array то же поле приходит объектом. В cols один раз перечислены названия столбцов. В rows лежат строки, ячейки идут в порядке столбцов. Число остаётся числом, а пустая ячейка приходит как null. Вариант из списка или справочника приходит подписью.

{
  "id": "dosage",
  "value": {
    "cols": ["Кому", "Доза, мг"],
    "rows": [
      ["Взрослый", 500],
      ["Ребёнок", 250]
    ]
  }
}

Пример со справочником в столбце. У столбца «Препарат» указан value_set, а в ячейке приходит подпись варианта.

{
  "id": "drug_dose",
  "label": "Назначение",
  "type": "table",
  "format": "array",
  "columns": [
    {"id": "drug", "label": "Препарат", "type": "select", "value_set": "drugs"},
    {"id": "dose", "label": "Доза, мг", "type": "integer"}
  ]
}

{
  "id": "drug_dose",
  "value": {
    "cols": ["Препарат", "Доза, мг"],
    "rows": [
      ["Амоксициллин", 500]
    ]
  }
}

smartica.ai отвечает 422, если у таблицы нет columns или указан allow_other. Для столбца select действуют те же правила, что для поля select. Нужен options или value_set, но не оба сразу.

#Медицинские величины

Для температуры, давления, пульса, роста, веса и частых анализов укажите preset, и поле готово. type, unit, precision, min и max smartica.ai подставит сама.

{"id": "temp", "label": "Температура", "preset": "body_temperature"}

В протоколе такое поле приходит числом, как обычный decimal.

{"id": "temp", "value": 37.8}

Список всех величин с границами, правила для своих значений поверх пресета, давление и коды ФНСИ, ФСЛИ и LOINC собраны на странице Медицинские величины.

#Проверка бланка

Запрос POST /api/v1/integrations/{platform}/fields/validate только проверяет схему бланка. Приём не создаётся, запись не открывается, протокол не заполняется.

Категорически рекомендуем проверять так каждое новое поле до того, как бланк попадёт в приём.

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

Запрос подписывается тем же ключом клиники, что и остальные запросы к smartica.ai.

POST /api/v1/integrations/{platform}/fields/validate
Authorization: Bearer <API-ключ клиники>
Content-Type: application/json
Accept: application/json

{
  "template": "Терапия",
  "fields": [
    {
      "id": "note",
      "label": "Примечание",
      "type": "text",
      "max_length": 9000
    }
  ]
}

У текста max_length не больше 5000, поэтому ответ 422. В fields ответа попадают только поля без ошибок. Здесь поле одно, и список пуст. Путь fields.0 указывает на поле в вашем запросе, а не в ответе.

{
  "template": "Терапия",
  "fields": [],
  "errors": [
    {
      "path": "fields.0.max_length",
      "message": "max_length — целое от 1 до 5000."
    }
  ],
  "warnings": []
}

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

warnings означает, что smartica.ai приняла бланк, но что-то в нём поправила. Предупреждение само по себе не даёт 422. Если ошибок нет, ответ 200. Если ошибки есть, предупреждения приходят вместе с errors, а код ответа 422.

Предупреждение приходит в пяти случаях:

• В type значение не из списка типов, например widget. smartica.ai считает такое поле текстом. Поле без type или с пустым type сюда не входит, это обычный текст. Код unknown_field_type.
• В format значение, которого у типа нет. У text допустимы markdown, plain и html, у table ещё array. smartica.ai ставит markdown. У string формата нет, и format у строки предупреждения не даёт. Код unknown_text_format.
• В options больше 100 вариантов. В схеме остаются первые 100. Код option_limit.
• У двух полей один id. smartica.ai заполняет первое поле и пропускает остальные. Код duplicate_field_id.
• В preset имя не из списка медицинских величин. smartica.ai разбирает поле по type, как будто preset нет. Код unknown_preset.

Прочитайте warnings. Если поправка вам не подходит, исправьте бланк сами. Иначе в приём уйдёт поправленная схема.

Запрос ниже вызывает четыре предупреждения из пяти:

• у note неизвестные type и format;
• второе поле повторяет id note;
• у side в options 101 вариант;
• у dose неизвестный format таблицы.

В примере показаны первые два варианта side. Остальные устроены так же, value от v3 до v101.

{
  "template": "Терапия",
  "fields": [
    {
      "id": "note",
      "label": "Примечание",
      "type": "widget",
      "format": "rtf"
    },
    {
      "id": "note",
      "label": "Примечание повтор",
      "type": "text"
    },
    {
      "id": "side",
      "label": "Сторона",
      "type": "select",
      "options": [
        {"value": "v1", "label": "Вариант 1"},
        {"value": "v2", "label": "Вариант 2"}
      ]
    },
    {
      "id": "dose",
      "label": "Доза",
      "type": "table",
      "format": "csv",
      "columns": [
        {"id": "who", "label": "Кому", "type": "string"}
      ]
    }
  ]
}

Ответ 200. Второго note в fields нет. У side остаются первые 100 вариантов. В примере ответа массив options у side не показан, в нём первые 100 вариантов из запроса. Неизвестный format у текста и у таблицы приходит одним предупреждением, и в field_ids оба поля.

{
  "template": "Терапия",
  "fields": [
    {
      "id": "note",
      "label": "Примечание",
      "type": "text",
      "format": "markdown"
    },
    {
      "id": "side",
      "label": "Сторона",
      "type": "select"
    },
    {
      "id": "dose",
      "label": "Доза",
      "type": "table",
      "format": "markdown",
      "columns": [
        {"id": "who", "label": "Кому", "type": "string"}
      ]
    }
  ],
  "errors": [],
  "warnings": [
    {
      "code": "duplicate_field_id",
      "field_ids": ["note"],
      "message": "Несколько полей с одинаковым id: note. Заполнили первое, остальные пропустили. Сделайте id уникальными внутри бланка."
    },
    {
      "code": "unknown_field_type",
      "field_ids": ["note"],
      "message": "Неизвестный type у полей: note. Считаем их текстом."
    },
    {
      "code": "unknown_text_format",
      "field_ids": ["note", "dose"],
      "message": "Неизвестный format у полей: note, dose. Используем markdown."
    },
    {
      "code": "option_limit",
      "field_ids": ["side"],
      "message": "У полей side больше 100 вариантов. Оставили первые, остальные передайте справочником."
    }
  ]
}

Если в запросе нет template или у поля нет id или label, ответ тоже 422, но другого вида. В нём error равен validation_failed, а errors приходит объектом с текстами ошибок по полям. Схемы в таком ответе нет.

Ошибки, из-за которых smartica.ai отклоняет бланк, перечислены в разделе Ошибки схемы. Если отправить такой бланк в Launch или Import, запрос может завершиться 422, и приём не начнётся. Для врача это уже поздно.

#Ошибки схемы

Launch, Import и проверка бланка отвечают 422, если схема хотя бы одного поля неверна. smartica.ai отклоняет бланк в таких случаях:

• у select нет ни options, ни value_set;
• у select указаны и options, и value_set;
• min больше max;
• в options повторяется value;
• у table нет columns;
• у table указан allow_other;
• preset не подходит к type, например body_temperature у text;
• max_length не целое, у string больше 500 или у text больше 5000.

Когда smartica.ai сама запрашивает бланк у вашей МИС, ответить 422 некому. Тогда smartica.ai пропускает неверное поле и заполняет остальные.

#Пропущенные поля

Поля, которые smartica.ai не заполнила, приходят в массиве skipped рядом с fields. Массив есть и в протоколе, который smartica.ai присылает вам запросом PUT, и в ответе, когда вы забираете готовый протокол сами.

{"id": "temperature", "reason": "no_data"}

reason объясняет, почему поле не заполнено. Если врач говорил о поле, но ответ не подошёл, в элементе есть ещё text. Это слова врача без разметки. Несколько формулировок разделены «; ». При no_data поля text нет.

{"id": "condition", "reason": "not_in_options", "text": "Состояние средней тяжести, вялый"}

Как обращаться с skipped:

• Не записывайте поля из skipped в карту и не очищайте их.
• Не записывайте text в поле с кодом из справочника. Покажите его врачу рядом с пустым полем, чтобы врач выбрал вариант сам.

#См. также

• Медицинские величины
• Справочники
• Запись протокола в карту
• Готовый протокол
• Протокол после правки врача
• Лимиты