# 实验室连接器

> 以 CSV、HL7 v2 ORU^R01 或 JSON 格式发送完整的实验室报告，并获取带有 LOINC 代码和参考范围的实验室观察结果。

Source: https://developers.anpheros.com/zh/guides/lab-connector

实验室（或任何持有实验室报告的机构）在一个请求中发送完整的报告，平台会将每个结果转换为患者的实验室 `Observation`：

```
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        (optional; recorded in Provenance)
Idempotency-Key: <report id>          (optional; a retry returns the same answer)
```

## 格式

**CSV** 带标题行；分隔符 `,` `;` 或制表符，接受小数点逗号，日期为 ISO 格式，
`DD.MM.YYYY` 或 `DD/MM/YYYY`。可识别的列（罗马尼亚语或英语）：标记
(`analiza`, `test`, `marker`, `name`) — 或仅 LOINC `code` 列，在这种情况下，LOINC 名称将成为标记 —
值 (`rezultat`, `valoare`, `value`, `result`)，单位 (`um`, `unitate`, `unit`)，
参考范围 (`interval`, `referinta`: `70-100`, `<5`, `>3.5`) 或 `ref_low`/`ref_high`，
日期 (`data`, `recoltare`)，可选的 LOINC (`loinc`, `code`)，备注。

```
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
```

**HL7 v2 ORU^R01** (ER7 文本，段由 CR 或 LF 分隔)：`OBX-3` 标识符 (`code^text^LN`
为 LOINC；本地代码 (`^L`, `^99zzz`) 或任何其他编码系统将保留为实验室自己的代码，在
`urn:anpheros:lab-code` 下)，`OBX-5` 值 (`NM`, `SN` 或文本)，
`OBX-6` 单位，`OBX-7` 参考范围，`OBX-8` 异常标志 → `interpretation`，`OBX-11` 状态，
`OBX-14` 或 `OBR-7` 日期；`OBR-3`/`MSH-10` 将成为 Provenance 中的报告 ID。

**实验室。** 每项结果在 `performer` 中命名其生产者，正如 HL7 Europe Laboratory Report 2.1.0
要求的那样：您代表的组织 (`X-Anpheros-Acting-As`)，否则为 HL7 的 `MSH-4`（发送机构），或
JSON 中的 `laboratory`（顶级或每个项目）。CSV 不包含实验室；此类结果将通过缺失
执行者进行验证，这是事实。

**文本报告、文档和缺失日期。** 一行一个 OBX 的文本报告 (`TX`/`FT`，相同 `OBX-3`)
将合并为一项结果。整个文档在 `OBX-5` 中（`ED`，或任何编码值 `Base64`）不
作为结果存储；响应会发出警告，文档应放在 `/documents` 中。如果没有 `OBR-7`，结果将按
`OBR-14`（标本接收）日期，并附带警告。

**时间和时区。** 没有时区的 v2 时间是发送者的本地时间，而不是 UTC。与
`OBX-14`/`OBR-7` (`20260901081000+0300`) 一起发送的偏移量将被保留 (`2026-09-01T08:10:00+03:00`)。如果没有偏移量，将使用
`MSH-7` 的偏移量，并附带警告；如果任何地方都没有偏移量，结果将只保留其日期，也附带警告。CSV 时间
(`01.09.2026 08:10`) 不包含时区，因此仅存储为日期。直到 2026 年 10 月 17 日，此类时间一直被标记为 UTC；
在此之前导入的结果将保留其标识符，并在再次发送报告时仍被识别。

HL7 结果中仍处于待定状态 (OBX-11 `I`)、无法获取 (`X`)、已删除 (`D`) 或错误 (`W`) 的结果，以及没有值的 OBX 段，
不会成为 Observations；每个都会在 `warnings` 中命名。

**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, "date": "2026-09-01", "code": "3016-3"}]}`。

## 返回内容

```json
{"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"}]}
```

- 当报告提供 LOINC 代码或名称与平台术语（罗马尼亚语和英语名称及常用别名）匹配时，标记将映射到 **LOINC**。其他标记将保留实验室代码在 `urn:anpheros:lab-code` 下，并使用报告中的确切文本，然后在 `unmapped` 中列出，以便您可以在自己这边改进映射。实验室自己的代码仅与其实验室一起才是唯一的：源系统记录在每个 Observation 的 Provenance (`X-Anpheros-Source-System`) 中。
- 名称将与 LOINC 名称和同义词进行匹配（例如 *Hemoglobin A1c*、*Glycated hemoglobin*、*HDL cholesterol*、*LDL-C*）。与多个概念匹配的名称，或带有概念不具备的限定词的名称（*urine*、*non-HDL*、*free*、*ratio*…），不会被猜测：它将保留实验室代码并在 `unmapped` 中列出。当您的系统有 LOINC 代码时，请发送它们。
- 尿素和尿素氮 (BUN) 是不同的测量值：*Uree* / *Urea* 映射到尿素（LOINC `3091-6`，或 `22664-7` 以 mmol/L 为单位），*BUN* / *Urea nitrogen* / *Azot ureic* 映射到尿素氮（`3094-0`，或 `14937-7` 以 mmol/L 为单位）。值永远不会被转换。
- LDL 胆固醇：没有方法的名称映射到 `2089-1`；*calculated* / *calculat* / *Friedewald* 映射到计算的 LDL (`13457-7`)；*direct* 映射到直接测定 (`18262-6`)。方法是一个限定词，例如 *Bilirubina directa* 中的 *direct*，它不是总胆红素，并保留实验室代码。
- 葡萄糖：实验室报告上的裸露的 "Glicemie" / "Glucose" 映射到血清或血浆（LOINC `2345-7`）；名称为毛细血管、指尖采血或全血（"capilar"、"sânge integral"）的映射到全血 (`2339-0`)。报告中的 LOINC 代码始终优先。
- 每行都有一个稳定的标识符 (`urn:anpheros:lab-import:v2`)，该标识符由报告内容构建——报告 ID、报告上的名称和代码、日期、值和单位——而不是由平台选择的 LOINC 代码，因此**重新发送相同的报告会跳过已导入的行** (`skipped`)，即使在映射改进之后也是如此。任何这些内容不同的行（另一份报告、另一个采集时间、另一个值）都会被分开保留。2026 年 10 月 14 日之前导入的结果将保留其原始标识符，并通过名称、日期、值、单位和报告 ID 进行识别。没有报告 ID (CSV) 的情况下，此类匹配将在 `warnings` 中报告；发送报告 ID（HL7 `OBR-3`/`MSH-10`、JSON `origin`）以区分不同的报告。
- 每个 Observation 都包含 Provenance，其中包含 `author_type = import`、您的源系统和报告 ID；每个 Observation 会触发 `resource.created` 个 webhook；患者将在他们的应用程序中看到结果，并且他们同意的任何应用程序都可以读取它们。
- 每个请求最多 500 行。

两个 SDK：`labs.importCsv`、`labs.importHl7`、`labs.importItems`。

从 CSV 和 HL7 v2 报告到 FHIR Observations 的工作示例，包含未映射的标记和已重新发送的报告：[如何将实验室结果导入 FHIR 记录](https://developers.anpheros.com/zh/guides/import-lab-results-fhir)。

实验室数据如何在实验室、诊所、应用程序和 AI 之间移动，以及在实验室结果 API 中需要注意什么：[实验室结果 API](https://developers.anpheros.com/zh/guides/lab-results-api)。