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

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

（文檔版本vi.5）

”盛1m嬲融褊

2018年10月

版本說明

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

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

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

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

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

證件號碼傳出生證號；

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

件類型傳“99”，證件號碼內容傳“母親身

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

自編碼（默認01）”。

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

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

紅部分。

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

對象peopleinfo補充字段、isRealName添加

實名渠道，virldCardVerify中傳輸對象

UseCardlnfo補充字段，更新證件類型、診療

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

口（見標紅部分）。

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

machineCode

目次

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

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

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

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

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

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

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

4.2接入機構身份認證接口.....................錯誤!未定義書簽。

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

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

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

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

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

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

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

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

1概述

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

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

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

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

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

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

?通過修改配置文件，使新增加的機具類型能完全適應上層應用的調用接口，即

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

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

2適用范圍及對象

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

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

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

調用方式。

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

開發(fā)人員。

2.1接口調用前置約束條件

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

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

?調用getAuthKey（組織機構代碼,用戶名，密碼），獲得認證字符串，如果在調用

各業(yè)務接口后返回“認證字符串失效”時，需要重新調用getAuthKey接口獲

取新的認證字符串；

參數(shù)說明：

組織機構代碼：為組織機構代碼證上的9位代碼（去掉連字符）。

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

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

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

場景約束條件：

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

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

接口調用時序圖

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

出示二維碼進行掃碼讀取個人信息

接口調用時序圖

3返回碼表

返回碼返回碼描述

10000"成功"

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

10109，zWebService返回卡不存在“

1010z/WebService返回卡已掛失“

1020z，WebService返回卡已注銷“

10101"WebService返回機構代碼錯誤”

10103“WebService返回密碼錯誤〃

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

10105z，WebService認證字符串失效,請重新操作本操作”

10102"WebService用戶名錯誤”

10108身份證未辦卡

10109卡號不存在

10110參數(shù)錯誤

10111身份證號碼不正確

10113錯誤的性別代碼

10114姓名不能為空

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

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

10117只有正常和掛失的卡才能進行補換卡

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

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

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

10122補換卡時必需提供身份證或者原卡號

10123民族代碼不正確

10124出生日期格式不正確

10125卡已被使用

10126消費類型不正確

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

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

10129網(wǎng)絡異常

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

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

10132婚姻狀況代碼不正確

10133學歷代碼不正確

10134證件類型不正確

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

10136地址類別不正確

10137疫苗接種日期不正確

10138AB0血型代碼不正確

10139RH血型代碼不正確

10140醫(yī)學警示標志值域錯誤,應為T或F

10141芯片序列號不正確

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

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

10144應用城市代碼未填寫或填寫錯誤

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

10150卡號與身份證不相同

10151銀行卡號錯誤

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

10153芯片序列號重復

10154發(fā)卡方式錯誤

10155銀行代碼錯誤

10156該人屬于貧困人口

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

本節(jié)介紹以標準方式調用webServices的方法，及相關參數(shù)

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

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

卡的類別：1.正式卡2臨時卡必填

klxStringILen

3電子健康卡。

電子健康卡標準規(guī)范的版本必填

gfbbString4Len

編號。如VI.1

orgCodeStringl-30Len發(fā)卡機構代碼必填

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

khString18Len卡號必填

aqmString3Len安全碼必填

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

列號由卡片制造機構定

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

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

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

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

fkxlhStringlOLen機構自行定義，并負責保證數(shù)

據(jù)的唯一性；

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

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

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

據(jù)在卡片應用城

市內的唯一性。

應用城市代碼(機構所在行政必填

yycsdmString6Len

區(qū)代碼)

必填

xpxlhString64Len芯片序列號/電子健康卡號

必填

yhkhString64Len銀行卡號

健康卡狀態(tài)

jkkztString1Len

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

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

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

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

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

助機申請7微信公眾號8支

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

程序11支付寶生活號

必填

bankCodeStringl-22Len銀行代碼

peopleinfoPeopleinfo居民信息必填

必填

isRealNameString1Len如已經(jīng)實名認證，認證渠道為必

傳（傳輸代碼）

0.尚未實名認證

認證渠道：

1、微信認證

2、銀聯(lián)認證

3、支付寶認證

4、公安認證

9、其他認證

終端類型：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,支付寶服務號；

regChannelString64Len

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

批量處理；

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

xmString32Len姓名必填

性別按國家標準GB/T必填

xbStringILen

2261.1-2003

民族代碼按國家標準必填

mzdmString2Len

GB3304-91

csrqString8Len(YYYYMMDD)出生日期必填

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

sfzhmString18Len

發(fā)碼則不填）

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

證件號碼必填

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

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

zjhmString18Len

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

兒性別#新生兒自編碼（默認

01）”）

validStartDateString8Len證件有效期開始時間YYYYMMDI）

validEndDateString8Len證件有效期結束時間YYYYMMDI）

idlnstString128Len發(fā)證機關

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

telephoneStringHLen聯(lián)系人電話

idPhotoStringCLOB證件照片轉為base64

scenePhotoStringCLOB頭像照片轉為base64

languageStringllLen語言

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

童

personnelTypeString5Len

僅無身份證件時按2傳參，有身

份證件時均按1傳參

多胎標記人員類型為2時必填

multifetalMarkStringILen

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

多胎標記為1時必填

multpripleBirthsStringILen

產次順序號：例1、2、3

motherNameString50Len母親姓名

motherldCodeString32Len母親身份證號

人員類型為2時，與身份證號二

motherEmpiString64Len

選一填寫

guardianNameString64Len監(jiān)護人姓名

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

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

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

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

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

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

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

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

碼）

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

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

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

職業(yè)類別代碼

1.國家機關、黨群組織、企、

事業(yè)單位負責人

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

3.辦事人員和有關人員

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

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

產人員

6.生產、運輸設備操作人員及

有關人員

7.軍人

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

9.無職業(yè)

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

jkdahString17Len健康檔案號選填

xnhkhString18Len新農合卡號選填

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ī)療費用支付方式：01.城鎮(zhèn)必填

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

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

ylfyzffsString2Len

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

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

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

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

birthPlaceString200Len出生地必填

domicileString250Len戶籍所在地址必填

jzkkhString10Len就診卡卡號

VirCard（卡信息）

virtualCardNumString64Len虛擬電子卡號必填

empiString64Len主索引ID必填

vuidString64Len電子健康卡ID必填

orgcodeString10Len健康卡簽發(fā)機構代碼必填

orgnameString64Len健康卡簽發(fā)機構名稱必填

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

erhcEnddateDate64Len

yyyy-mm-dd

peopleinfoPeopleinfo64Len居民信息必填

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

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

ksdmString15Len

【標準科室代碼】

ksmcStringlOOLen科室名稱必填

科室類型（1掛號科室2收費必填

科室

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

KslxString2Len科室

6檢驗科室7處置治療科室8

藥房

9手術麻醉10其它科室）

SAM卡號；必填

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

寫固定值noSam

機具號，必填

如果是電子健康卡，再獲

machineCodeString64Len

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

固定值SweepBlock

健康卡芯片號必填

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

xpxlhString64Len

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

參數(shù)"vuid"）

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

operCodeStringILen

作）

操作時間必填

operTimeString20Len

(yyyy-MM-ddss)

就診類型必填

medicalTypeStringILen1住院2門診3急診4體

檢5其它

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

AmountString20Len刷卡金額必填

支付方式（0無支付1銀行卡支付必填

PayModeStringILen2院內預繳金支付3現(xiàn)金支付

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

發(fā)卡機構代碼（需從健康卡必填

orgCodeString20Len

上讀?。?/p>

BankCodeString20Len發(fā)卡銀行機構代碼必填

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

yycsdmString6Len

康卡上讀?。?/p>

useOrgCodeString20Len刷卡機構代碼必填

useOrgNameString20Len刷卡機構名稱必填

useCityCodeString6Len刷卡應用城市代碼必填

khString32Len卡號必填

xmString16Len姓名必填

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

medStepcodeString4Len

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

用卡信息UseCardlnfo

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

medTypeString2Len

診4體檢5其它）

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

刷卡科室代碼（見字典標注科必填

depCodeString4Len

室代碼）

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

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

payAmountString16Len

010105收費的情況下，必填）

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

payChannelString16Len010105收費的情況下，必填）

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

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

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

issuingModeString2Len構自助機7微信公眾號8

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

小程序11支付寶生活號

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

terminalTypeString2Len

端99其他）

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

machineCodeString64Len

注冊接口返回）

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

khStringl-64Len子卡卡號必填

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

字典

fkorgcodeStringl-22Len子卡發(fā)卡機構代必填

碼

fkorgnameString32Len子卡發(fā)卡機構名必填

稱

yycsdmString32Len應用城市代碼必填

applytimeString7Len操作時間必填

YYYYMMDD

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

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

作（正常，掛失，

注銷）

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

綁3解綁）

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

sfzhmString18Len身份證號碼當vuid為空必填

vuidString64Len電子健康卡id當sfzhm,xm,zjhm,

zjlx為空時必填

xmStringlOLen姓名當vuid為空必填

ZjhmString18Len證件號碼當vuid為空必填

ZjlxString2Len證件類型當vuid為空必填

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

terminalPurposeString50Len終端的用途必填

terminalNameString30Len終端名稱必填

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

口2自助終端99

其他）

serialNumberStr