电子健康卡业务WebService接口规范

电子健康卡业务\ZVebService接口规范

（文档版本vi.5）

”盛1m嬲融褊

2018年10月

版本说明

版本更新日期更新说明修改人

VI.12019/01/15初始版文档形成张凡

VI.22019/03/27修改示例报文郭珊

VI.32019/10/09支持新生儿发码用码：杜志

1有出生证的新生儿发码证件类型传“08”，

证件号码传出生证号；

2无出生证的新生儿发码卡类型传“2”，证

件类型传“99”，证件号码内容传“母亲身

份证#新生儿出生日期#新生儿性别#新生儿

自编码（默认01）”。

VI.42020/02/16线下读码接口新增跨域读码逻辑，二维码内万家乐

容改为国家规范2.4版本，见出参QRCode标

红部分。

VI.52021/05/31syncCardInfo>updateCardlnfo接口中传输

对象peopleinfo补充字段、isRealName添加

实名渠道，virldCardVerify中传输对象

UseCardlnfo补充字段，更新证件类型、诊疗

环节等字典，添加regTerminal终端注册接

口（见标红部分）。

VI.62021/07/19新增注册终端（regTerminal）返回刘方瑞

machineCode

目次

1概述.....................................错误!未定义书签。

2适用范围及对象...........................错误!未定义书签。

2.1接口调用前置约束条件.....................错误!未定义书签。

2.2电子健康卡接口调用业务场景描述...........错误!未定义书签。

3返回码表.........................................错误!未定义书签。

4webServices调用接口规范........................错误!未定义书签。

4.1接口数据传输对象DTO封装说明.............错误!未定义书签。

4.2接入机构身份认证接口.....................错误!未定义书签。

4.3发卡同步接口.............................错误!未定义书签。

4.4信息更新接口.............................错误!未定义书签。

4.5更改卡状态...............................错误!未定义书签。

4.6电子卡静态二维码下载.....................错误!未定义书签。

4.7电子健康卡身份验证.......................错误!未定义书签。

5附件.....................................错误!未定义书签。

5.1数据代码对照表...........................错误!未定义书签。

电子健康卡业务接口规范

1概述

为简化医院HIS系统，以及其他第三方需要与卡管平台交互的系统接入，在卫生

部居民健康卡技术规范的基础上，对各机具厂商提供的居民健康卡读、写接口进行进

一步的封装，方便各业务应用系统的使用和维护。

通过本接口规范的实现，旨在达到以下目的：

•HIS厂商或其它需要接入卡管平台的系统，通过调用接口动态库（或控件），可

以进行电子健康卡读卡、电子健康卡发卡、电子健康卡打印。

•通过修改配置文件，使新增加的机具类型能完全适应上层应用的调用接口，即

上层应用接口不需修改代码就可以直接使用新的读写卡机具。

本规范详细说明了封装接口的定义、调用参数说明，以及相关数据的格式。

2适用范围及对象

本规范确定电子健康卡中数据存取的应用编程接口。基于符合规范《居民健康卡应

用规范》中的定义的居民健康卡特定数据项，依据居民健康卡在医疗卫生行业中的业务应

用，以及居民健康卡管理流程等要求，描述定义所需接口函数、参数数据类型以及接口的

调用方式。

本接口说明适用于卡管平台的开发人员、项目管理人员、与卡管平台相关的第三方应用

开发人员。

2.1接口调用前置约束条件

•接入机构必须是市级电子健康卡卡管平台联网单位；

•由市级平台统一分配用户名和密码；

•调用getAuthKey（组织机构代码,用户名，密码），获得认证字符串，如果在调用

各业务接口后返回“认证字符串失效”时，需要重新调用getAuthKey接口获

取新的认证字符串；

参数说明：

组织机构代码：为组织机构代码证上的9位代码（去掉连字符）。

2.2电子健康卡接口调用业务场景描述

二维码打印纸规格（推荐：2.5*2.5cm雅银树脂）

场景一（办理电子健康卡）

场景约束条件：

•办卡人必须出示本人身份证原件；

•可重复发电子卡；

接口调用时序图

场景二（电子健康卡读卡）

出示二维码进行扫码读取个人信息

接口调用时序图

3返回码表

返回码返回码描述

10000"成功"

10110z，WebService返回参数错误”

10109，zWebService返回卡不存在“

1010z/WebService返回卡已挂失“

1020z，WebService返回卡已注销“

10101"WebService返回机构代码错误”

10103“WebService返回密码错误〃

10112WebService返回错误的操作代码”

10105z，WebService认证字符串失效,请重新操作本操作”

10102"WebService用户名错误”

10108身份证未办卡

10109卡号不存在

10110参数错误

10111身份证号码不正确

10113错误的性别代码

10114姓名不能为空

10115身份证已经办理过

10116卡号已经存在

10117只有正常和挂失的卡才能进行补换卡

10118卡关联的居民信息不存在

10119只有正常状态的才能挂失

10121只有挂失状态的才能解挂失

10122补换卡时必需提供身份证或者原卡号

10123民族代码不正确

10124出生日期格式不正确

10125卡已被使用

10126消费类型不正确

10127旧卡已经在黑名单中

10128发卡时间格式不正确

10129网络异常

10130卡号和身份证号码关联不上

10131医疗费用支付方式不正确

10132婚姻状况代码不正确

10133学历代码不正确

10134证件类型不正确

10135职业代码不正确

10136地址类别不正确

10137疫苗接种日期不正确

10138AB0血型代码不正确

10139RH血型代码不正确

10140医学警示标志值域错误,应为T或F

10141芯片序列号不正确

10142发卡序列号不正确

10143身份证办理过多张健康卡

10144应用城市代码未填写或填写错误

10149对象或其属性值均为空，请检查语言对复杂对象的支持

10150卡号与身份证不相同

10151银行卡号错误

10152联系人关系不正确

10153芯片序列号重复

10154发卡方式错误

10155银行代码错误

10156该人属于贫困人口

4webServices调用接口规范

本节介绍以标准方式调用webServices的方法，及相关参数

4.1接口数据传输对象DTO封装说明

居民健康卡信息Cardinfo(DTO)数』居传输对象结构

卡的类别：1.正式卡2临时卡必填

klxStringILen

3电子健康卡。

电子健康卡标准规范的版本必填

gfbbString4Len

编号。如VI.1

orgCodeStringl-30Len发卡机构代码必填

fksjString8Len(YYYYMMDD)发卡时间必填

khString18Len卡号必填

aqmString3Len安全码必填

发卡序列号;首位：0代表“序必填

列号由卡片制造机构定

义”；1代表”序列号由卡

管系统定义”。

如首位为0,后续9个字符

数据由卡片制造

fkxlhStringlOLen机构自行定义，并负责保证数

据的唯一性；

如首位为1,后续9个字符

数据由卡管系统

自行定义，并负责保证该数

据在卡片应用城

市内的唯一性。

应用城市代码(机构所在行政必填

yycsdmString6Len

区代码)

必填

xpxlhString64Len芯片序列号/电子健康卡号

必填

yhkhString64Len银行卡号

健康卡状态

jkkztString1Len

1正常,3挂失，9：注销

发卡方式：1区域批量发卡2必填

医院现场发卡3银行网点发

卡4电信网点发卡5App在线

issuingModeString1Len申请6医疗卫生机构自

助机申请7微信公众号8支

付宝小程序9其它10微信小

程序11支付宝生活号

必填

bankCodeStringl-22Len银行代码

peopleinfoPeopleinfo居民信息必填

必填

isRealNameString1Len如已经实名认证，认证渠道为必

传（传输代码）

0.尚未实名认证

认证渠道：

1、微信认证

2、银联认证

3、支付宝认证

4、公安认证

9、其他认证

终端类型：1人工窗口2自助必填

terminalTypeString1Len

终端

qrTypeString1Len二维码类型0动态1静态必填

pcNameString64Len工作站名称必填

pclpString64Len工作站ip必填

macIdString64Len读证终端编号必填

支付账户类型：0,无；1,微必填

信；2,支付宝；3,银联；4,

payAccTypeString64Len

银行；5,统一支付平台；9,

其他；

注册途径11,APP；12,微信必填

公众帐号；13,支付宝服务号；

regChannelString64Len

21,自助机；31,窗口；41,

批量处理；

居民信息Peopleinfo（DTO）数据传输对象结构

xmString32Len姓名必填

性别按国家标准GB/T必填

xbStringILen

2261.1-2003

民族代码按国家标准必填

mzdmString2Len

GB3304-91

csrqString8Len(YYYYMMDD)出生日期必填

居民身份证号码（若为新生儿必填

sfzhmString18Len

发码则不填）

zjlxString2Len证件类别(CV02.01.101)必填

证件号码必填

（若卡类型为“2”，且为新生

儿没有出生证，则传“母亲身

zjhmString18Len

份证#新生儿出生日期#新生

儿性别#新生儿自编码（默认

01）”）

validStartDateString8Len证件有效期开始时间YYYYMMDI）

validEndDateString8Len证件有效期结束时间YYYYMMDI）

idlnstString128Len发证机关

1inkmanString50Len联系人姓名

telephoneStringHLen联系人电话

idPhotoStringCLOB证件照片转为base64

scenePhotoStringCLOB头像照片转为base64

languageStringllLen语言

人员类型。1：普通2:无证件儿

童

personnelTypeString5Len

仅无身份证件时按2传参，有身

份证件时均按1传参

多胎标记人员类型为2时必填

multifetalMarkStringILen

传输代码：0（单胎）1（多胎）

多胎标记为1时必填

multpripleBirthsStringILen

产次顺序号：例1、2、3

motherNameString50Len母亲姓名

motherldCodeString32Len母亲身份证号

人员类型为2时，与身份证号二

motherEmpiString64Len

选一填写

guardianNameString64Len监护人姓名

guardianldCodeString18Len监护人身份证号

guardianPhoneStringHLen监护人联系方式

provinceCodeStringlOLen居住省份代码参照《中华人民共

和国行政区划代码》

（GBT2260-2013X9位区划代码）

addressCityCodeStringlOLen居住城市代码参照《中华人民

共和国行政区划代码》

（GBT2260-2013）（9位区划代

码）

countyCodeStringlOLen居住县区代码参照《中华人民共

和国行政区划代码》

（GBT2260-2013X9位区划代码）

职业类别代码

1.国家机关、党群组织、企、

事业单位负责人

2.专业技术人员

3.办事人员和有关人员

professionTypeString3Len4.商业、服务业人员

5.农、林、牧、渔、水利业生

产人员

6.生产、运输设备操作人员及

有关人员

7.军人

8.不便分类的其他从业人员

9.无职业

见附录《职业代码》（VI.1）

jkdahString17Len健康档案号选填

xnhkhString18Len新农合卡号选填

fyzhdmString2Len婚姻状况代码（GB/T2261.2）必填

xldmString2Len文化程度代码（GB/T4658）必填

zydmString4Len职业类别代码GB/T6565必填

地址类别选填

dzlbStringILen（1.户籍地址2.现居住地

址）

地址-省（自治区、直辖市）选填

dzsfString20Len

的名称

dzsString20Len地址-市（地区、州）的名称选填

dzqxString20Len地址-县（区）的名称选填

地址-乡（镇、街道办事处）选填

dzxzString20Len

的名称

地址-村（街、路、弄等）的选填

dzcString20Len

名称

unitWrokString20Len工作单位选填

brdhString20Len本人电话号码选填

医疗费用支付方式：01.城镇必填

职工基本医疗保险；02.城镇

居民基本医疗保险；03.新型

ylfyzffsString2Len

农村合作医疗；04.贫困救助；

05.商业医疗保险；06.全公

费；07.全自费；99.其他

citizenshipString3Len参照数据字典【国籍】必填

birthPlaceString200Len出生地必填

domicileString250Len户籍所在地址必填

jzkkhString10Len就诊卡卡号

VirCard（卡信息）

virtualCardNumString64Len虚拟电子卡号必填

empiString64Len主索引ID必填

vuidString64Len电子健康卡ID必填

orgcodeString10Len健康卡签发机构代码必填

orgnameString64Len健康卡签发机构名称必填

健康卡失效日期，格式为：必填

erhcEnddateDate64Len

yyyy-mm-dd

peopleinfoPeopleinfo64Len居民信息必填

OperatorLoglnfo操作日志信息数据传输对象

科室代码参照数据字典必填

ksdmString15Len

【标准科室代码】

ksmcStringlOOLen科室名称必填

科室类型（1挂号科室2收费必填

科室

3门诊科室4住院科室5检查

KslxString2Len科室

6检验科室7处置治疗科室8

药房

9手术麻醉10其它科室）

SAM卡号；必填

SAMCodeString64Len如果是电子健康卡，请填

写固定值noSam

机具号，必填

如果是电子健康卡，再获

machineCodeString64Len

取不到机具号的时候，请填写

固定值SweepBlock

健康卡芯片号必填

如果是电子健康卡，请填

xpxlhString64Len

写电子健康卡ID（发卡返回

参数"vuid"）

操作（0：读操作/I：写操必填

operCodeStringILen

作）

操作时间必填

operTimeString20Len

(yyyy-MM-ddss)

就诊类型必填

medicalTypeStringILen1住院2门诊3急诊4体

检5其它

TerminalTypeStringILen1人工窗口2自助终端必填

AmountString20Len刷卡金额必填

支付方式（0无支付1银行卡支付必填

PayModeStringILen2院内预缴金支付3现金支付

4其它,5支付宝6微信）

发卡机构代码（需从健康卡必填

orgCodeString20Len

上读取）

BankCodeString20Len发卡银行机构代码必填

发卡应用城市代码（需从健必填

yycsdmString6Len

康卡上读取）

useOrgCodeString20Len刷卡机构代码必填

useOrgNameString20Len刷卡机构名称必填

useCityCodeString6Len刷卡应用城市代码必填

khString32Len卡号必填

xmString16Len姓名必填

诊疗环节代码，参照数据字必填

medStepcodeString4Len

典【诊疗环节代码】

用卡信息UseCardlnfo

就诊类型（1住院2门诊3急必填

medTypeString2Len

诊4体检5其它）

depTypeString2Len科室类型（见字典）必填

刷卡科室代码（见字典标注科必填

depCodeString4Len

室代码）

medStepcodeString16Len诊疗环节代码（见字典）必填

支付金额（当诊疗环节为

payAmountString16Len

010105收费的情况下，必填）

支付渠道（当诊疗环节为

payChannelString16Len010105收费的情况下，必填）

参照附录《支付渠道编码》

二维码来源渠道2医院窗口必填

5第三方APP6医疗卫生机

issuingModeString2Len构自助机7微信公众号8

支付宝小程序9其它10微信

小程序11支付宝生活号

终端类型（1人工窗口2自助终必填

terminalTypeString2Len

端99其他）

识读终端编号（由4.10终端必填

machineCodeString64Len

注册接口返回）

绑卡信息（bCardlnfo）DT0数据传输对象

khStringl-64Len子卡卡号必填

klxString2Len卡类型参照数据必填

字典

fkorgcodeStringl-22Len子卡发卡机构代必填

码

fkorgnameString32Len子卡发卡机构名必填

称

yycsdmString32Len应用城市代码必填

applytimeString7Len操作时间必填

YYYYMMDD

statusString2Len卡状态，挂失，必填

注销状态不可操

作（正常，挂失，

注销）

operateTypeString2Len操作类型必填（1绑卡2换

绑3解绑）

绑卡索引（bindPeoplelnfo）DTO数据传输对象

sfzhmString18Len身份证号码当vuid为空必填

vuidString64Len电子健康卡id当sfzhm,xm,zjhm,

zjlx为空时必填

xmStringlOLen姓名当vuid为空必填

ZjhmString18Len证件号码当vuid为空必填

ZjlxString2Len证件类型当vuid为空必填

终端注册(TerminalInfo)DTO之攵据传输对象

terminalPurposeString50Len终端的用途必填

terminalNameString30Len终端名称必填

terminalTypeString20Len终端类型（1人工窗必填

口2自助终端99

其他）

serialNumberStr