# 元核云灵眸智能开放平台 Open API Skills

本文档给 AI Agent、claim-agent 和第三方系统读取，用于自动选择并调用元核云灵眸智能开放平台接口。

Skills URL：

```text
GET https://open.yuancore.com/api/skills
```

正式接口基础地址：

```text
https://open.yuancore.com/api
```

## 1. 调用规则

### 1.1 优先使用正式接口

AI 调用业务能力时，优先使用 `/api/*` 正式接口。正式接口需要租户 SK 鉴权，会记录调用量、扣点、并发限制和用量统计。

请求头：

```http
Authorization: Bearer <SK>
Content-Type: application/json
```

### 1.2 返回码

接口统一返回 JSON，`code == 200` 表示成功。

| code | 含义 | AI 处理方式 |
| --- | --- | --- |
| 200 | 成功 | 读取返回字段或 `data` |
| 201 | OCR 任务处理中 | 稍后继续调用 `/api/ocr/query` |
| 400 | 入参错误 | 修正参数后重试 |
| 402 | 点数不足 | 停止调用，提示租户充值 |
| 403 | SK 无效或未登录 | 停止调用，检查 `Authorization` |
| 404 | 任务或资源不存在 | 检查 `taskId` 或业务参数 |
| 422 | 发票查验参数不完整 | 根据 `msg` 补齐票据字段后重试 |
| 429 | 超过并发限制 | 稍后重试，不要立即高频重试 |
| 500 | 服务处理失败或部分接口参数校验失败 | 先读取 `msg`；参数问题修正后重试，服务问题记录并上报平台 |

文件类型识别、标准 OCR、ICD-10 等部分现有参数校验仍可能返回 `500`。遇到 `500` 时先读取 `msg`；如果明确提示图片、诊断或文件类型不能为空，修正参数后再调用。

### 1.3 并发限制

默认规则：

- OCR 异步任务：同一租户最多 20 个待处理任务。
- 其他同步请求：同一租户最多 10 个并发请求。
- 租户可以对单个 SK 设置更小的并发上限。

超过限制时返回：

```json
{
  "code": 429,
  "msg": "同步请求并发已达限制，租户上限10个，当前SK上限10个，请稍后再试"
}
```

或：

```json
{
  "code": 429,
  "msg": "同一租户OCR待处理任务已达20个，请稍后再试"
}
```

### 1.4 置信度使用规则

OCR 返回的叶子字段通常是对象：

```json
{
  "value": "字段值",
  "confidence": 80,
  "bbox": []
}
```

`confidence >= 80` 表示系统判断为可免检分数。如果业务复核发现判断有误，可以通过平台“问题上报”反馈给技术员检视原因。

### 1.5 图片参数

图片类接口通常支持二选一：

- `imageBase64`：图片 base64，支持 `data:image/png;base64,...` 前缀。
- `imageUrl`：公网可访问图片地址。

不要同时传大文件 base64 和 URL。URL 不可访问时会导致识别失败。

## 2. 接口选择

| 任务 | 正式接口 | 是否异步 | 说明 |
| --- | --- | --- | --- |
| 文件类型识别 | `POST /api/ocr/image-classify` | 否 | 判断图片属于医疗发票、费用清单、病历等材料类型 |
| 智能 OCR 标准版 | `POST /api/ocr/standard` | 是 | 提交图片识别任务，适合常规材料结构化 |
| 智能 OCR 专业版 | `POST /api/ocr/professional` | 是 | 医疗发票、费用清单、病历增强识别 |
| OCR 结果查询 | `POST /api/ocr/query` | 否 | 根据 `taskId` 轮询异步 OCR 结果 |
| 医保三大目录匹配 | `POST /api/three-catalogs/match` | 否 | 单个药品、诊疗、耗材项目匹配甲乙类和自付比例 |
| 医院信息匹配 | `POST /api/hospital/match` | 否 | 匹配医院标准信息、保司医院编码、级别、地区和性质 |
| ICD-10 匹配 | `POST /api/icd10/match` | 否 | 按诊断和主诉匹配疾病编码 |
| 医疗发票查验 | `POST /api/invoice/verify` | 否 | 财政医疗票据、税务医疗发票官方查验 |

## 3. 文件类型识别

### 3.1 接口

```text
POST /api/ocr/image-classify
```

### 3.2 请求字段

| 字段 | 类型 | 必传 | 说明 |
| --- | --- | --- | --- |
| imageBase64 | string | 二选一 | 图片 base64 |
| imageUrl | string | 二选一 | 图片 URL |
| filePath | string | 非必传 | 服务端可访问文件路径，普通租户一般不用 |

### 3.3 请求示例

```json
{
  "imageBase64": "data:image/png;base64,..."
}
```

### 3.4 成功返回

```json
{
  "code": 200,
  "msg": "操作成功",
  "fileType": "医疗发票"
}
```

### 3.5 说明

- 财政票据、税务发票会兼容返回为 `医疗发票`。
- 同一张图片中包含多张独立正式医疗发票时，文件类型识别返回 `医疗发票（多）`；后续 OCR 可继续传 `医疗发票（多）`，返回 `发票列表`。
- 常见返回类型包括：`医疗发票`、`医疗发票（多）`、`费用清单`、`门诊病历`、`入院记录`、`出院记录`、`出院小结`、`住院病案首页`、`检查报告`、`化验单`、`处方笺`、`结算单`、`身份证（人像面）`、`身份证（国徽面）`、`户口本（户主页）`、`户口本（常住人口登记卡）`、`银行卡`、`社保卡`、`出生医学证明`、`结婚证`、`理赔申请书`、`理赔申请书（第二页）`。

## 4. 智能 OCR 标准版

### 4.1 接口

```text
POST /api/ocr/standard
```

### 4.2 请求字段

| 字段 | 类型 | 必传 | 说明 |
| --- | --- | --- | --- |
| imageBase64 | string | 二选一 | 图片 base64 |
| imageUrl | string | 二选一 | 图片 URL |
| fileType | string | 非必传 | 文件类型。不传时系统可先识别类型；可传 `其他` 识别非内置类型材料 |
| priority | number | 非必传 | OCR 任务优先级，默认 0，数值越大越优先 |
| fileName | string | 非必传 | 原始文件名，用于任务列表展示 |

### 4.3 请求示例

```json
{
  "fileType": "医疗发票",
  "imageUrl": "https://example.com/invoice.jpg",
  "priority": 0
}
```

### 4.4 成功返回

```json
{
  "code": 200,
  "msg": "操作成功",
  "taskId": "01XXXX"
}
```

提交成功只返回 `taskId`，实际扣点以租户后台的用量统计和点数明细为准。

### 4.5 查询结果

拿到 `taskId` 后调用：

```text
POST /api/ocr/query
```

### 4.6 支持类型

标准版适合直接结构化材料，支持：`医疗发票`、`医疗发票（多）`、`入院记录`、`出院记录`、`出院小结`、`手术记录`、`病理报告`、`CT报告`、`MR报告`、`费用清单`、`门诊病历`、`结算单`、`检查报告`、`化验单`、`处方笺`、`住院病案首页`、`身份证（人像面）`、`身份证（国徽面）`、`户口本（户主页）`、`户口本（常住人口登记卡）`、`银行卡`、`社保卡`、`出生医学证明`、`结婚证`、`理赔申请书`、`理赔申请书（第二页）`、`其他`，以及租户自定义 OCR 类型。

`其他` 类型不限定固定字段，只返回图片中明确可见的关键信息。返回的字段名根据材料内容动态生成，结果为扁平 key-value 结构，不返回数组或嵌套对象。查询接口中每个动态字段仍按 `{value, confidence, bbox}` 返回。

如果传入的 `fileType` 不是系统内置类型，且当前租户没有配置同名自定义 OCR 类型，系统会自动使用 `其他` 通用识别规则，不再返回文件类型未配置错误。

`医疗发票（多）` 标准版返回 `发票列表[]`，每个元素字段与单张 `医疗发票` 一致。标准版包括 `其他` 类型均按固定 15 点/次计费，不按发票张数追加扣点；专业版 `医疗发票（多）` 才按单张医疗发票价格乘以 `发票列表[]` 数量计费。

## 5. 智能 OCR 专业版

### 5.1 接口

```text
POST /api/ocr/professional
```

### 5.2 请求字段

| 字段 | 类型 | 必传 | 说明 |
| --- | --- | --- | --- |
| imageBase64 | string | 二选一 | 图片 base64 |
| imageUrl | string | 二选一 | 图片 URL |
| fileType | string | 是 | 专业版类型，常用 `医疗发票`、`医疗发票（多）`、`费用清单`、`门诊病历` |
| 省 | string | 非必传 | 仅费用清单专业版使用。传入时作为三大目录匹配地区；不传时使用 OCR 识别出的医院名称匹配医院库，取对应省份 |
| 市 | string | 非必传 | 仅费用清单专业版使用。传入时作为三大目录匹配地区；不传时使用 OCR 识别出的医院名称匹配医院库，取对应城市 |
| srcCode | string | 非必传 | 仅专业版病历类材料使用，用于指定 ICD-10 匹配来源编码；不传默认 `YB2`。医疗发票、费用清单不使用该参数 |
| priority | number | 非必传 | OCR 任务优先级，默认 0 |
| fileName | string | 非必传 | 原始文件名 |

### 5.3 请求示例

多张医疗发票：

```json
{
  "fileType": "医疗发票（多）",
  "imageBase64": "data:image/png;base64,..."
}
```

费用清单：

```json
{
  "fileType": "费用清单",
  "imageBase64": "data:image/png;base64,...",
  "省": "广东省",
  "市": "广州市"
}
```

病历类请求：

```json
{
  "fileType": "门诊病历",
  "srcCode": "YB2",
  "imageUrl": "https://example.com/record.jpg"
}
```

### 5.4 成功返回

```json
{
  "code": 200,
  "msg": "操作成功",
  "taskId": "01XXXX"
}
```

提交成功只返回 `taskId`，实际扣点以租户后台的用量统计和点数明细为准。专业版识别完成后可能按多张发票数量或参与医保匹配的项目数量追加扣点。

### 5.5 增强规则

- `医疗发票`：在标准 OCR 基础上增加官方查验、识别信息校准、细类项目医保三大目录匹配；基础 30 点/张，参与医保匹配的项目每 10 条加 5 点，不满 10 条按 10 条算。
- `医疗发票（多）`：同图多张正式医疗发票拆分识别，返回 `发票列表[]`；每张发票字段和识别要求与单张 `医疗发票` 一致。计费按单张医疗发票价格乘以 `发票列表[]` 数量计算，提交任务时先按 1 张预扣，识别完成后按多出的张数补扣。
- `费用清单`：识别明细后补充 `项目标准名称`、医保三大目录甲乙类、自付比例、备注和置信度；参与医保匹配的项目每 10 条加 5 点，不满 10 条按 10 条算。`省`、`市` 可选传入；未传时按 OCR 识别出的 `医院名称` 匹配医院库，并使用该医院对应省市做三大目录匹配。
- `病历`：识别诊断、主诉后补充 ICD-10 疾病编码、疾病名称、是否意外和置信度；可传 `srcCode` 指定 ICD-10 来源编码，不传默认 `YB2`。

## 6. OCR 结果查询

### 6.1 接口

```text
POST /api/ocr/query
```

OCR 结果查询接口不扣点，可以使用同一个 `taskId` 多次轮询。OCR 点数在提交标准版或专业版任务时扣除，不会在查询结果时重复扣除。

### 6.2 请求字段

| 字段 | 类型 | 必传 | 说明 |
| --- | --- | --- | --- |
| taskId | string | 必传 | OCR 提交接口返回的任务 ID |

### 6.3 请求示例

```json
{
  "taskId": "01XXXX"
}
```

### 6.4 处理中返回

```json
{
  "code": 201,
  "msg": "识别中",
  "taskId": "01XXXX",
  "fileType": "医疗发票",
  "fileName": "invoice.jpg",
  "imageUrl": "https://...",
  "state": "识别中"
}
```

### 6.5 成功返回

```json
{
  "code": 200,
  "msg": "操作成功",
  "taskId": "01XXXX",
  "fileType": "医疗发票",
  "fileName": "invoice.jpg",
  "imageUrl": "https://...",
  "state": "识别完成",
  "data": {
    "票据标题": {
      "value": "广东省医疗门诊收费票据（电子）",
      "confidence": 80,
      "bbox": []
    }
  }
}
```

### 6.6 OCR 返回字段结构

除数组和对象容器外，OCR 结果的叶子字段一般返回：

```json
{
  "value": "字段值",
  "confidence": 80,
  "bbox": []
}
```

字段没有识别到时，`value` 通常为空字符串，`confidence` 通常为 40 或 0，`bbox` 为空数组。

### 6.7 OCR 标准版具体返回字段

#### 医疗发票

第一层字段：

```text
票据标题、票据类型、发票类型、发票状态、票据号码、校验码、票据代码、姓名、性别、开票日期、就诊日期、门特门慢、是否急诊、是否电子发票、是否医保结算、是否完整、盖章检查、医院名称、地区、入院日期、出院日期、住院天数、发票总金额、医保类型、医疗机构类型、业务流水号、社会保障号码、收款单位、住院号/门诊号、收款人、复核人、住院科别、工作单位、支付渠道、医保编号、就诊卡号、病历号、交款人社会统一信用代码、预缴金额、补缴金额、退费金额、医保统筹基金支付、其他支付、个人账户支付、个人现金支付、附加基金支付、医保账户余额、当年支付、历年支付、本年余额、历年余额、按比例自付、个人自付、自付一、自付二、个人自费、起付标准、医保范围内金额、累计医保内范围金额、年度门诊大额累计支付、超封顶金额、门诊大额支付、退休补充支付、残军补充支付、单位补充险[原公疗]支付、统筹累计支付、公务员补助、师职补助、大病保险报销、大病补充报销、医疗救助、产前检查费、民政救助、大病救助、伤残补助、其他补助、商业保险、医院承担、大类项目、细类项目
```

`大类项目[]` 字段：

```text
项目名称、金额
```

`细类项目[]` 字段：

```text
项目名称、项目标准名称、数量、单价、规格、剂型、单位、金额、类别、自付比例、自付金额、所属大类、项目编码
```

限定返回值：

| 字段 | value 可返回值 | 判断说明 |
| --- | --- | --- |
| 票据类型 | `门诊`、`住院`、`药店`、`其他` | 根据票据内容判断 |
| 发票类型 | `财政票据`、`税务发票`、`其他` | 根据票据性质判断 |
| 发票状态 | `正常`、`红冲`、`未知` | 根据票面状态判断 |
| 性别 | `男`、`女`、空字符串 | 根据患者信息判断 |
| 门特门慢 | `门特`、`门慢`、空字符串 | 门固、门固定按门特返回；票面无相关信息时返回空字符串 |
| 是否急诊 | `是`、`否` | 票面出现急诊时返回是，否则返回否 |
| 是否电子发票 | `是`、`否` | 结合标题是否含电子及纸质补打、红章等特征判断 |
| 是否医保结算 | `是`、`否` | 存在医保实时结算、医保结算或医保编号时返回是；明确自费或无医保结算信息时返回否 |
| 是否完整 | `是`、`否` | 票面关键区域未被遮挡、裁切时返回是，否则返回否 |
| 盖章检查 | `有`、`无` | 财政票据检查财政监制章，税务发票检查税务部门章 |
| 细类项目[].类别 | `甲`、`乙`、`丙`、空字符串 | 优先按明细行的医保类别、备注和自付比例判断；0%/无自付为甲，部分自付为乙，100%/全自费为丙 |
| 日期字段 | `YYYY-MM-DD`、空字符串 | 无法确认日期时返回空字符串 |

其他字段同样按限定值返回：费用清单 `明细[].类别` 只返回 `甲`、`乙`、`丙` 或空字符串；门诊病历 `是否医生签名`、处方笺 `是否有医生签名` 只返回 `是` 或 `否`；身份证国徽面 `有效期限-结束日期` 返回 `YYYY-MM-DD` 或 `长期`。OCR 查询任务的 `state` 只返回 `新创建`、`识别中`、`识别完成`、`识别异常`。

其他图片类型字段按以下通用口径返回，未识别到内容时 `value` 返回空字符串：

| 字段类型 | 返回内容 |
| --- | --- |
| 标题、姓名、医院、科室、地区 | 返回材料对应标签或区域中的标题、人员及机构信息；标题不使用医院名称代替。医院名称返回中文全称；确有多个不同的中文医疗机构名称时，按材料从上到下排列并以单个空格连接，不重复返回同一机构的英文译名、拼音或 Logo 英文副标题 |
| 入院/出院记录、病历 | 主诉、现病史、既往史、诊断、诊疗经过、出院情况、医嘱等字段返回各自明确区域的内容，不跨区域推断 |
| CT、MR、检查、病理报告 | 检查名称、部位、影像所见、影像诊断、病理诊断、标本信息等字段返回报告对应栏目内容 |
| 化验单 | 项目名称、结果、单位、参考范围、异常提示等字段返回检验明细对应列内容 |
| 费用与结算字段 | 金额、基金支付、个人支付、自费、自付、余额等字段返回票面同名栏目的金额，不在文档字段间互相推算 |
| 编码、号码字段 | 返回票面同名标签对应的 ICD-10 编码、票据号码、病案号、身份证号、卡号等编号，不使用邻近其他编号代替 |
| 日期字段 | 返回 `YYYY-MM-DD` 或材料上明确标注的年月格式；没有明确日期时返回空字符串 |
| 证件、户口本、银行卡、理赔申请书 | 返回证件或申请书对应栏目的姓名、证件号、关系、银行账号、事故经过等原文内容 |

#### 医疗发票（多）

第一层字段：

```text
发票列表
```

`发票列表[]` 中每个元素的字段与 `医疗发票` 一致，识别要求也与单张 `医疗发票` 一致。标准版按 15 点/次计费，不按发票张数追加扣点。

#### 费用清单

第一层字段：

```text
票据标题、医院名称、姓名、票据代码、票据号码、门诊号、总金额、就诊日期、入院日期、出院日期、住院天数、明细、页码
```

`明细[]` 字段：

```text
项目名称、项目标准名称、数量、单价、规格、剂型、单位、金额、类别、自付比例、自付金额、所属大类、项目编码
```

#### 门诊病历

```text
票据标题、姓名、医院名称、地区、科室、就诊日期、主诉、诊断、诊断疾病代码、现病史、既往史、既往史疾病代码、个人史、个人史疾病代码、家族史、家族史疾病代码、婚育史、体格检查、建议、是否医生签名、既往病史-检查描述、既往病史-疾病描述、既往病史-手术操作、现疾病-检查描述、现疾病-手术操作
```

#### 入院记录

```text
票据标题、姓名、医院名称、入院日期、主诉、现病史、既往史、体格检查、辅助检查、个人史、家族史、婚育史、修正判断、页码
```

#### 出院记录

```text
票据标题、姓名、医院名称、科室、出院诊断、出院诊断疾病代码、入院日期、出院日期、住院天数、入院诊断疾病代码、入院诊断、入院情况、诊疗经过、出院情况、出院医嘱、页码
```

#### 出院小结

```text
票据标题、医院名称、病案号、姓名、科室、入院日期、出院日期、住院天数、入院情况、出院情况、诊疗过程、入院诊断、出院诊断、入院诊断疾病代码、出院诊断疾病代码、检查结果、出院原因、出院注意事项、页码
```

#### 手术记录

```text
票据标题、姓名、性别、年龄、科室、手术日期、手术名称、手术经过、术前诊断、术后诊断、术后情况
```

#### 病理报告

```text
票据标题、姓名、年龄、性别、病理诊断、报告日期、送检日期、科室、病理号、肉眼检查、临床诊断、标本信息、病区
```

#### CT报告

```text
票据标题、医院名称、姓名、年龄、影像流水号、检查部位、检查时间、报告日期、影像所见、影像诊断
```

#### MR报告

```text
票据标题、医院名称、姓名、年龄、影像流水号、检查部位、检查时间、报告日期、影像所见、影像诊断
```

#### 结算单

第一层字段：

```text
票据标题、姓名、性别、医疗机构编号、医院名称、入院日期、出院日期、住院天数、医保范围内费用、总金额、统筹总额、自付二总额、自费总额、大类项目、支付信息、统筹基金支付、超限价金额、起付金额、退休补充支付、残军补助支付、单位补充险[原公疗]支付、本年度统筹基金累计支付、本年度住院统筹基金累计支付、本年度门特统筹基金累计支付、本年度大额互助资金[住院]累计支付、个人账户余额、当年帐户余额
```

`大类项目[]` 字段：

```text
项目名称、金额、自费、自付二、统筹基金支付
```

#### 检查报告

```text
票据标题、姓名、年龄、性别、科室、门诊号、检查名称、检查部位、检查日期、影像结果、检查结果
```

#### 化验单

```text
票据标题、姓名、性别、年龄、科室、标本类型、诊断、检验项目、检验仪器、检验时间、采样时间、接收时间、报告时间、备注、检验者、审核者、标本号、病案号、住院号、申请时间、医师、病人类型、机构名称、项目明细、送检日期、带勾选项文字内容、细胞图片、判读结果、建议、项目代码、项目名称、结果、单位、参考范围、异常结果提示、检验方法
```

#### 处方笺

```text
票据标题、姓名、年龄、医院名称、就诊日期、就诊科室、诊断、诊断疾病代码、地区、是否有医生签名
```

#### 住院病案首页

```text
票据标题、姓名、身份证号、医院名称、科室、病房、主要诊断及疾病编码、其他诊断及疾病编码、病理诊断及疾病编码、住院次数、现住址、电话、职业、工作单位、出生日期、性别、出院状态、联系人姓名、联系人关系、联系人电话、联系人地址、入院途径、入院诊断疾病代码、出院诊断疾病代码、病案号
```

#### 身份证（人像面）

```text
姓名、性别、出生日期、公民身份号码
```

#### 身份证（国徽面）

```text
签发机关、有效期限-开始日期、有效期限-结束日期
```

#### 户口本（户主页）

```text
户别、户主姓名、户号
```

#### 户口本（常住人口登记卡）

```text
姓名、曾用名、公民身份证件编号、户主或与户主关系
```

#### 银行卡

```text
银行名称、银行卡号
```

#### 社保卡

```text
姓名、性别、出生、社会保障号码、卡号、发卡日期、银行卡号
```

#### 出生医学证明

```text
新生儿姓名、母亲姓名、父亲姓名
```

#### 结婚证

第一层字段：

```text
持证人、登记日期、男方、女方
```

`男方`、`女方` 对象字段：

```text
姓名、国籍、出生日期、身份证件号
```

#### 理赔申请书

```text
报案编号、出险人姓名、出险人证件类型、出险人证件号码、事故经过、申请金额、理赔类型、申请人证件类型、申请人证件号码、申请人姓名、银行名称、银行卡号、开户人姓名、出险日期、医院名称
```

#### 理赔申请书（第二页）

```text
报案编号
```

### 6.8 OCR 专业版追加字段

专业版不是替换标准版字段，而是在标准版字段基础上追加业务增强字段。

#### 医疗发票专业版

医疗发票保留标准版全部字段，并对 `细类项目[]` 追加：

```text
项目标准名称、医保项目名称、医保类别、医保自付比例、医保备注
```

其中：

- `项目标准名称` 是标准 OCR 阶段清理后的项目名称。
- `医保项目名称`、`医保类别`、`医保自付比例` 等来自三大目录匹配。
- 医保字段按 `{value, confidence, bbox}` 结构返回，匹配置信度写在各字段的 `confidence` 中，不单独返回置信度字段。
- 专业版匹配时使用 `项目名称` 做医保目录匹配，不使用 `项目标准名称` 替代匹配。
- 官方票据查验结果单独返回在 `查验结果`；同时会校准标准 OCR 已有的 `发票状态`、票据号码、开票日期、金额等字段。

#### 医疗发票（多）专业版

返回第一层为 `发票列表[]`。每个元素返回单张医疗发票的标准 OCR 字段；每张发票只能提取自身区域内的基础信息、项目明细和支付信息，不能与其他发票串行混填。

当前 `医疗发票（多）` 不追加单张医疗发票专业版的 `查验结果` 和细类项目医保目录匹配字段。

计费按单张医疗发票价格乘以 `发票列表[]` 数量计算。

#### 费用清单专业版

费用清单保留标准版全部字段，并对 `明细[]` 追加：

```text
项目标准名称、医保项目名称、医保类别、医保自付比例、医保备注
```

其中 `项目标准名称` 在标准 OCR 阶段生成，三大目录匹配使用 `项目名称`。医保字段按 `{value, confidence, bbox}` 结构返回，匹配置信度写在各字段的 `confidence` 中。

#### 病历专业版

病历类材料保留标准版字段，并追加：

```text
ICD-10疾病编码、ICD-10疾病名称、是否意外
```

追加字段同样按 `{value, confidence, bbox}` 结构返回。

病历类专业版可在提交 OCR 任务时传 `srcCode`，用于指定 ICD-10 来源编码；不传默认 `YB2`。该参数仅影响病历 ICD-10 匹配，不影响医疗发票和费用清单。

## 7. 医保三大目录匹配

### 7.1 接口

```text
POST /api/three-catalogs/match
```

该接口只支持传单个项目参数，不支持传图片或文件，计费以开放平台接口产品配置为准，当前为 10 点/次。本匹配接口返回 `code == 200` 时按接口产品配置扣点，包括未匹配或低置信度结果；失败结果不扣点。费用清单图片、医疗发票图片请调用 `POST /api/ocr/professional`。

### 7.2 请求字段

| 字段 | 类型 | 必传 | 说明 |
| --- | --- | --- | --- |
| 项目名称 | string | 必传 | 需要匹配医保三大目录的项目名称 |
| 项目类型 | string | 非必传 | `药品`、`诊疗`、`耗材` |
| 省 | string | 必传 | 省份，例如 `广东省` |
| 市 | string | 必传 | 城市，例如 `广州市` |
| 票据类型 | string | 非必传 | 传 `门诊发票` 或 `住院发票`；会影响“限住院”等限定项目的甲乙类判断 |
| 医院名称 | string | 非必传 | 用于医院制剂归属判断，会影响医院制剂匹配结果 |
| 医院编码 | string | 非必传 | 医院编码 |
| 医院等级 | string | 非必传 | 医院等级 |
| 医院性质 | string | 非必传 | 公立、私立等 |
| 项目编码 | string | 非必传 | 票据或目录项目编码 |
| 规格 | string | 非必传 | 药品规格或耗材规格 |
| 剂型 | string | 非必传 | 药品剂型 |
| 单位 | string | 非必传 | 单位 |
| 数量 | string | 非必传 | 数量 |
| 单价 | string | 非必传 | 单价 |
| 金额 | string | 非必传 | 金额 |
| 类别 | string | 非必传 | 票据识别出的甲乙丙类 |
| 自付比例 | string | 非必传 | 票据识别出的自付比例 |
| 所属大类 | string | 非必传 | 西药费、中成药、诊疗费、材料费等 |

### 7.3 请求示例

```json
{
  "项目名称": "阿奇霉素片",
  "项目类型": "药品",
  "省": "广东省",
  "市": "广州市",
  "票据类型": "门诊发票",
  "医院名称": "广东省人民医院",
  "规格": "0.25g",
  "金额": "32.00"
}
```

### 7.4 成功返回

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "项目名称": "阿奇霉素片",
    "项目标准名称": "阿奇霉素片",
    "项目类型": "药品",
    "省": "广东省",
    "市": "广州市",
    "医保项目名称": "阿奇霉素片",
    "医保类别": "甲类",
    "医保自付比例": "0",
    "医保备注": "",
    "医保置信度": 80,
    "医保目录地区": "广东省/广州市"
  }
}
```

### 7.5 未匹配返回

未匹配时仍会返回 `项目标准名称`，医保字段为空或低置信度：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "项目名称": "未知项目",
    "项目标准名称": "未知项目",
    "医保项目名称": "",
    "医保类别": "",
    "医保自付比例": "",
    "医保备注": "",
    "医保置信度": 0,
    "医保目录地区": ""
  }
}
```

### 7.6 说明

- 成功返回中的 `data.省`、`data.市` 是请求输入的省份和城市，两个字段分别返回。
- `data.医保目录地区` 是实际命中的目录地区，格式为 `省/市`，例如 `广东省/广州市`；未匹配时为空字符串。
- `data.医保置信度` 为 `80` 分及以上时属于可信任结果；低于 `80` 分时需要人工复核。
- 三大目录匹配会优先使用标准目录数据；标准目录没有命中时，可使用生产经验、票据识别经验等兜底。
- 如果传入 `类别` 且明确为丙类，而标准目录没有匹配到，系统可返回丙类并给较高置信度。
- 当 `医保类别` 和 `医保自付比例` 同时为空时，`医保置信度` 固定为 `0`。
- 如果目录备注存在限制条件但无法根据入参确认，置信度会降低；传入 `票据类型`、`医院名称` 等上下文有助于提高判断准确性。
- 返回中不会暴露内部 `医保缓存ID`。

## 8. 医院信息匹配

### 8.1 接口

```text
POST /api/hospital/match
```

计费以开放平台接口产品配置为准，当前为 10 点/次。本匹配接口返回 `code == 200` 时按接口产品配置扣点，包括低置信度结果；未匹配返回 `404`，不扣点。

### 8.2 请求字段

| 字段 | 类型 | 必传 | 说明 |
| --- | --- | --- | --- |
| 医院名称 | string | 必传 | 医院名称，兼容 `hospitalName` |
| srcCode | string | 非必传 | 系统 ZJRS 或租户自定义保司医院编码表 |
| 省 | string | 非必传 | 省份，兼容 `province`，作为强约束 |
| 市 | string | 非必传 | 城市，兼容 `city`，作为强约束 |

### 8.3 请求示例

```json
{
  "srcCode": "ZJRS",
  "省": "北京市",
  "市": "北京市",
  "医院名称": "北京大学第三医院"
}
```

### 8.4 成功返回

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "医院标准名称": "北京大学第三医院",
    "医院曾用名称": [],
    "医院级别": "三级",
    "省": "北京市",
    "市": "北京市",
    "区": "海淀区",
    "医院性质": "公立",
    "医院标准信息置信度": 100,
    "保司医院名称": "北京大学第三医院",
    "保司医院编码": "0004571",
    "保司医院级别": "三级",
    "保司医院省": "北京市",
    "保司医院市": "北京市",
    "保司医院区": "海淀区",
    "保司医院性质": "公立",
    "保司医院匹配置信度": 100
  }
}
```

### 8.5 自定义保司医院编码表

租户后台支持维护自定义保司医院编码表。Excel 表头至少包含：

| 字段 | 必传 | 说明 |
| --- | --- | --- |
| 保司医院编码 | 是 | 保司侧医院编码 |
| 保司医院名称 | 是 | 保司侧医院名称 |
| 保司医院级别 | 否 | 一级、二级、三级或原始等级 |
| 保司医院省 | 否 | 省份 |
| 保司医院市 | 否 | 城市 |
| 保司医院区 | 否 | 区县 |
| 保司医院性质 | 否 | 公立、私立等 |

### 8.6 匹配规则摘要

- 不传 `srcCode` 时，只返回医院标准信息，不返回保司医院字段及 `保司医院匹配置信度`。
- 传 `srcCode` 时，先匹配保司医院信息，再用保司医院名称匹配标准医院信息；保司医院为 `其他医院` 时，继续用原始输入医院名匹配标准医院。
- 保司医院匹配优先级：当前租户自定义编码表 > 生产人工确认经验 > 系统内置编码表。
- 保司医院匹配支持用医院名称、AI 原医院名称或医院编码命中；省市完全匹配优先，其次省匹配，再其次省市为空兜底。
- 标准医院匹配支持医院标准名称、曾用名，以及括号全角/半角变体。
- `医院标准信息置信度`：标准名称命中为 100，曾用名命中为 80；标准库未命中且 DeepSeek 明确确认医院存在时，返回标准信息且 `医院标准信息置信度` 为 `40`。
- DeepSeek 确认存在的医院信息会自动加入医院标准库；无法确认存在或返回信息异常时不入库，并按未匹配处理。
- `保司医院匹配置信度`：当前只表示是否命中保司医院记录，命中为 100，未命中为 0。
- 当保司医院为 `其他医院` 且标准医院已匹配时，保司医院级别、省、市、区、性质使用标准医院信息补充，保司医院编码和名称仍保留保司结果。

## 9. ICD-10 匹配

### 9.1 接口

```text
POST /api/icd10/match
```

计费以开放平台接口产品配置为准，当前为 10 点/次。本匹配接口返回 `code == 200` 时按接口产品配置扣点，包括低置信度结果；失败结果不扣点。

### 9.2 请求字段

| 字段 | 类型 | 必传 | 说明 |
| --- | --- | --- | --- |
| srcCode | string | 非必传 | ICD-10 来源编码，不传默认 `YB2` |
| diagnosis | string | 按场景 | 诊断名称 |
| chiefComplaint | string | 非必传 | 主诉或补充诊断上下文 |
| imageBase64 | string | 按场景 | 带诊断信息的图片 base64 |
| imageUrl | string | 按场景 | 带诊断信息的图片 URL |

### 9.3 请求示例

```json
{
  "srcCode": "YB2",
  "diagnosis": "颈椎病",
  "chiefComplaint": "颈部疼痛1周"
}
```

图片请求：

```json
{
  "srcCode": "YB2",
  "imageUrl": "https://example.com/medical-record.jpg"
}
```

### 9.4 成功返回

```json
{
  "code": 200,
  "msg": "操作成功",
  "srcCode": "YB2",
  "diagnosis": "颈椎病",
  "chiefComplaint": "颈部疼痛1周",
  "diseaseName": "颈椎病",
  "diseaseCode": "M47.201",
  "confidence": 80,
  "isAccident": false
}
```

### 9.5 返回字段

以下字段直接返回在响应根层，不放在 `data` 字段内。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | number | 业务状态码，`200` 表示匹配成功 |
| msg | string | 接口处理说明 |
| srcCode | string | 本次实际使用的 ICD-10 来源编码，未传时返回 `YB2` |
| chiefComplaint | string | 本次匹配使用的主诉；图片请求时为从图片中识别出的主诉 |
| diagnosis | string | 本次匹配使用的诊断；图片请求时为从图片中识别出的诊断 |
| diseaseName | string | 匹配到的 ICD-10 疾病名称 |
| diseaseCode | string | 匹配到的 ICD-10 疾病编码 |
| confidence | number | ICD-10 匹配置信度，等于或大于 `80` 时系统判断为可免检分数 |
| isAccident | boolean | 根据诊断和主诉判断是否为意外情形；`true` 表示意外，`false` 表示疾病或非意外 |
| ocrData | object | 仅传入 `imageBase64` 或 `imageUrl` 时返回，为图片识别产生的原始结构化病历数据 |

`ocrData` 不是固定结构。当前 ICD-10 匹配会读取其中的“诊断”和“主诉”，还可能包含图片中识别到的其他病历字段，具体字段随图片内容变化。直接传 `diagnosis`、未传图片时不返回 `ocrData`。

### 9.6 匹配规则摘要

- `srcCode` 不传默认 `YB2`。
- 支持租户自定义 ICD-10 列表和诊断关键词关系。
- 生产经验优先于通用医学标准匹配；`ZJRS` 等来源会按保司认可经验排序。
- 当诊断对应多个编码时，优先使用 ref 诊断关键词关系；没有 ref 时再用 AI 判断，主诉只作为辅助上下文。

## 10. 医疗发票查验

### 10.1 接口

```text
POST /api/invoice/verify
```

### 10.2 请求字段

| 字段 | 类型 | 必传 | 说明 |
| --- | --- | --- | --- |
| imageBase64 | string | 按场景 | 票据图片 base64 |
| imageUrl | string | 按场景 | 票据图片 URL |
| filePath | string | 按场景 | 服务端文件路径 |
| invoiceType | string | 非必传 | `财政票据` 或 `税务发票` |
| invoiceCode | string | 按场景 | 票据代码或发票代码 |
| invoiceNumber | string | 按场景 | 票据号码或发票号码 |
| billingDate | string | 按场景 | 开票日期，建议 `yyyy-MM-dd` |
| totalAmount | string | 按场景 | 票据金额或价税合计 |
| checkCode | string | 按场景 | 税务发票校验码 |
| payer | string | 按场景 | 部分财政票据需要交款人 |
| idNumber | string | 按场景 | 部分财政票据需要身份证号或证件号后六位 |
| salesTaxNo | string | 按场景 | 部分税务发票需要销售方税号 |
| orderNo | string | 按场景 | 部分区块链或通用电子发票需要 |
| province | string | 非必传 | 省份，用于选择查验规则 |

### 10.3 请求示例

```json
{
  "imageUrl": "https://example.com/invoice.jpg",
  "province": "广东省",
  "payer": "张三",
  "idNumber": "123456"
}
```

### 10.4 成功返回

```json
{
  "code": 200,
  "msg": "操作成功",
  "invoiceType": "财政票据",
  "resultCode": 0,
  "resultRemark": "正常",
  "isRed": false,
  "data": {
    "invoiceCode": "00000000",
    "invoiceNumber": "0000000000",
    "billingDate": "2026-06-11",
    "totalAmount": "100.00",
    "payer": "张三",
    "payee": "某医院"
  }
}
```

### 10.5 说明

- 支持财政医疗票据电子版和税务发票电子版。
- 返回 `invoiceType` 只会是 `财政票据` 或 `税务发票`；`isRed` 为 `true` 表示已冲红，`false` 表示未判断为冲红。
- 财政票据 `data.redTag`：`0` 表示正常、`1` 表示已红冲；税务发票 `data.state`：`1` 正常、`2` 作废、`3` 红冲、`7` 部分红冲、`8` 全额红冲。
- 如果传图片，系统会先识别票面字段再查验。
- 不同省份财政票据可能要求补充 `payer` 或 `idNumber`。

## 11. curl 示例

### 11.1 文件类型识别

```bash
curl -sS -X POST 'https://open.yuancore.com/api/ocr/image-classify' \
  -H 'Authorization: Bearer <SK>' \
  -H 'Content-Type: application/json' \
  -d '{"imageUrl":"https://example.com/file.jpg"}'
```

### 11.2 OCR 提交和查询

```bash
curl -sS -X POST 'https://open.yuancore.com/api/ocr/professional' \
  -H 'Authorization: Bearer <SK>' \
  -H 'Content-Type: application/json' \
  -d '{"fileType":"费用清单","imageUrl":"https://example.com/list.jpg"}'
```

```bash
curl -sS -X POST 'https://open.yuancore.com/api/ocr/query' \
  -H 'Authorization: Bearer <SK>' \
  -H 'Content-Type: application/json' \
  -d '{"taskId":"01XXXX"}'
```

### 11.3 三大目录匹配

```bash
curl -sS -X POST 'https://open.yuancore.com/api/three-catalogs/match' \
  -H 'Authorization: Bearer <SK>' \
  -H 'Content-Type: application/json' \
  -d '{"项目名称":"阿奇霉素片","项目类型":"药品","省":"广东省","市":"广州市"}'
```

### 11.4 ICD-10 匹配

```bash
curl -sS -X POST 'https://open.yuancore.com/api/icd10/match' \
  -H 'Authorization: Bearer <SK>' \
  -H 'Content-Type: application/json' \
  -d '{"srcCode":"YB2","diagnosis":"颈椎病","chiefComplaint":"颈部疼痛1周"}'
```

## 12. AI 调用建议

1. 先判断任务类型，再选接口；不要把费用清单图片传给 `/api/three-catalogs/match`。
2. 图片材料不确定类型时，先调用 `/api/ocr/image-classify`。
3. OCR 是异步接口，必须保存 `taskId` 并轮询 `/api/ocr/query`。
4. 查询 OCR 结果时，`code == 201` 表示继续等待，不是失败。
5. 三大目录匹配一定传 `项目名称`；有地区、票据类型、医院名称、规格、类别、自付比例时一并传入。
6. ICD-10 匹配优先传结构化 `diagnosis` 和 `chiefComplaint`；只有没有结构化字段时才传病历图片。
7. 看到 `402`、`403` 时不要重试；看到 `429` 时延迟重试。