Коннектор для лабораторий: как лабораторный отчет в формате HL7 v2, CSV или JSON превращается в FHIR Observations одним запросом

В лаборатории есть одна задача при интеграции: внести отчет в карту пациента без повторного ввода, без потери диапазона значений и без создания формата, который никто другой не читает. Коннектор лаборатории Anpheros принимает отчет в том виде, в котором лаборатория его уже производит (HL7 v2, CSV или JSON), и преобразует каждый результат в Observation FHIR с кодом LOINC, единицей измерения, диапазоном значений, датой и названием лаборатории в качестве исполнителя. Данное руководство является договором.

Техническая версия для разработчиков: Коннектор лаборатории · API результатов лабораторных исследований на developers.anpheros.com с запросами, ответами и ограничениями. Эта страница — версия для широкой аудитории.

Один запрос

POST /v1/patients/{patient_id}/labs/import
Authorization: Bearer <project key>
Content-Type: text/csv | x-application/hl7-v2+er7 | application/json
X-Anpheros-Source-System: labx        (необязательно; записывается в Provenance)
Idempotency-Key: <report id>          (необязательно; повторный запрос вернет тот же ответ)

Ответ сообщает, что произошло:

{"created": 3, "skipped": 0, "unmapped": ["Marker foarte rar"], "warnings": [],
 "observations": [{"id": "…", "marker": "TSH", "code": "3016-3", "system": "http://loinc.org",
                   "value": 2.1, "unit": "mUI/L", "date": "2026-09-01"}]}

Форматы

HL7 v2 ORU^R01, в виде текста ER7. OBX-3 — идентификатор (code^text^LN — LOINC; локальный код сохраняется как собственный код лаборатории), OBX-5 — значение, OBX-6 — единица измерения, OBX-7 — диапазон значений, OBX-8 — флаг аномальности (становится interpretation), OBX-11 — статус, OBX-14 или OBR-7 — дата. MSH-4 указывает отправляющее учреждение, которое становится исполнителем; OBR-3 и MSH-10 становятся идентификатором отчета в Provenance. Результаты в ожидании, удаленные или неверные (I, X, D, W) и сегменты OBX без значения не становятся Observations и указываются в warnings.

CSV с заголовком; разделители , ; или табуляция, десятичная запятая принимается, даты в формате ISO, DD.MM.YYYY или DD/MM/YYYY. Распознаваемые столбцы на румынском или английском языках: marker, value, unit, reference range (70-100, <5, >3.5) или ref_low/ref_high, date, необязательный код LOINC, note. CSV не содержит информации о лаборатории, поэтому исполнитель отсутствует, если вы не отправите X-Anpheros-Acting-As.

Analiza;Rezultat;UM;Interval de referinta;Data
Hemoglobina glicozilata (HbA1c);6,4;%;4,0-5,6;01.09.2026
TSH;2,1;mUI/L;0,4-4,0;01.09.2026

JSON, если у вас уже есть структурированные данные: {"date": "2026-09-01", "origin": "report-77", "laboratory": "Synevo", "items": [{"marker": "TSH", "value": 2.1, "unit": "mUI/L", "ref_low": 0.4, "ref_high": 4.0, "code": "3016-3"}]}.

Важные правила сопоставления

• LOINC при наличии, иначе по названию. Названия сопоставляются с названиями и синонимами LOINC на румынском и английском языках. Название, которое соответствует нескольким понятиям или имеет квалификатор, которого нет у понятия (моча, не-ЛПНП, свободный, соотношение), не угадывается: оно сохраняет собственный код лаборатории под urn:anpheros:lab-code и появляется в unmapped, чтобы вы могли улучшить сопоставление на своей стороне. Отправляйте коды LOINC, когда они у вас есть.
• Значения никогда не преобразуются. Мочевина и азот мочевины — это разные коды; прямые ЛПНП и рассчитанные ЛПНП — разные коды; глюкоза из сыворотки и из капиллярной крови — разные коды. Коннектор выбирает правильный код по названию и методу и оставляет число без изменений.
• Времена сохраняют свою зону. Время v2 с смещением сохраняется; без него используется смещение MSH-7 с предупреждением; если нигде нет смещения, сохраняется только дата. Времена CSV не содержат зоны и сохраняются как даты.
• Идемпотентность. Отправьте один и тот же отчет дважды с одним и тем же Idempotency-Key, и вы получите один и тот же ответ и никаких дубликатов.
• Provenance для каждого результата: исходная система, идентификатор отчета и исполнитель, как того требует HL7 Europe Laboratory Report.

Что видит пациент

Результаты появляются в карте человека и, если он использует Anpheros Daily, на его телефоне по мере поступления, с диапазоном значений и динамикой по предыдущим отчетам. Ничего сканировать, ничего перепечатывать не нужно. Если результат аномальный, человек видит флаг; приложение его не интерпретирует.

Тестирование

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

curl -X POST "$BASE/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: text/csv" --data-binary @report.csv
curl "$BASE/fhir/R4/Observation?patient=$PID&category=laboratory&_sort=-date" -H "Authorization: Bearer $KEY"

Полная спецификация, включая примечания по соответствию HL7 Europe, доступна по адресу developers.anpheros.com/guides/lab-connector.

Частые вопросы

Должны ли мы менять то, что производит наша ЛИС?

Нет. Отправляйте сообщение ORU^R01 или экспорт CSV как есть. Если вы можете добавить коды LOINC, сделайте это; в противном случае коннектор сопоставляет по названию и сообщает вам, что не смог сопоставить.

Что делать с результатами, которые вы не можете сопоставить?

Они сохраняются с собственным кодом лаборатории и точным текстом из отчета, поэтому ничего не теряется, и перечисляются в unmapped, чтобы вы могли добавить код LOINC в следующий раз.

Сохраняются ли диапазоны значений и флаги аномальности?

Да: диапазон идет в referenceRange, флаг — в interpretation, единица измерения сохраняется как UCUM, а значение никогда не преобразуется.

Может ли лаборатория отправлять результаты для пациента, которого она не создавала?

Только с согласия человека или от имени организации, за которую действует проект, с использованием X-Anpheros-Acting-As. Проект видит созданных им пациентов; все остальное требует разрешения.

Есть ли плата за интеграцию?

Песочница бесплатна. Производство начинается с 49 евро в месяц за организацию, первый месяц бесплатно; см. цены.