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

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

（文檔版本vi.5）

”盛1m嬲融褊

2018年10月

版本說明

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

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

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

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

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

證件號碼傳出生證號；

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

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

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

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

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

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

紅部分。

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

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

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

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

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

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

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

machineCode

目次

1概述.....................................錯誤!未定義書簽。

2適用范圍及對象...........................錯誤!未定義書簽。

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

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

3返回碼表.........................................錯誤!未定義書簽。

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

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

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

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

4.4信息更新接口.............................錯誤!未定義書簽。

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

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

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

5附件.....................................錯誤!未定義書簽。

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

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

1概述

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

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

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

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

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

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

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

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

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

2適用范圍及對象

本規(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)用方式。

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

開發(fā)人員。

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

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

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

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

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

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

參數(shù)說明：

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

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

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

場景一（辦理電子健康卡）

場景約束條件：

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

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

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

場景二（電子健康卡讀卡）

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

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

3返回碼表

返回碼返回碼描述

10000"成功"

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

10109，zWebService返回卡不存在“

1010z/WebService返回卡已掛失“

1020z，WebService返回卡已注銷“

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

10103“WebService返回密碼錯誤〃

10112WebService返回錯誤的操作代碼”

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

10102"WebService用戶名錯誤”

10108身份證未辦卡

10109卡號不存在

10110參數(shù)錯誤

10111身份證號碼不正確

10113錯誤的性別代碼

10114姓名不能為空

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

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

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

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

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

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

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

10123民族代碼不正確

10124出生日期格式不正確

10125卡已被使用

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

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

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

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

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

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

10132婚姻狀況代碼不正確

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

10134證件類型不正確

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

10136地址類別不正確

10137疫苗接種日期不正確

10138AB0血型代碼不正確

10139RH血型代碼不正確

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

10141芯片序列號不正確

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

10143身份證辦理過多張健康卡

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

10149對象或其屬性值均為空，請檢查語言對復(fù)雜對象的支持

10150卡號與身份證不相同

10151銀行卡號錯誤

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

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

10154發(fā)卡方式錯誤

10155銀行代碼錯誤

10156該人屬于貧困人口

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

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

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

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

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

klxStringILen

3電子健康卡。

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

gfbbString4Len

編號。如VI.1

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

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

khString18Len卡號必填

aqmString3Len安全碼必填

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

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

義”；1代表”序列號由卡

管系統(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芯片序列號/電子健康卡號

必填

yhkhString64Len銀行卡號

健康卡狀態(tài)

jkkztString1Len

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

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

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

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

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

助機(jī)申請7微信公眾號8支

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

程序11支付寶生活號

必填

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動態(tài)1靜態(tài)必填

pcNameString64Len工作站名稱必填

pclpString64Len工作站ip必填

macIdString64Len讀證終端編號必填

支付賬戶類型：0,無；1,微必填

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

payAccTypeString64Len

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

其他；

注冊途徑11,APP；12,微信必填

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

regChannelString64Len

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

批量處理；

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

xmString32Len姓名必填

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

xbStringILen

2261.1-2003

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

mzdmString2Len

GB3304-91

csrqString8Len(YYYYMMDD)出生日期必填

居民身份證號碼（若為新生兒必填

sfzhmString18Len

發(fā)碼則不填）

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

證件號碼必填

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

兒沒有出生證，則傳“母親身

zjhmString18Len

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

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

01）”）

validStartDateString8Len證件有效期開始時(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語言

人員類型。1：普通2:無證件兒

童

personnelTypeString5Len

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

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

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

multifetalMarkStringILen

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

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

multpripleBirthsStringILen

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

motherNameString50Len母親姓名

motherldCodeString32Len母親身份證號

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

motherEmpiString64Len

選一填寫

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

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

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

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

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

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

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

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

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

碼）

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

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

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

職業(yè)類別代碼

1.國家機(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.無職業(yè)

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

jkdahString17Len健康檔案號選填

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

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本人電話號碼選填

醫(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ù)字典【國籍】必填

birthPlaceString200Len出生地必填

domicileString250Len戶籍所在地址必填

jzkkhString10Len就診卡卡號

VirCard（卡信息）

virtualCardNumString64Len虛擬電子卡號必填

empiString64Len主索引ID必填

vuidString64Len電子健康卡ID必填

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

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

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

erhcEnddateDate64Len

yyyy-mm-dd

peopleinfoPeopleinfo64Len居民信息必填

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

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

ksdmString15Len

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

ksmcStringlOOLen科室名稱必填

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

科室

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

KslxString2Len科室

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

藥房

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

SAM卡號；必填

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

寫固定值noSam

機(jī)具號，必填

如果是電子健康卡，再獲

machineCodeString64Len

取不到機(jī)具號的時(shí)候，請?zhí)顚?/p>

固定值SweepBlock

健康卡芯片號必填

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

xpxlhString64Len

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

參數(shù)"vuid"）

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

operCodeStringILen

作）

操作時(shí)間必填

operTimeString20Len

(yyyy-MM-ddss)

就診類型必填

medicalTypeStringILen1住院2門診3急診4體

檢5其它

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

AmountString20Len刷卡金額必填

支付方式（0無支付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卡號必填

xmString16Len姓名必填

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

medStepcodeString4Len

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

用卡信息UseCardlnfo

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

medTypeString2Len

診4體檢5其它）

depTypeString2Len科室類型（見字典）必填

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

depCodeString4Len

室代碼）

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

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

payAmountString16Len

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

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

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

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

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

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

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

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

小程序11支付寶生活號

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

terminalTypeString2Len

端99其他）

識讀終端編號（由4.10終端必填

machineCodeString64Len

注冊接口返回）

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

khStringl-64Len子卡卡號必填

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ù)傳輸對象

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

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

zjlx為空時(shí)必填

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

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

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

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

terminalPurposeString50Len終端的用途必填

terminalNameString30Len終端名稱必填

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

口2自助終端99

其他）

serialNumberStr