電子健康卡業(yè)務(wù)WebService接口規(guī)范

電子健康卡業(yè)務(wù)\ZVebService接口規(guī)范

（文檔版本vi.5）

”盛1m嬲融褊

2018年10月

版本說(shuō)明

版本更新日期更新說(shuō)明修改人

VI.12019/01/15初始版文檔形成張凡

VI.22019/03/27修改示例報(bào)文郭珊

VI.32019/10/09支持新生兒發(fā)碼用碼：杜志

1有出生證的新生兒發(fā)碼證件類型傳“08”，

證件號(hào)碼傳出生證號(hào)；

2無(wú)出生證的新生兒發(fā)碼卡類型傳“2”，證

件類型傳“99”，證件號(hào)碼內(nèi)容傳“母親身

份證#新生兒出生日期#新生兒性別#新生兒

自編碼（默認(rèn)01）”。

VI.42020/02/16線下讀碼接口新增跨域讀碼邏輯，二維碼內(nèi)萬(wàn)家樂(lè)

容改為國(guó)家規(guī)范2.4版本，見(jiàn)出參QRCode標(biāo)

紅部分。

VI.52021/05/31syncCardInfo>updateCardlnfo接口中傳輸

對(duì)象peopleinfo補(bǔ)充字段、isRealName添加

實(shí)名渠道，virldCardVerify中傳輸對(duì)象

UseCardlnfo補(bǔ)充字段，更新證件類型、診療

環(huán)節(jié)等字典，添加regTerminal終端注冊(cè)接

口（見(jiàn)標(biāo)紅部分）。

VI.62021/07/19新增注冊(cè)終端（regTerminal）返回劉方瑞

machineCode

目次

1概述.....................................錯(cuò)誤!未定義書(shū)簽。

2適用范圍及對(duì)象...........................錯(cuò)誤!未定義書(shū)簽。

2.1接口調(diào)用前置約束條件.....................錯(cuò)誤!未定義書(shū)簽。

2.2電子健康卡接口調(diào)用業(yè)務(wù)場(chǎng)景描述...........錯(cuò)誤!未定義書(shū)簽。

3返回碼表.........................................錯(cuò)誤!未定義書(shū)簽。

4webServices調(diào)用接口規(guī)范........................錯(cuò)誤!未定義書(shū)簽。

4.1接口數(shù)據(jù)傳輸對(duì)象DTO封裝說(shuō)明.............錯(cuò)誤!未定義書(shū)簽。

4.2接入機(jī)構(gòu)身份認(rèn)證接口.....................錯(cuò)誤!未定義書(shū)簽。

4.3發(fā)卡同步接口.............................錯(cuò)誤!未定義書(shū)簽。

4.4信息更新接口.............................錯(cuò)誤!未定義書(shū)簽。

4.5更改卡狀態(tài)...............................錯(cuò)誤!未定義書(shū)簽。

4.6電子卡靜態(tài)二維碼下載.....................錯(cuò)誤!未定義書(shū)簽。

4.7電子健康卡身份驗(yàn)證.......................錯(cuò)誤!未定義書(shū)簽。

5附件.....................................錯(cuò)誤!未定義書(shū)簽。

5.1數(shù)據(jù)代碼對(duì)照表...........................錯(cuò)誤!未定義書(shū)簽。

電子健康卡業(yè)務(wù)接口規(guī)范

1概述

為簡(jiǎn)化醫(yī)院HIS系統(tǒng)，以及其他第三方需要與卡管平臺(tái)交互的系統(tǒng)接入，在衛(wèi)生

部居民健康卡技術(shù)規(guī)范的基礎(chǔ)上，對(duì)各機(jī)具廠商提供的居民健康卡讀、寫接口進(jìn)行進(jìn)

一步的封裝，方便各業(yè)務(wù)應(yīng)用系統(tǒng)的使用和維護(hù)。

通過(guò)本接口規(guī)范的實(shí)現(xiàn)，旨在達(dá)到以下目的：

?HIS廠商或其它需要接入卡管平臺(tái)的系統(tǒng)，通過(guò)調(diào)用接口動(dòng)態(tài)庫(kù)（或控件），可

以進(jìn)行電子健康卡讀卡、電子健康卡發(fā)卡、電子健康卡打印。

?通過(guò)修改配置文件，使新增加的機(jī)具類型能完全適應(yīng)上層應(yīng)用的調(diào)用接口，即

上層應(yīng)用接口不需修改代碼就可以直接使用新的讀寫卡機(jī)具。

本規(guī)范詳細(xì)說(shuō)明了封裝接口的定義、調(diào)用參數(shù)說(shuō)明，以及相關(guān)數(shù)據(jù)的格式。

2適用范圍及對(duì)象

本規(guī)范確定電子健康卡中數(shù)據(jù)存取的應(yīng)用編程接口?；诜弦?guī)范《居民健康卡應(yīng)

用規(guī)范》中的定義的居民健康卡特定數(shù)據(jù)項(xiàng)，依據(jù)居民健康卡在醫(yī)療衛(wèi)生行業(yè)中的業(yè)務(wù)應(yīng)

用，以及居民健康卡管理流程等要求，描述定義所需接口函數(shù)、參數(shù)數(shù)據(jù)類型以及接口的

調(diào)用方式。

本接口說(shuō)明適用于卡管平臺(tái)的開(kāi)發(fā)人員、項(xiàng)目管理人員、與卡管平臺(tái)相關(guān)的第三方應(yīng)用

開(kāi)發(fā)人員。

2.1接口調(diào)用前置約束條件

?接入機(jī)構(gòu)必須是市級(jí)電子健康卡卡管平臺(tái)聯(lián)網(wǎng)單位；

?由市級(jí)平臺(tái)統(tǒng)一分配用戶名和密碼；

?調(diào)用getAuthKey（組織機(jī)構(gòu)代碼,用戶名，密碼），獲得認(rèn)證字符串，如果在調(diào)用

各業(yè)務(wù)接口后返回“認(rèn)證字符串失效”時(shí)，需要重新調(diào)用getAuthKey接口獲

取新的認(rèn)證字符串；

參數(shù)說(shuō)明：

組織機(jī)構(gòu)代碼：為組織機(jī)構(gòu)代碼證上的9位代碼（去掉連字符）。

2.2電子健康卡接口調(diào)用業(yè)務(wù)場(chǎng)景描述

二維碼打印紙規(guī)格（推薦：2.5*2.5cm雅銀樹(shù)脂）

場(chǎng)景一（辦理電子健康卡）

場(chǎng)景約束條件：

?辦卡人必須出示本人身份證原件；

?可重復(fù)發(fā)電子卡；

接口調(diào)用時(shí)序圖

場(chǎng)景二（電子健康卡讀卡）

出示二維碼進(jìn)行掃碼讀取個(gè)人信息

接口調(diào)用時(shí)序圖

3返回碼表

返回碼返回碼描述

10000"成功"

10110z，WebService返回參數(shù)錯(cuò)誤”

10109，zWebService返回卡不存在“

1010z/WebService返回卡已掛失“

1020z，WebService返回卡已注銷“

10101"WebService返回機(jī)構(gòu)代碼錯(cuò)誤”

10103“WebService返回密碼錯(cuò)誤〃

10112WebService返回錯(cuò)誤的操作代碼”

10105z，WebService認(rèn)證字符串失效,請(qǐng)重新操作本操作”

10102"WebService用戶名錯(cuò)誤”

10108身份證未辦卡

10109卡號(hào)不存在

10110參數(shù)錯(cuò)誤

10111身份證號(hào)碼不正確

10113錯(cuò)誤的性別代碼

10114姓名不能為空

10115身份證已經(jīng)辦理過(guò)

10116卡號(hào)已經(jīng)存在

10117只有正常和掛失的卡才能進(jìn)行補(bǔ)換卡

10118卡關(guān)聯(lián)的居民信息不存在

10119只有正常狀態(tài)的才能掛失

10121只有掛失狀態(tài)的才能解掛失

10122補(bǔ)換卡時(shí)必需提供身份證或者原卡號(hào)

10123民族代碼不正確

10124出生日期格式不正確

10125卡已被使用

10126消費(fèi)類型不正確

10127舊卡已經(jīng)在黑名單中

10128發(fā)卡時(shí)間格式不正確

10129網(wǎng)絡(luò)異常

10130卡號(hào)和身份證號(hào)碼關(guān)聯(lián)不上

10131醫(yī)療費(fèi)用支付方式不正確

10132婚姻狀況代碼不正確

10133學(xué)歷代碼不正確

10134證件類型不正確

10135職業(yè)代碼不正確

10136地址類別不正確

10137疫苗接種日期不正確

10138AB0血型代碼不正確

10139RH血型代碼不正確

10140醫(yī)學(xué)警示標(biāo)志值域錯(cuò)誤,應(yīng)為T或F

10141芯片序列號(hào)不正確

10142發(fā)卡序列號(hào)不正確

10143身份證辦理過(guò)多張健康卡

10144應(yīng)用城市代碼未填寫或填寫錯(cuò)誤

10149對(duì)象或其屬性值均為空，請(qǐng)檢查語(yǔ)言對(duì)復(fù)雜對(duì)象的支持

10150卡號(hào)與身份證不相同

10151銀行卡號(hào)錯(cuò)誤

10152聯(lián)系人關(guān)系不正確

10153芯片序列號(hào)重復(fù)

10154發(fā)卡方式錯(cuò)誤

10155銀行代碼錯(cuò)誤

10156該人屬于貧困人口

4webServices調(diào)用接口規(guī)范

本節(jié)介紹以標(biāo)準(zhǔn)方式調(diào)用webServices的方法，及相關(guān)參數(shù)

4.1接口數(shù)據(jù)傳輸對(duì)象DTO封裝說(shuō)明

居民健康卡信息Cardinfo(DTO)數(shù)』居傳輸對(duì)象結(jié)構(gòu)

卡的類別：1.正式卡2臨時(shí)卡必填

klxStringILen

3電子健康卡。

電子健康卡標(biāo)準(zhǔn)規(guī)范的版本必填

gfbbString4Len

編號(hào)。如VI.1

orgCodeStringl-30Len發(fā)卡機(jī)構(gòu)代碼必填

fksjString8Len(YYYYMMDD)發(fā)卡時(shí)間必填

khString18Len卡號(hào)必填

aqmString3Len安全碼必填

發(fā)卡序列號(hào);首位：0代表“序必填

列號(hào)由卡片制造機(jī)構(gòu)定

義”；1代表”序列號(hào)由卡

管系統(tǒng)定義”。

如首位為0,后續(xù)9個(gè)字符

數(shù)據(jù)由卡片制造

fkxlhStringlOLen機(jī)構(gòu)自行定義，并負(fù)責(zé)保證數(shù)

據(jù)的唯一性；

如首位為1,后續(xù)9個(gè)字符

數(shù)據(jù)由卡管系統(tǒng)

自行定義，并負(fù)責(zé)保證該數(shù)

據(jù)在卡片應(yīng)用城

市內(nèi)的唯一性。

應(yīng)用城市代碼(機(jī)構(gòu)所在行政必填

yycsdmString6Len

區(qū)代碼)

必填

xpxlhString64Len芯片序列號(hào)/電子健康卡號(hào)

必填

yhkhString64Len銀行卡號(hào)

健康卡狀態(tài)

jkkztString1Len

1正常,3掛失，9：注銷

發(fā)卡方式：1區(qū)域批量發(fā)卡2必填

醫(yī)院現(xiàn)場(chǎng)發(fā)卡3銀行網(wǎng)點(diǎn)發(fā)

卡4電信網(wǎng)點(diǎn)發(fā)卡5App在線

issuingModeString1Len申請(qǐng)6醫(yī)療衛(wèi)生機(jī)構(gòu)自

助機(jī)申請(qǐng)7微信公眾號(hào)8支

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

程序11支付寶生活號(hào)

必填

bankCodeStringl-22Len銀行代碼

peopleinfoPeopleinfo居民信息必填

必填

isRealNameString1Len如已經(jīng)實(shí)名認(rèn)證，認(rèn)證渠道為必

傳（傳輸代碼）

0.尚未實(shí)名認(rèn)證

認(rèn)證渠道：

1、微信認(rèn)證

2、銀聯(lián)認(rèn)證

3、支付寶認(rèn)證

4、公安認(rèn)證

9、其他認(rèn)證

終端類型：1人工窗口2自助必填

terminalTypeString1Len

終端

qrTypeString1Len二維碼類型0動(dòng)態(tài)1靜態(tài)必填

pcNameString64Len工作站名稱必填

pclpString64Len工作站ip必填

macIdString64Len讀證終端編號(hào)必填

支付賬戶類型：0,無(wú)；1,微必填

信；2,支付寶；3,銀聯(lián)；4,

payAccTypeString64Len

銀行；5,統(tǒng)一支付平臺(tái)；9,

其他；

注冊(cè)途徑11,APP；12,微信必填

公眾帳號(hào)；13,支付寶服務(wù)號(hào)；

regChannelString64Len

21,自助機(jī)；31,窗口；41,

批量處理；

居民信息Peopleinfo（DTO）數(shù)據(jù)傳輸對(duì)象結(jié)構(gòu)

xmString32Len姓名必填

性別按國(guó)家標(biāo)準(zhǔn)GB/T必填

xbStringILen

2261.1-2003

民族代碼按國(guó)家標(biāo)準(zhǔn)必填

mzdmString2Len

GB3304-91

csrqString8Len(YYYYMMDD)出生日期必填

居民身份證號(hào)碼（若為新生兒必填

sfzhmString18Len

發(fā)碼則不填）

zjlxString2Len證件類別(CV02.01.101)必填

證件號(hào)碼必填

（若卡類型為“2”，且為新生

兒沒(méi)有出生證，則傳“母親身

zjhmString18Len

份證#新生兒出生日期#新生

兒性別#新生兒自編碼（默認(rèn)

01）”）

validStartDateString8Len證件有效期開(kāi)始時(shí)間YYYYMMDI）

validEndDateString8Len證件有效期結(jié)束時(shí)間YYYYMMDI）

idlnstString128Len發(fā)證機(jī)關(guān)

1inkmanString50Len聯(lián)系人姓名

telephoneStringHLen聯(lián)系人電話

idPhotoStringCLOB證件照片轉(zhuǎn)為base64

scenePhotoStringCLOB頭像照片轉(zhuǎn)為base64

languageStringllLen語(yǔ)言

人員類型。1：普通2:無(wú)證件兒

童

personnelTypeString5Len

僅無(wú)身份證件時(shí)按2傳參，有身

份證件時(shí)均按1傳參

多胎標(biāo)記人員類型為2時(shí)必填

multifetalMarkStringILen

傳輸代碼：0（單胎）1（多胎）

多胎標(biāo)記為1時(shí)必填

multpripleBirthsStringILen

產(chǎn)次順序號(hào)：例1、2、3

motherNameString50Len母親姓名

motherldCodeString32Len母親身份證號(hào)

人員類型為2時(shí)，與身份證號(hào)二

motherEmpiString64Len

選一填寫

guardianNameString64Len監(jiān)護(hù)人姓名

guardianldCodeString18Len監(jiān)護(hù)人身份證號(hào)

guardianPhoneStringHLen監(jiān)護(hù)人聯(lián)系方式

provinceCodeStringlOLen居住省份代碼參照《中華人民共

和國(guó)行政區(qū)劃代碼》

（GBT2260-2013X9位區(qū)劃代碼）

addressCityCodeStringlOLen居住城市代碼參照《中華人民

共和國(guó)行政區(qū)劃代碼》

（GBT2260-2013）（9位區(qū)劃代

碼）

countyCodeStringlOLen居住縣區(qū)代碼參照《中華人民共

和國(guó)行政區(qū)劃代碼》

（GBT2260-2013X9位區(qū)劃代碼）

職業(yè)類別代碼

1.國(guó)家機(jī)關(guān)、黨群組織、企、

事業(yè)單位負(fù)責(zé)人

2.專業(yè)技術(shù)人員

3.辦事人員和有關(guān)人員

professionTypeString3Len4.商業(yè)、服務(wù)業(yè)人員

5.農(nóng)、林、牧、漁、水利業(yè)生

產(chǎn)人員

6.生產(chǎn)、運(yùn)輸設(shè)備操作人員及

有關(guān)人員

7.軍人

8.不便分類的其他從業(yè)人員

9.無(wú)職業(yè)

見(jiàn)附錄《職業(yè)代碼》（VI.1）

jkdahString17Len健康檔案號(hào)選填

xnhkhString18Len新農(nóng)合卡號(hào)選填

fyzhdmString2Len婚姻狀況代碼（GB/T2261.2）必填

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

zydmString4Len職業(yè)類別代碼GB/T6565必填

地址類別選填

dzlbStringILen（1.戶籍地址2.現(xiàn)居住地

址）

地址-?。ㄗ灾螀^(qū)、直轄市）選填

dzsfString20Len

的名稱

dzsString20Len地址-市（地區(qū)、州）的名稱選填

dzqxString20Len地址-縣（區(qū)）的名稱選填

地址-鄉(xiāng)（鎮(zhèn)、街道辦事處）選填

dzxzString20Len

的名稱

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

dzcString20Len

名稱

unitWrokString20Len工作單位選填

brdhString20Len本人電話號(hào)碼選填

醫(yī)療費(fèi)用支付方式：01.城鎮(zhèn)必填

職工基本醫(yī)療保險(xiǎn)；02.城鎮(zhèn)

居民基本醫(yī)療保險(xiǎn)；03.新型

ylfyzffsString2Len

農(nóng)村合作醫(yī)療；04.貧困救助；

05.商業(yè)醫(yī)療保險(xiǎn)；06.全公

費(fèi)；07.全自費(fèi)；99.其他

citizenshipString3Len參照數(shù)據(jù)字典【國(guó)籍】必填

birthPlaceString200Len出生地必填

domicileString250Len戶籍所在地址必填

jzkkhString10Len就診卡卡號(hào)

VirCard（卡信息）

virtualCardNumString64Len虛擬電子卡號(hào)必填

empiString64Len主索引ID必填

vuidString64Len電子健康卡ID必填

orgcodeString10Len健康卡簽發(fā)機(jī)構(gòu)代碼必填

orgnameString64Len健康卡簽發(fā)機(jī)構(gòu)名稱必填

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

erhcEnddateDate64Len

yyyy-mm-dd

peopleinfoPeopleinfo64Len居民信息必填

OperatorLoglnfo操作日志信息數(shù)據(jù)傳輸對(duì)象

科室代碼參照數(shù)據(jù)字典必填

ksdmString15Len

【標(biāo)準(zhǔn)科室代碼】

ksmcStringlOOLen科室名稱必填

科室類型（1掛號(hào)科室2收費(fèi)必填

科室

3門診科室4住院科室5檢查

KslxString2Len科室

6檢驗(yàn)科室7處置治療科室8

藥房

9手術(shù)麻醉10其它科室）

SAM卡號(hào)；必填

SAMCodeString64Len如果是電子健康卡，請(qǐng)?zhí)?/p>

寫固定值noSam

機(jī)具號(hào)，必填

如果是電子健康卡，再獲

machineCodeString64Len

取不到機(jī)具號(hào)的時(shí)候，請(qǐng)?zhí)顚?/p>

固定值SweepBlock

健康卡芯片號(hào)必填

如果是電子健康卡，請(qǐng)?zhí)?/p>

xpxlhString64Len

寫電子健康卡ID（發(fā)卡返回

參數(shù)"vuid"）

操作（0：讀操作/I：寫操必填

operCodeStringILen

作）

操作時(shí)間必填

operTimeString20Len

(yyyy-MM-ddss)

就診類型必填

medicalTypeStringILen1住院2門診3急診4體

檢5其它

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

AmountString20Len刷卡金額必填

支付方式（0無(wú)支付1銀行卡支付必填

PayModeStringILen2院內(nèi)預(yù)繳金支付3現(xiàn)金支付

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

發(fā)卡機(jī)構(gòu)代碼（需從健康卡必填

orgCodeString20Len

上讀?。?/p>

BankCodeString20Len發(fā)卡銀行機(jī)構(gòu)代碼必填

發(fā)卡應(yīng)用城市代碼（需從健必填

yycsdmString6Len

康卡上讀?。?/p>

useOrgCodeString20Len刷卡機(jī)構(gòu)代碼必填

useOrgNameString20Len刷卡機(jī)構(gòu)名稱必填

useCityCodeString6Len刷卡應(yīng)用城市代碼必填

khString32Len卡號(hào)必填

xmString16Len姓名必填

診療環(huán)節(jié)代碼，參照數(shù)據(jù)字必填

medStepcodeString4Len

典【診療環(huán)節(jié)代碼】

用卡信息UseCardlnfo

就診類型（1住院2門診3急必填

medTypeString2Len

診4體檢5其它）

depTypeString2Len科室類型（見(jiàn)字典）必填

刷卡科室代碼（見(jiàn)字典標(biāo)注科必填

depCodeString4Len

室代碼）

medStepcodeString16Len診療環(huán)節(jié)代碼（見(jiàn)字典）必填

支付金額（當(dāng)診療環(huán)節(jié)為

payAmountString16Len

010105收費(fèi)的情況下，必填）

支付渠道（當(dāng)診療環(huán)節(jié)為

payChannelString16Len010105收費(fèi)的情況下，必填）

參照附錄《支付渠道編碼》

二維碼來(lái)源渠道2醫(yī)院窗口必填

5第三方APP6醫(yī)療衛(wèi)生機(jī)

issuingModeString2Len構(gòu)自助機(jī)7微信公眾號(hào)8

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

小程序11支付寶生活號(hào)

終端類型（1人工窗口2自助終必填

terminalTypeString2Len

端99其他）

識(shí)讀終端編號(hào)（由4.10終端必填

machineCodeString64Len

注冊(cè)接口返回）

綁卡信息（bCardlnfo）DT0數(shù)據(jù)傳輸對(duì)象

khStringl-64Len子卡卡號(hào)必填

klxString2Len卡類型參照數(shù)據(jù)必填

字典

fkorgcodeStringl-22Len子卡發(fā)卡機(jī)構(gòu)代必填

碼

fkorgnameString32Len子卡發(fā)卡機(jī)構(gòu)名必填

稱

yycsdmString32Len應(yīng)用城市代碼必填

applytimeString7Len操作時(shí)間必填

YYYYMMDD

statusString2Len卡狀態(tài)，掛失，必填

注銷狀態(tài)不可操

作（正常，掛失，

注銷）

operateTypeString2Len操作類型必填（1綁卡2換

綁3解綁）

綁卡索引（bindPeoplelnfo）DTO數(shù)據(jù)傳輸對(duì)象

sfzhmString18Len身份證號(hào)碼當(dāng)vuid為空必填

vuidString64Len電子健康卡id當(dāng)sfzhm,xm,zjhm,

zjlx為空時(shí)必填

xmStringlOLen姓名當(dāng)vuid為空必填

ZjhmString18Len證件號(hào)碼當(dāng)vuid為空必填

ZjlxString2Len證件類型當(dāng)vuid為空必填

終端注冊(cè)(TerminalInfo)DTO之攵據(jù)傳輸對(duì)象

terminalPurposeString50Len終端的用途必填

terminalNameString30Len終端名稱必填

terminalTypeString20Len終端類型（1人工窗必填

口2自助終端99

其他）

serialNumberStr