医匠透析 HDIS · 开放接口对接规范 v1（草案）

GET https://hdis.api.yijiangsoft.com/open/v1/ping

{HTTP方法大写}
{请求路径}
{规范化查询串}
{请求体的SHA-256十六进制小写}
{Timestamp}
{Nonce}

signature = HMAC-SHA256(key = appSecret, data = 待签名串) → 转小写十六进制

appId     = hdis_demo
appSecret = 0123456789abcdef
方法      = POST
路径      = /open/v1/lab/reports
查询串    = （空）
请求体    = {"reports":[]}
Timestamp = 1756684800000
Nonce     = 7f3d0c1e-0000-4000-8000-000000000001

POST⏎
/open/v1/lab/reports⏎
⏎
486a8f07711a55700e1ed31c536217c17f3135cc6340b4830bcb4f87bbc7072a⏎
1756684800000⏎
7f3d0c1e-0000-4000-8000-000000000001

GET /open/v1/reconcile/lab?name=张三&date=2026-09-01

name=%E5%BC%A0%E4%B8%89&date=2026-09-01

date=2026-09-01&name=%E5%BC%A0%E4%B8%89

appId     = hdis_demo
appSecret = 0123456789abcdef
Timestamp = 1756684800000
Nonce     = 7f3d0c1e-0000-4000-8000-000000000002

GET⏎
/open/v1/reconcile/lab⏎
date=2026-09-01&name=%E5%BC%A0%E4%B8%89⏎
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855⏎
1756684800000⏎
7f3d0c1e-0000-4000-8000-000000000002

047f33f0e1b6dba5fdc78a09c9c2ac344a1220709d6f6de05363eaedd3b94dc7

static String sign(String appSecret, String method, String path, String canonicalQuery,
                   byte[] body, long timestamp, String nonce) throws Exception {
    MessageDigest sha = MessageDigest.getInstance("SHA-256");
    String bodyHash = hex(sha.digest(body == null ? new byte[0] : body));
    String toSign = String.join("\n", method.toUpperCase(), path, canonicalQuery,
                                bodyHash, String.valueOf(timestamp), nonce);
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(appSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    return hex(mac.doFinal(toSign.getBytes(StandardCharsets.UTF_8)));
}

static String hex(byte[] b) {
    StringBuilder sb = new StringBuilder(b.length * 2);
    for (byte x : b) sb.append(Character.forDigit((x >> 4) & 0xF, 16)).append(Character.forDigit(x & 0xF, 16));
    return sb.toString();
}

/**
 * 规范化查询串（§3.1）。入参为实际发送的查询串原文（不含 ?），
 * 如 "name=%E5%BC%A0%E4%B8%89&date=2026-09-01"。只调整顺序，不做编码或解码。
 */
static String canonicalQuery(String rawQuery) {
    if (rawQuery == null || rawQuery.isEmpty()) return "";
    List<String[]> pairs = new ArrayList<>();
    for (String part : rawQuery.split("&")) {
        if (part.isEmpty()) continue;
        int eq = part.indexOf('=');
        pairs.add(eq < 0 ? new String[]{part, ""}
                         : new String[]{part.substring(0, eq), part.substring(eq + 1)});
    }
    // 按解码后的参数名排序（使 %61 与 a 排序一致），拼接时仍使用原始的名与值。
    pairs.sort(Comparator.<String[], String>comparing(p -> URLDecoder.decode(p[0], StandardCharsets.UTF_8))
                         .thenComparing(p -> p[1]));
    StringJoiner sj = new StringJoiner("&");
    for (String[] p : pairs) sj.add(p[0] + "=" + p[1]);
    return sj.toString();
}

static string Sign(string appSecret, string method, string path, string canonicalQuery,
                   byte[] body, long timestamp, string nonce) {
    using var sha = SHA256.Create();
    var bodyHash = Convert.ToHexString(sha.ComputeHash(body ?? Array.Empty<byte>())).ToLowerInvariant();
    var toSign = string.Join("\n", method.ToUpperInvariant(), path, canonicalQuery,
                             bodyHash, timestamp.ToString(), nonce);
    using var mac = new HMACSHA256(Encoding.UTF8.GetBytes(appSecret));
    return Convert.ToHexString(mac.ComputeHash(Encoding.UTF8.GetBytes(toSign))).ToLowerInvariant();
}

// 规范化查询串（§3.1）。入参为实际发送的查询串原文（不含 ?），只调整顺序，不做编码或解码。
static string CanonicalQuery(string rawQuery) {
    if (string.IsNullOrEmpty(rawQuery)) return "";
    var pairs = rawQuery.Split('&', StringSplitOptions.RemoveEmptyEntries).Select(part => {
        var eq = part.IndexOf('=');
        return eq < 0 ? (Name: part, Value: "") : (Name: part[..eq], Value: part[(eq + 1)..]);
    })
    // 按解码后的参数名排序，须使用 StringComparer.Ordinal；区域相关的默认比较器会得到不同的顺序。
    .OrderBy(p => Uri.UnescapeDataString(p.Name.Replace("+", " ")), StringComparer.Ordinal)
    .ThenBy(p => p.Value, StringComparer.Ordinal);
    return string.Join("&", pairs.Select(p => $"{p.Name}={p.Value}"));
}

{ "code": 200, "msg": "操作成功", "data": { }, "timestamp": 1756684800123 }

"patient": {
  "idCard": "330102199001011234",
  "name": "张三",
  "gender": "M",
  "birthDate": "1990-01-01",
  "hisPatientId": "0000123456",
  "visitNo": "ZY2026090100123",
  "visitType": "INPATIENT"
}

{
  "reports": [
    {
      "externalId": "LIS20260901000123",
      "reportNo": "20260901000123",
      "patient": { "idCard": "330102199001011234", "name": "张三", "hisPatientId": "0000123456" },
      "panelName": "肾功能+电解质",
      "specimen": "SERUM",
      "collectedAt": "2026-09-01 07:35:00",
      "reportedAt": "2026-09-01 09:12:00",
      "status": "FINAL",
      "labName": "检验科",
      "reporter": "李四",
      "reviewer": "王五",
      "items": [
        { "itemCode": "0231", "itemName": "血红蛋白", "value": 98,   "unit": "g/L",    "refLow": 115, "refHigh": 150, "abnormalFlag": "L" },
        { "itemCode": "0455", "itemName": "血钾",     "value": 5.8,  "unit": "mmol/L", "refLow": 3.5, "refHigh": 5.3, "abnormalFlag": "H" },
        { "itemCode": "0912", "itemName": "尿素",     "value": 22.4, "unit": "mmol/L", "refLow": 2.9, "refHigh": 8.2, "abnormalFlag": "H" },
        { "itemCode": "1180", "itemName": "HBsAg",    "value": "阴性", "resultType": "QUALITATIVE" }
      ]
    }
  ]
}

{
  "code": 200, "msg": "操作成功",
  "data": {
    "total": 2, "accepted": 2, "rejected": 0,
    "results": [
      { "externalId": "LIS20260901000123", "status": "CREATED", "matched": true,
        "patientRef": "P202600123", "itemsMapped": 3, "itemsUnmapped": 1 },
      { "externalId": "LIS20260901000124", "status": "UPDATED", "matched": false,
        "pendingReason": "身份证号在本院透析患者中未找到，已进待认领" }
    ]
  }
}

{
  "reports": [
    {
      "externalId": "PACS20260828000077",
      "patient": { "idCard": "330102199001011234", "name": "张三" },
      "examType": "ECHO",
      "examName": "经胸超声心动图",
      "bodySite": "心脏",
      "method": "经胸二维超声",
      "examedAt": "2026-08-28 10:20:00",
      "reportedAt": "2026-08-28 11:05:00",
      "findings": "左房内径 41mm，左室舒张末期内径 52mm，室间隔厚度 12mm……",
      "conclusion": "左室肥厚，二尖瓣轻度返流，左室舒张功能减低。",
      "reporter": "赵六",
      "items": [
        { "hdisCode": "EF",     "value": 58,   "unit": "%"  },
        { "hdisCode": "LVIDd",  "value": 52,   "unit": "mm" },
        { "hdisCode": "IVSd",   "value": 12,   "unit": "mm" },
        { "hdisCode": "MITRAL_REGURG", "value": "轻度", "resultType": "QUALITATIVE" }
      ]
    }
  ]
}

{ "code": 200, "data": {
  "version": "1.0.0",
  "items": [ { "code": "HGB", "name": "血红蛋白", "category": "CBC",
               "valueType": "numeric", "unit": "g/L", "aliases": ["HGB","Hb","血色素"] } ],
  "examTypes": [ { "code": "ECHO", "name": "心脏超声" } ]
} }

{ "code": 200, "data": {
  "date": "2026-09-01", "labReportCount": 128, "examReportCount": 14,
  "unmatchedCount": 2,
  "externalIdDigest": "sha256:3f9a…",
  "externalIds": ["LIS20260901000123", "…"]
} }

{ "code": 200, "msg": "操作成功", "data": {
  "appId": "hdis_demo", "appName": "示例医院检验科", "tenantId": "1", "sandbox": true,
  "serverTime": "2026-09-01 08:00:00",
  "stringToSign": "GET\n/open/v1/ping\n\ne3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\n1756684800000\n7f3d0c1e-0000-4000-8000-000000000001"
}, "timestamp": 1756684800123 }

export function canonicalQuery(rawQueryString = '') {
  const raw = typeof rawQueryString === 'string' ? rawQueryString : buildQueryString(rawQueryString);
  if (!raw) return '';
  const pairs = [];
  for (const part of raw.split('&')) {
    if (!part) continue;
    const eq = part.indexOf('=');
    pairs.push(eq < 0 ? [part, ''] : [part.slice(0, eq), part.slice(eq + 1)]);
  }
  // 按解码后的参数名排序（使 %61 与 a 排序一致），拼接时仍使用原始的名与值。
  const decoded = new Map();
  const nameForSort = (n) => {
    if (!decoded.has(n)) {
      let v;
      try {
        // 与 Java URLDecoder 一致，将 + 视为空格，否则含 + 的参数名排序结果会不同。
        v = decodeURIComponent(n.replace(/\+/g, ' '));
      } catch {
        v = n; // 百分号编码不合法时按原文排序，不中断执行；此类请求验签会失败。
      }
      decoded.set(n, v);
    }
    return decoded.get(n);
  };
  pairs.sort((a, b) => {
    const na = nameForSort(a[0]);
    const nb = nameForSort(b[0]);
    if (na !== nb) return na < nb ? -1 : 1;
    if (a[1] !== b[1]) return a[1] < b[1] ? -1 : 1;
    return 0;
  });
  return pairs.map(([k, v]) => `${k}=${v}`).join('&');
}

export function stringToSign({ method, path, query = '', body = null, timestamp, nonce }) {
  const raw = body == null ? Buffer.alloc(0) : Buffer.isBuffer(body) ? body : Buffer.from(body, 'utf8');
  const bodyHash = crypto.createHash('sha256').update(raw).digest('hex');
  return [method.toUpperCase(), path, canonicalQuery(query), bodyHash, String(timestamp), nonce].join('\n');
}

export function sign(appSecret, toSign) {
  return crypto.createHmac('sha256', Buffer.from(appSecret, 'utf8')).update(toSign, 'utf8').digest('hex');
}