附件2-电子健康卡管理系统接口使用文档V1.7.docx

电子健康卡管理系统接口文档(V1.7版)修订历史版本时间内容修订者1.12019-3-63.4获取二维码接口添加code_type参数林乐行1.22019-3-7接口请求方式和摘要增加SHA256，接口数据加密增加AES朱坚1.32019-3-12更新了SHA256算法签名示例董伟1.42019-3-15增加用卡数据上传接口，包含（科室代码字典、刷卡终端类型编号字典、诊疗环节代码字典）苏振中1.52019-5-7修改各加密方式的示例苏振中1.62019-5-10修改AES加密示例苏振中1.72020-5-63.1注册电子健康卡 接口请求参数中的出生日期改为必填项苏振中1. 文档概述1.1. 引言本文档制定App应用类型为服务端电子健康卡管理系统的业务接口规范2. API 接口概述电子健康卡管理系统作为服务端，以Http、Https方式为应用类型为服务端的App应用提供服务数据内容的格式为json;数据字符编码格式为:utf-82.1. 接口请求方式1. URL：http://host:port/api/ehc/handle2. 请求方式：POST3. 请求参数：序号参数名数据类型中文名称1data字符串请求数据包（格式：json），请求包应包含app_id2algorithm整型签名算法（1- SM2WithSM3算法，2-SM3算法，3-SHA256算法）3signature字符串对请求包做的签名值（格式：16进制串）本接口提供可以用：SM2WithSM3、SM3、SHA256算法签名。

当采用1- SM2WithSM3、2-SM3算法时，需要调用签名服务器生成签名；当采用3-SHA256算法时，需要调用方程序自行生成签名2.1.1 SM2WithSM3或SM3算法签名示例当algorithm的值为签名算法1或2时：{"data":"{\"method\":\"ehc.ehealthcode.verify\",\"app_id\":\"3vtzutuzb131il4io4\",\"term_id\":\"SK0001\",\"version\":\"X.M.0.1\",\"timestamp\":\"1557236049417\",\"digest_type\":\"SM3\",\"digest\":\"C108F66CCEB1097409517887C66BBACFBFDB5DB1F0386B875C899D2CD7BCF719\",\"enc_type\":\"SM4\",\"biz_content\":\"c30d18ac98e71c03eaa110aab94b5abed6439c942325d1ab50d60e7d8a8460844c9eaf96b66083445bb3f030c3b3782f9f88e382dafc5091f7b2ad63e6994b9a368d52ee36c8dbd7429427d8ca6b6a8a27d4f23faddf49f5600fa340c9a2376d\"}","algorithm":1,"signature":"3046022100F5460204FA2F698F1487C6759931108992BFF07FA4FC799123653BDCF08701A3022100F3C2F4BB0A3752F2E933B436A9325E7BB05F241D0A07D432E2CD93E65C16942A"}注意：1、 其中data为接口中的“请求参数”组成的json字符串。

2、 当卡管后台“系统设置--系统配置管理--授权验证开启“开关为关闭（0）时，algorithm和signature参数不起作用，此时对于接口请求也不到”电子健康卡API授权管理系统”做验证3、 卡管后台“系统设置--系统配置管理--授权验证开启“开关为开启（1）时，系统对于请求会到” 电子健康卡API授权管理系统”做验证，此时传入的algorithm和signature参数应为调用”电子健康卡API授权管理系统”的签名认证服务器所生成的签名签名原文的生成规则为：data+app_secret,生成签名示例：{"app_id": " app_id ", "biz_content": "F404379A66B50640EF1367CCE000F6463BA1D6068A3C5360374B741DFCD7…", "enc_type": "SM4", "method": "ehc.ehealthcode.verify", "term_id": "35020010001", "timestamp": "1512971932368", "version": "X.M.0.1"}0F6463BA5F0AC09AB1FFA3D10F8C620D其中上面标黄的为app_id和app_secret，这两个来源于” 电子健康卡API授权管理系统”，在此系统中下载。

若对签名有疑问，则和”电子健康卡API授权管理系统”的厂商技术沟通2.1.2 SHA256算法签名示例当algorithm的值为签名算法3时：{"data":"{\"method\":\"ehc.ehealthcode.verify\",\"app_id\":\"3vtzutuzb131il4io4\",\"term_id\":\"SK0001\",\"version\":\"X.M.0.1\",\"timestamp\":\"1557236049417\",\"digest_type\":\"SM3\",\"digest\":\"C108F66CCEB1097409517887C66BBACFBFDB5DB1F0386B875C899D2CD7BCF719\",\"enc_type\":\"SM4\",\"biz_content\":\"c30d18ac98e71c03eaa110aab94b5abed6439c942325d1ab50d60e7d8a8460844c9eaf96b66083445bb3f030c3b3782f9f88e382dafc5091f7b2ad63e6994b9a368d52ee36c8dbd7429427d8ca6b6a8a27d4f23faddf49f5600fa340c9a2376d\"}","algorithm":3,"signature":"e62027a1b098edb3fb5b37e43c3da15488549b260150030e16ecef1536576ab8"}注意：1、 其中data为接口中的“请求参数”组成的json字符串。

2、 signature参数应为计算所得的值签名原文的生成规则为：data+app_secret,生成签名原文示例：{"method":"ehc.ehealthcode.verify","app_id":"3vtzutuzb131il4io4","term_id":"SK0001","version":"X.M.0.1","timestamp":"1557236049417","digest_type":"SM3","digest":"C108F66CCEB1097409517887C66BBACFBFDB5DB1F0386B875C899D2CD7BCF719","enc_type":"SM4","biz_content":"c30d18ac98e71c03eaa110aab94b5abed6439c942325d1ab50d60e7d8a8460844c9eaf96b66083445bb3f030c3b3782f9f88e382dafc5091f7b2ad63e6994b9a368d52ee36c8dbd7429427d8ca6b6a8a27d4f23faddf49f5600fa340c9a2376d"}ae4ead79e2bb40d69f163717b61e7984计算得出签名值：e62027a1b098edb3fb5b37e43c3da15488549b260150030e16ecef1536576ab8其中上面标黄的为app_id和app_secret，在卡管后台“App信息管理-- App信息管理或者查看App应用--下载加解密密钥”获取。

若对此签名有疑问，则和我司技术沟通2.2. 接口数据加密请求的数据加密是对“请求参数”中的biz_content值进行加密，加密方式通过enc_type的值方式进行加密，加密的的密钥在卡管后台“App信息管理-- App信息管理或者查看App应用--下载加解密密钥”获取加密方式现在系统支持PLAIN/SM4/AES方式2.2.1 SM4示例请求参数：{"data":"{\"method\":\"ehc.ehealthcode.verify\",\"app_id\":\"3vtzutuzb131il4io4\",\"term_id\":\"SK0001\",\"version\":\"X.M.0.1\",\"timestamp\":\"1557236049417\",\"digest_type\":\"SM3\",\"digest\":\"C108F66CCEB1097409517887C66BBACFBFDB5DB1F0386B875C899D2CD7BCF719\",\"enc_type\":\"SM4\",\"biz_content\":\"c30d18ac98e71c03eaa110aab94b5abed6439c942325d1ab50d60e7d8a8460844c9eaf96b66083445bb3f030c3b3782f9f88e382dafc5091f7b2ad63e6994b9a368d52ee36c8dbd7429427d8ca6b6a8a27d4f23faddf49f5600fa340c9a2376d\"}","algorithm":1,"signature":"3046022100F5460204FA2F698F1487C6759931108992BFF07FA4FC799123653BDCF08701A3022100F3C2F4BB0A3752F2E933B436A9325E7BB05F241D0A07D432E2CD93E65C16942A"}数据加密码源(biz_content)：{"ehealth_code":"85:6CFB29781341DDB2B1DD1E88F8C5B39FEC6CB8FCFADA86B01F506C6F9B45EE68:1"}通过加密后数据（SM4）：c30d18ac98e71c03eaa110aab94b5abed6439c942325d1ab50d60e7d8a8460844c9eaf96b66083445bb3f030c3b3782f9f88e382dafc5091f7b2ad63e6994b9a368d52ee36c8dbd7429427d8ca6b6a8a27d4f23faddf49f5600fa340c9a2376d提示：此示例加密秘钥为ae4ead79e2bb40d69f163717b61e79842.2.2 AES示例待加密的数据加密码源(biz_conten。