Описание ответов

Инструкция по обработке ответов сервера FHIR R5 для интеграции с МИС

Введение:

Данная инструкция предоставляет разработчикам медицинских информационных систем структурированное описание форматов и сценариев обработки ответов ЦИСЗ. Цель — обеспечить корректную интерпретацию HTTP-статусов, заголовков и тел ответов для построения устойчивой и соответствующей стандарту интеграции.

Первичным и основным источником информации является официальная документация HL7 FHIR R5.

Данная инструкция является адаптированным и структурированным руководством по взаимодействию с ЦИСЗ.

Общая структура HTTP-ответа:

Каждый ответ сервера состоит из трех ключевых компонентов:

• код состояния HTTP (Status Code);
• набор HTTP-заголовков (Headers);
• тело ответа (Body).

Понимание этой структуры обязательно для корректной обработки как успешных операций, так и ошибок.

HTTP-заголовки (Headers)

Сервер FHIR использует стандартные и специфические HTTP-заголовки для передачи метаинформации. Некоторые из них являются обязательными для определенных операций.

Обязательные заголовки (в зависимости от операции):

Content-Type: обязателен при наличии тела ответа. Указывает формат данных. Должен соответствовать запрошенному в заголовке Accept клиента или формату по умолчанию (application/fhir+json).

Пример: Content-Type: application/fhir+json; charset=utf-8.

Date: содержит дату и время (в формате HTTP-даты) создания сообщения, то есть момент, когда сервер сгенерировал и отправил ответ.

Date: <день-недели>, <день> <месяц> <год> <часы>:<минуты>:<секунды> GMT.

Пример: Tue, 15 Nov 2025 12:45:26 GMT.

Рекомендуемые заголовки:

Last-Modified: указывает дату и время последнего изменения ресурса (соответствует Resource.meta.lastUpdated). Может использоваться для кэширования. Формат: RFC-1123.

Пример: Last-Modified: Tue, 15 Nov 2025 12:45:26 GMT.

Тело ответа (ресурс, пакет Bundle или операционный исход OperationOutcome).

Успешные ответы (2xx):

200 OK

Успешное выполнение операции, которая не приводит к созданию новой версии ресурса на сервере. Тело ответа практически всегда присутствует.

Типичные сценарии и формат тела:

​Получение информации о пациенте (GET [FHIR_BASE]/[resource-type]/[id]).

Тело ответа: единичный ресурс FHIR (например, Patient, Observation).

Пример:

GET [FHIR_BASE]/Patient/example-id

HTTP/1.1 200 OK
Content-Type: application/fhir+json; charset=utf-8
Date: Mon, 01 Jan 2024 12:00:00 GMT
...

{
  "resourceType": "Patient",
  "id": "example-id",
  "meta": { ... },
  "active": true,
  "name": [ ... ]
  // ... остальные поля ресурса
}

Действия клиента: не требуются.

​Поиск информации о пациенте (GET [FHIR_BASE]/[resource-type]?[parameters]).

Тело ответа: ресурс Bundle с типом (Bundle.type) searchset. Содержит массив найденных ресурсов в Bundle.entry. Даже при 0 результатах возвращается пустой Bundle, а не ошибка 404 Not Found.

Пример:

GET [FHIR_BASE]/Patient?name=Иван

HTTP/1.1 200 OK
Content-Type: application/fhir+json; charset=utf-8
Date: Mon, 01 Jan 2024 12:00:00 GMT

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 42,
  "link": [
    {
      "relation": "self",
      "url": "https://internal.cisz.by/api/fhir/Patient?name=Иван"
    }
  ],
  "entry": [
    { "resource": { "resourceType": "Patient", "id": "pt1", ... } },
    { "resource": { "resourceType": "Patient", "id": "pt2", ... } }
    ...
  ]
}

Действия клиента: не требуются.

Операции ($status, $cancel, $get-document-id).

Тело ответа: ресурс Parameters.

КРИТИЧЕСКИ ВАЖНО: код 200 OK указывает только на успешный приём и выполнение логики операции сервером. Итоговый бизнес-результат операции (успех или неудача) содержится внутри тела ответа Parameters в выходных параметрах (например, в параметре ProcessingStatus).

Пример для $status:

GET [FHIR_BASE]/Bundle/[bundle-id]/$status

HTTP/1.1 200 OK
Content-Type: application/fhir+json; charset=utf-8
Date: Mon, 01 Jan 2024 12:00:00 GMT

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "ProcessingStatus",
      "valueCode": "Failed" // Бизнес-логика завершилась ошибкой
    },
    {
      "name": "StatusDescription",
      "resource": { // Детали ошибки в OperationOutcome
        "resourceType": "OperationOutcome",
        "issue": [ ... ]
      }
    }
  ]
}

Действия клиента: в зависимости от содержимого ответа. Для операции $status, где ProcessingStatus = Failed, необходимо проверить Bundle, который не импортировался, исправить ошибки и повторить импорт.

201 Created

Успешное создание нового ресурса в результате операции create (POST [FHIR_BASE]/[resource-type]). Сервер присваивает ресурсу логический id и версию.

Обязательные заголовки:

• Location: абсолютный URL созданного ресурса, включая его версию;
• ETag: номер версии созданного ресурса.

Формат тела: обычно содержит созданный ресурс с присвоенными сервером полями id и meta.versionId. Может отличаться от отправленного запросом, если сервер добавил или модифицировал данные.

POST [FHIR_BASE]/Resource

HTTP/1.1 201 Created
Location: https://[FHIR_BASE]/Resource/example-id/_history/1
ETag: W/"1"
Content-Type: application/fhir+json

{
  "resourceType": "Resource",
  "id": "new-resource-id", // ID присвоен сервером
  "meta": {
    "versionId": "1",
    "lastUpdated": "2025-01-01T12:00:00Z"
  },
  "status": "..."
  // ...
}

Действия клиента: не требуются.

202 Accepted

Запрос принят на асинхронную обработку. Это характерно для долгих операций, таких как $import.

Ключевые особенности:

• сервер подтверждает, что запрос корректен и поставлен в очередь на выполнение;
• немедленный результат операции недоступен;
• тело ответа: содержит ресурс Parameters, который включает параметры для отслеживания статуса (например, OperationStatusReference, ResourceId). На данном этапе статус обработки (ProcessingStatus) обычно имеет значение Pending;
• клиент обязан использовать механизм, предоставленный сервером (часто через последующий вызов $status с ResourceId), чтобы получить окончательный результат.

POST [FHIR_BASE]/Bundle/$import

HTTP/1.1 202 Accepted
Content-Type: application/fhir+json; charset=utf-8
Date: Mon, 01 Jan 2024 12:00:00 GMT

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "ProcessingStatus",
      "valueCode": "Pending"
    },
    {
      "name": "transactionTime",
      "valueInstant": "2024-01-01T12:00:00Z"
    }
  ]
}

Действия клиента: в зависимости от ответа и выполняемой операции. При $import и processingStatus = Pending, необходимо выполнить операцию $status через 10 секунд после получения ответа.

Ответы с ошибками клиента (4xx):

4xx/5xx с OperationOutcome

Даже в случае ошибок (коды 4xx и 5xx) структура ответа предсказуема. Сервер возвращает в теле ответа ресурс OperationOutcome со структурированным описанием проблемы. Клиентское приложение должно быть готово парсить OperationOutcome для любых ответов (в том числе и 200 ОК).

400 Bad Request

Запрос является семантически или синтаксически некорректным, и сервер не может его обработать.

Типичные сценарии:

• некорректный синтаксис JSON в теле запроса;
• отсутствует обязательный параметр для операции (например, параметр _profile для поиска);
• передан неизвестный или неподдерживаемый параметр поиска;
• неверный формат значения параметра (например, передана строка вместо числа для параметра _count);
• нарушение правил составления запроса, описанных в спецификации (например, неверная структура Bundle для импорта - несоответствие профилям, описанным в руководстве).

HTTP/1.1 400 Bad Request
Content-Type: application/fhir+json; charset=utf-8
Date: Thu, 22 Jan 2026 10:58:11 GMT

{
    "resourceType": "OperationOutcome",
    "id": "40520d3e-b868-4618-ac5c-a0ec7c98cec6",
    "meta": {
        "lastUpdated": "2026-01-22T10:58:12.196055+00:00"
    },
    "issue": [
        {
            "severity": "error",
            "code": "invariant",
            "details": {
                "coding": [
                    {
                        "system": "http://hl7.org/fhir/dotnet-api-operation-outcome",
                        "code": "1012"
                    },
                    {
                        "system": "http://fire.ly/dotnet-sdk-operation-outcome-structdef-reference",
                        "code": "Bundle(https://fhir.by/AbstractArea/StructureDefinition/Bundle/MedicationDocument)"
                    }
                ],
                "text": "Instance failed constraint bdl-9 \"Документ должен иметь identifier с system и  value\""
            },
            "diagnostics": "Resource was validated using fhir.by package with version 0.2.5810",
            "expression": [
                "Bundle, element Bundle(https://fhir.by/AbstractArea/StructureDefinition/Bundle/MedicationDocument)"
            ]
        }
    ]
}

В элементе OperationOutcome.issue.details.text указана причина возникшей ошибки.

ВАЖНО: для некоторых случаев OperationOutcome будет содержать несколько .issue и следующие значения issue[0].text:

"Referenced resource '' does not validate against any of the expected target profiles (https://fhir.by/StructureDefinition/PatientWithIdentificationNumber, https://fhir.by/StructureDefinition/PatientWithoutIdentificationNumber, https://fhir.by/StructureDefinition/AnonymousPatientBy)."

Как правило, валидатор не смог верно обработать вложенный ресурс и соответственно не сопоставил его с профилем, описанным в руководстве. Причиной этого могла послужить ошибка, описанная в issue с индексом 1. Исправление ошибок должно быть последовательным, начиная с issue[1]. Для отладки рекомендовано использовать операцию /Bundle/$validate в соответствующем окружении и с соответствующей версией (указывается в OperationOutcome.issue.diagnostics для операции $import или $validate).

OperationOutcome.issue содержат элементы severity и code. Возможно их использование для автоматической обработки ошибок, возникающих при импорте ресурсов. Описание кодов на сайте стандарта.

Часто встречающиеся значения для severity:

Часто встречающиеся значения для code:

Существует набор кодов для OperationOutcome.issue.details.coding.code.

Часто встречающиеся значения для OperationOutcome.issue.details.coding.code:

Для ошибок, возникающих при импорте при нарушении схемы JSON, будут возвращаться OperationOutcome, не содержащие конкретных кодов ошибок или явного указания проблемы, но в OperationOutcome.issue.diagnostics будет указана локализация проблемы.

Пример: попытка импорта ресурса Bundle с meta.profile с пустым массивом:

HTTP/1.1 400 Bad Request
Content-Type: application/fhir+json; charset=utf-8
Date: Thu, 22 Jan 2026 12:29:48 GMT

{
    "resourceType": "OperationOutcome",
    "id": "246e1693-b6c4-4ee6-ac9d-b5c97f15a63a",
    "meta": {
        "lastUpdated": "2026-01-22T12:29:48.9783401+00:00"
    },
    "issue": [
        {
            "severity": "error",
            "code": "invalid",
            "diagnostics": "One or more errors occurred. (An array needs to have at least one element. At Bundle.meta.profile[0], line 6, position 10)"
        }
    ]
}

Действия клиента: необходимо исправить запрос и/или содержимое запроса.

401 Unauthorized

Запрос требует аутентификации пользователя. Заголовок WWW-Authenticate: должен быть предоставлен, должен указывать на схему аутентификации.

Типичные сценарии:

• отсутствует заголовок Authorization;
• истек срок действия предоставленного токена доступа (OAuth2 Bearer token);
• неверный или поврежденный токен/учетные данные.

HTTP/1.1 401 Unauthorized
Content-Type: application/fhir+json; charset=utf-8
Date: Thu, 22 Jan 2026 10:58:11 GMT

{
    "resourceType": "OperationOutcome",
    "id": "7d42ddfe-10af-47fd-907c-1a1b7eeea833",
    "issue": [
        {
            "severity": "error",
            "code": "login",
            "diagnostics": "Authentication failed."
        }
    ]
}

Действия клиента: необходимо проверить авторизационные данные.

403 Forbiden

Недостаточно прав на выполнение операции.

Типичные сценарии:

• у пользователя отсутствует необходимая scope (право) для выполнения операции write на ресурсы типа Patient;
• попытка доступа к ресурсу, находящемуся вне разрешенной для пользователя области (например, к данным другого медицинского учреждения).

HTTP/1.1 403 Forbiden
Content-Type: application/fhir+json; charset=utf-8
Date: Thu, 22 Jan 2026 10:58:11 GMT

{
    "resourceType": "OperationOutcome",
    "id": "id",
    "meta": {
        "lastUpdated": "2026-01-22T10:58:11.0353476+00:00"
    },
    "issue": [
        {
            "severity": "error",
            "code": "forbidden",
            "diagnostics": "Идентификационный номер медицинского работника не соответствует номеру в подписи"
        }
    ]
}

Сообщения в OperationOutcome.issue.diagnostics:

• идентификационный номер медицинского работника не соответствует номеру в подписи;
• отсутствуют необходимые роли в токене;
• ссылка на организацию в ресурсе Composition не соответствует авторизованному пользователю.

Действия клиента: необходимо проверить авторизационные данные.

404 Not Found

Сервер не нашел ничего, соответствующего Request-URL. Не означает, что ресурс когда-либо существовал.

Типичные сценарии:

• запрос к несуществующему логическому ID ресурса (GET [FHIR_BASE]/Patient/nonexistent-id);
• запрос к неподдерживаемому типу ресурса (GET [FHIR_BASE]/UnsupportedResource);
• запрос к несуществующей конечной точке операции (POST [FHIR_BASE]/Patient/$unknown-operation).

ВАЖНО: пустой результат поиска (GET [FHIR_BASE]/Patient?identifier=unknown) не является ошибкой 404 Not Found. В этом случае возвращается 200 OK с пустым Bundle типа searchset.

Пример: ответ при неверно указанном Request-URL:

HTTP/1.1 404 Not Found
Content-Type: application/fhir+json; charset=utf-8
Date: Thu, 22 Jan 2026 10:58:11 GMT

{
    "resourceType": "OperationOutcome",
    "id": "6e9814b7-11a1-433d-829c-1d67ec789ed0",
    "issue": [
        {
            "severity": "error",
            "code": "not-found",
            "diagnostics": "The requested route was not found."
        }
    ]
}

Действия клиента: необходимо исправить запрос и/или содержимое запроса.

405 Not Allowed

Сервер не поддерживает данный запрос.

HTTP/1.1 405 Not Allowed
Content-Type: text
Date: Thu, 22 Jan 2026 10:58:11 GMT

Действия клиента: необходимо исправить запрос

406 NotAcceptable

Сервер не может вернуть представление ресурса в формате, запрошенном в параметре _format.

Пример: клиент запросил неподдерживаемый параметр:

HTTP/1.1 406 NotAcceptable
Content-Type: application/fhir+json; charset=utf-8
Date: Thu, 22 Jan 2026 12:23:44 GMT

{
    "resourceType": "OperationOutcome",
    "id": "b439d496-bf9c-4387-9da0-45e70ec4b5b9",
    "meta": {
        "lastUpdated": "2026-01-22T12:23:44.9743964+00:00"
    },
    "issue": [
        {
            "severity": "error",
            "code": "not-supported",
            "diagnostics": "The requested \"_format\" parameter is not supported."
        }
    ]
}

Действия клиента: необходимо исправить запрос.

409 Conflict

Указывает на конфликт, связанный с текущим состоянием целевого ресурса.

Типичный сценарий: клиент пытается обновить ресурс (PUT [FHIR_BASE]/Resource/[id]) с устаревшей версией.

Действия клиента: необходимо исправить запрос и/или содержимое запроса.

410 Gone

Запрашиваемый ресурс больше недоступен на сервере и не будет доступен в будущем. Это намеренное и постоянное удаление.

Действия клиента: необходимо исправить запрос и/или содержимое запроса.

Ответы с ошибками сервера (5xx):

500 Internal Server Error

Общая ошибка сервера, когда он столкнулся с ситуацией, которую не может обработать, и не может дать более конкретный код ответа.

HTTP/1.1 500 Internal Server Error
Content-Type: text/html
Date: Thu, 22 Jan 2026 12:23:44 GMT

<html> 
<head>
<title>500 Internal Server Error</title>
</head>
<body> 
<center>
<h1>500 Internal Server Error</h1>
</center> 
<hr><center>nginx/1.25.4</center> 
</body>
</html>

• необработанное исключение в коде серверного приложения;
• внезапная недоступность критической внутренней службы (база данных, сервис аутентификации);
• ошибка конфигурации сервера, которая проявляется только при выполнении определенной операции;
• внутренняя ошибка при обработке транзакции.

503 Service Unavailable

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

HTTP/1.1 503 Service Unavailable
Content-Type: text/plain
Date: Thu, 22 Jan 2026 12:23:44 GMT

upstream connect error or disconnect/reset before headers. reset reason: connection termination

Ключевые ресурсы в ответах:

Для корректной обработки ответов FHIR-сервера клиентское приложение должно уметь интерпретировать два ресурса: OperationOutcome (для сообщений об ошибках и дополнительной информации) и Bundle (для наборов данных, результатов поиска и пакетных операций).

OperationOutcome

Ресурс OperationOutcome используется для передачи деталей об успешном выполнении, предупреждениях или ошибках, возникших при обработке запроса. Это основной ресурс для диагностики проблем.

Cтруктура элементов:

• issue (обязательно): массив, содержащий одно или несколько сообщений. Каждый элемент имеет следующую структуру:

  • severity (обязательно): уровень серьезности проблемы. Возможные значения:
    • fatal: проблема привела к полному прекращению обработки запроса. Требует вмешательства клиента для исправления запроса. Соответствует кодам 4xx (кроме 429);
    • error: проблема привела к неудачному завершению операции, но обработка в целом была возможна. Соответствует большинству кодов 4xx и некоторым 5xx;
    • warning: операция выполнена, но могут быть нежелательные последствия. Клиенту следует обратить внимание. Соответствует кодам 200 OK или 201 Created, но с замечаниями;
    • information: информационное сообщение, не требующее действий.
  • code (обязательно): тип проблемы. Критически важен для автоматической обработки. Основные значения:
    • invalid: cодержимое запроса нарушает синтаксис или правила (базовую валидацию). Часто для кода 400;
    • structure / required / value: нарушение структурных правил профиля FHIR (отсутствие обязательного поля, несоответствие паттерну). Для кода 422;
    • security: проблема аутентификации/авторизации. Для кодов 401, 403;
    • processing / not-supported / duplicate / not-found / conflict: соответствуют кодам 422, 404, 409, 405 и т.д.
  • details (опционально): человекочитаемое описание проблемы. Поле text внутри details содержит основное сообщение;
  • diagnostics (опционально): отладочная информация для разработчика (например, часть SQL-запроса, стек-трейс в безопасном виде). Не предназначено для конечного пользователя;
  • location (опционально): указывает на элемент(ы) во входящем запросе, вызвавший(ие) проблему. Может содержать имя параметра (например, _count) или путь FHIR Path (например, Patient.name[0].family);
  • expression (опционально): указывает на элемент(ы) в результирующем ресурсе, к которому(ым) относится предупреждение или информация. Используется FHIR Path.

Bundle

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

Как правило ресурс Bundle имеет тип searchset: результат операции поиска (search). Содержит найденные ресурсы в элементе Bundle.entry.resource. Даже при 0 результатах (total = 0) возвращается Bundle этого типа.

Структура элементов:

• type (обязательно): определяет назначение Bundle (см. выше);
• total (опционально): общее количество совпадений по всему результату поиска (может быть больше количества ресурсов в текущей странице);

• link (опционально): массив ссылок для навигации, особенно для пагинации. Ключевые отношения (relation):

  • self: ссылка на текущую страницу результатов;
  • next: ссылка на следующую страницу результатов (при наличии);
  • previous: ссылка на предыдущую страницу.

• entry (опционально): массив записей. Каждая запись содержит:

  • resource: собственно ресурс FHIR (для searchset, history);

  • response: только для transaction-response и batch-response. Содержит результат обработки одной операции из пакета:

    • status: HTTP-статус код, который был бы возвращен, если бы операция выполнялась отдельно (например, 201 Created);
    • location: URL созданного/обновленного ресурса (если применимо);
    • outcome: ресурс OperationOutcome с деталями выполнения (особенно при ошибках).

Особенности обработки для операций:

Различные типы операций FHIR требуют специфического подхода к интерпретации ответов. Клиентское приложение должно корректно обрабатывать как содержимое тела ответа, так и метаданные, передаваемые через HTTP-заголовки и статусные коды.

Поиск (search):

Операция поиска выполняется через GET-запрос к коллекции ресурсов (например, GET [FHIR_BASE]/Patient?name=Иван). Ответ всегда возвращается с кодом 200 OK, если запрос синтаксически корректен.

• обработка пустого результата: при отсутствии совпадений сервер возвращает ресурс Bundle с типом searchset, где массив entry пуст, а поле total (если присутствует) равно 0. Это не является ошибкой;
• обработка частичных совпадений: cервер возвращает все ресурсы, соответствующие критериям поиска. Он не обязан уведомлять клиента, если какие-то критерии были интерпретированы нестрого или проигнорированы (например, из-за прав доступа). Анализ полноты и релевантности результатов лежит на клиенте;
• пагинация: клиент обязан проверять наличие ссылки с отношением next в Bundle.link. Для перехода на следующую страницу необходимо использовать предоставленный URL, не модифицируя его. Запрос следующей страницы является отдельным вызовом к серверу.

Краткое изложение

Эта таблица содержит обобщение описанных здесь взаимодействий. Обратите внимание, что все запросы могут включать необязательный заголовок Accept для указания формата ответа.

Обозначения:

R — требуется (Required);

O — опционально (Optional);

N/A — не применимо (Not Applicable).