DB4101-T 105-2024 政務(wù)數(shù)據(jù)市場化運(yùn)營服務(wù)接口規(guī)范

ICS35.240.01CCSL674101IDB4101/T105—2024 2規(guī)范性引用文件 3術(shù)語和定義 4縮略語 5基本原則 6接口組成 7接口描述 7.1數(shù)據(jù)協(xié)議 7.2接口名稱 7.3版本號 7.4接口訪問地址 7.5功能描述 8請求參數(shù) 8.1消息頭 8.2請求數(shù)據(jù)體 8.3公共參數(shù) 9響應(yīng)參數(shù) 9.1響應(yīng)碼 9.2響應(yīng)數(shù)據(jù) 9.3響應(yīng)數(shù)據(jù)簽名 10接口管理 10.1接口注冊 10.2接口變更 10.3接口交付 10.4接口調(diào)用 10.5接口下線 11安全保障要求 11.1基本要求 11.2運(yùn)行監(jiān)測 11.3管理制度 附錄A（資料性）接口信息表 A.1概述 附錄B（資料性）響應(yīng)碼示例 B.1公共響應(yīng)碼 DB4101/T105—2024B.2業(yè)務(wù)響應(yīng)碼 附錄C（資料性）接口注冊備案表 C.1接口注冊備案表 附錄D（資料性）接口使用備案表 D.1接口使用信息表 附錄E（資料性）接口下線備案表 E.1接口下線備案表 DB4101/T105—2024本文件按照GB/T1.1—2020《標(biāo)準(zhǔn)化工作導(dǎo)則第1部分：標(biāo)準(zhǔn)化文件的結(jié)構(gòu)和起草規(guī)則》的規(guī)定起草。請注意本文件的某些內(nèi)容可能涉及專利。本文件的發(fā)布機(jī)構(gòu)不承擔(dān)識別專利的責(zé)任。本文件由中共鄭州市委智慧城市運(yùn)行辦公室提出。本文件由鄭州市大數(shù)據(jù)標(biāo)準(zhǔn)化技術(shù)委員會(huì)（ZZTC12）歸口。本文件起草單位：鄭州大數(shù)據(jù)發(fā)展有限公司、鄭州市大數(shù)據(jù)中心。本文件主要起草人：尹旭、樊帆、魏紅格、蘇文杰、孟旭、李鑫均、楊耀環(huán)、徐曉強(qiáng)、常蔓文、張艷榮、劉文星、周昂達(dá)、楊澤堯、劉玉婷、張研碩。1DB4101/T105—2024政務(wù)數(shù)據(jù)市場化運(yùn)營服務(wù)接口規(guī)范本文件規(guī)定了政務(wù)數(shù)據(jù)市場化運(yùn)營服務(wù)接口的基本原則、接口組成、接口描述、請求參數(shù)、響應(yīng)參數(shù)、接口管理和安全保障等要求。本文件適用于政務(wù)數(shù)據(jù)市場化運(yùn)營服務(wù)。2規(guī)范性引用文件下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中，注日期的引用文件，僅該日期對應(yīng)的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適用于本文件。GB/T38664.2信息技術(shù)大數(shù)據(jù)政務(wù)數(shù)據(jù)開發(fā)共享第2部分：基本要求GB/T41479信息安全技術(shù)網(wǎng)絡(luò)數(shù)據(jù)處理安全要求3術(shù)語和定義下列術(shù)語和定義適用于本文件。3.1政務(wù)數(shù)據(jù)各級政務(wù)部門以及其技術(shù)支撐單位在履行職責(zé)過程中依法采集、生成、存儲(chǔ)、管理的各類數(shù)據(jù)資源。[來源：GB/T38664.1—2020,3.1]3.2[服務(wù)]接口信息系統(tǒng)為開發(fā)特定業(yè)務(wù)功能而發(fā)布的可供其他系統(tǒng)調(diào)用的應(yīng)用編程函數(shù)。[來源：GB/T42877—2023,3.2]4縮略語下列縮略語適用于本文件。URL：統(tǒng)一資源定位符（UniformResourceLocator）API：應(yīng)用程序編程接口（ApplicationProgrammingInterface）HTTPS：超文本傳輸安全協(xié)議（HypertextTransferProtocolSecure）IP：互聯(lián)網(wǎng)協(xié)議地址（InternetProtocolAddress）JSON：一種簡單的數(shù)據(jù)交換格式（JavaScriptObjectNotation）SSL：安全套接層協(xié)議（SecureSocketsLayer）TLS：安全傳輸層協(xié)議（TransportLayerSecurity）5基本原則2DB4101/T105—2024服務(wù)接口應(yīng)遵循以下基本原則：a)完整性：應(yīng)完整反映服務(wù)接口功能，提供完整的輸入、輸出和使用要求等，確保接口調(diào)用方能夠通過接口完成所需的任務(wù)；b)簡潔性：服務(wù)接口的參數(shù)命名、順序、格式說明等應(yīng)盡量簡潔、清晰明了，方便接口調(diào)用方理解和使用；c)擴(kuò)展性：應(yīng)考慮擴(kuò)展和變化，對擴(kuò)展開放，對修改封閉，以降低接口的復(fù)雜性和提高服務(wù)接口的可維護(hù)性；d)開放性：應(yīng)采用通用的設(shè)計(jì)標(biāo)準(zhǔn)，確保與其他系統(tǒng)的互聯(lián)互通；e)安全性：應(yīng)提供多種安全可靠的技術(shù)手段，保證服務(wù)接口及政務(wù)數(shù)據(jù)的安全。6接口組成服務(wù)接口應(yīng)至少包含接口描述、請求參數(shù)和響應(yīng)參數(shù)，具體內(nèi)容如下：a)接口描述：表達(dá)數(shù)據(jù)訪問的基本信息,包含數(shù)據(jù)協(xié)議、接口名稱、版本號、接口訪問地址及功能描述等基本信息,接口示例見附錄A；b)請求參數(shù)：表達(dá)數(shù)據(jù)訪問的輸入條件，包含消息頭和請求數(shù)據(jù)體；c)響應(yīng)參數(shù)：表達(dá)數(shù)據(jù)訪問的輸出結(jié)果，包含響應(yīng)碼、響應(yīng)數(shù)據(jù)和響應(yīng)數(shù)據(jù)簽名。7接口描述7.1數(shù)據(jù)協(xié)議應(yīng)采用HTTPS協(xié)議中的POST方式進(jìn)行數(shù)據(jù)交互，使用通用的字符集編碼，返回結(jié)果采用JSON格式。7.2接口名稱接口名稱用于標(biāo)識和區(qū)分不同的接口，通常包括接口的中文名稱和英文名稱。接口名稱應(yīng)包含業(yè)務(wù)領(lǐng)域、信息項(xiàng)、接口功能和參數(shù)條件等組成部分。其中，信息項(xiàng)和接口功能不應(yīng)為空，業(yè)務(wù)領(lǐng)域和參數(shù)條件可為空，接口中文名稱中各組成部分應(yīng)以中文橫杠“-”連接，接口英文名稱中組成部分包含多個(gè)參數(shù)條件應(yīng)以英文“AND”連接。業(yè)務(wù)領(lǐng)域：接口數(shù)據(jù)所屬行業(yè)或領(lǐng)域，如不動(dòng)產(chǎn)、公積金等。信息項(xiàng)：接口數(shù)據(jù)所表示的具體業(yè)務(wù)信息，如產(chǎn)權(quán)登記、抵押登記等。接口功能：接口提供數(shù)據(jù)結(jié)果的方法，見表1示例。參數(shù)條件：接口提供數(shù)據(jù)結(jié)果的條件，如身份證號碼、企業(yè)統(tǒng)一社會(huì)信用代碼等。表1接口功能示例12347.3版本號3DB4101/T105—2024版本號是接口的版本識別符，由數(shù)字和英文句號組成，版本號從左至右分為一級、二級、三級，默認(rèn)為1.0.0，采用多版本并存，增量發(fā)布的方式,大功能發(fā)布使用V1.0.0、V2.0.0形式，小版本發(fā)布使用V1.1.0、V1.2.0組成，其中小版本變化向下兼容。a)一級版本號：服務(wù)接口發(fā)生不兼容現(xiàn)版本的重大變更（包括但不限于發(fā)生影響結(jié)果的業(yè)務(wù)邏輯變更、增加或減少必填入?yún)?、減少非必填入?yún)⒒虺鰠ⅲr(shí)，版本號數(shù)字加1；b)二級版本號：服務(wù)接口發(fā)生兼容現(xiàn)版本的變更，同時(shí)標(biāo)識服務(wù)接口存在變更（包括但不限于增加非必填入?yún)?、增加出參）時(shí)，版本號數(shù)字加1；c)三級版本號：默認(rèn)為0，僅當(dāng)發(fā)生不涉及任何影響外部接口、操作使用和業(yè)務(wù)邏輯理解方面的版本發(fā)布時(shí)使用，一般是內(nèi)部安全性和可靠性提升時(shí)，版本號數(shù)字加1。7.4接口訪問地址應(yīng)統(tǒng)一格式的URL，格式為：https://{接口域名}/{版本號}/{接口英文名稱}，其中接口域名應(yīng)部署在專用域名下。7.5功能描述應(yīng)提供功能說明、示例說明，以便接口調(diào)用方快速理解接口功能和使用。8請求參數(shù)8.1消息頭消息頭應(yīng)攜帶接口憑證，用于減少用戶名和密碼的傳輸次數(shù)。8.2請求數(shù)據(jù)體請求數(shù)據(jù)體應(yīng)包含公共參數(shù)、業(yè)務(wù)參數(shù)、參數(shù)簽名。8.3公共參數(shù)公共參數(shù)應(yīng)包含接口調(diào)用方唯一標(biāo)識、時(shí)間戳和請求流水號等信息，其中時(shí)間戳格式應(yīng)為YYYYMMDDHHmmssSSS，其中，YYYY表示年（4位MM表示月（2位DD表示日（2位HH表示小時(shí)（2位，24小時(shí)制），mm表示分鐘（2位），ss表示秒（2位）,SSS表示毫秒（3位），如無特殊說明，時(shí)間應(yīng)為北京時(shí)間（UTC+8）。8.3.1業(yè)務(wù)參數(shù)應(yīng)使用安全自主可控的密碼算法對業(yè)務(wù)參數(shù)進(jìn)行加密運(yùn)算。8.3.2參數(shù)簽名應(yīng)使用安全自主可控的密碼算法對請求數(shù)據(jù)報(bào)文進(jìn)行簽名，保證數(shù)據(jù)的完整性和安全性。9響應(yīng)參數(shù)9.1響應(yīng)碼響應(yīng)碼分為公共響應(yīng)碼和業(yè)務(wù)響應(yīng)碼，應(yīng)使用英文組合字符串，成功狀態(tài)應(yīng)使用固定字符（如“success”或“ok”），示例見附錄B。4DB4101/T105—2024公共響應(yīng)碼非成功狀態(tài)格式應(yīng)為：{服務(wù)代碼}.{錯(cuò)誤原因英文組合}。其中服務(wù)代碼示例見表2。業(yè)務(wù)響應(yīng)碼非成功狀態(tài)格式應(yīng)為：{業(yè)務(wù)信息項(xiàng)}.{接口功能}.{錯(cuò)誤原因英文組合}。表2服務(wù)代碼示例123459.2響應(yīng)數(shù)據(jù)應(yīng)使用安全自主可控的密碼算法對響應(yīng)數(shù)據(jù)進(jìn)行加密運(yùn)算。9.3響應(yīng)數(shù)據(jù)簽名應(yīng)使用安全自主可控的密碼算法對響應(yīng)數(shù)據(jù)報(bào)文進(jìn)行簽名，保證數(shù)據(jù)的完整性和安全性。10接口管理10.1接口注冊接口注冊應(yīng)滿足以下要求：a)應(yīng)提供測試樣例，確保接口調(diào)用方能夠?qū)涌谶M(jìn)行測試；b)應(yīng)完整填寫接口注冊信息，經(jīng)審核后發(fā)布，接口注冊備案表模板見附錄C。10.2接口變更接口變更應(yīng)滿足以下要求：a)已發(fā)布的接口發(fā)生變更時(shí)，應(yīng)確保接口調(diào)用方不受影響；b)已發(fā)布并被正常調(diào)用的接口發(fā)生變更時(shí)，應(yīng)提前通知接口調(diào)用方在一定期限內(nèi)更新接口；c)應(yīng)建立版本控制機(jī)制，生產(chǎn)環(huán)境中應(yīng)最多保留3個(gè)詳細(xì)的版本；d)應(yīng)建立備案機(jī)制，備案內(nèi)容包括但不限于接口更新內(nèi)容、計(jì)劃停更時(shí)間、應(yīng)急預(yù)案等。10.3接口交付接口交付應(yīng)滿足以下要求：a)應(yīng)提供審計(jì)功能，記錄調(diào)用時(shí)間、接口提供方、調(diào)用方、調(diào)用情況等信息，不宜記錄賬號、密碼等敏感信息；b)應(yīng)對接口的連通有效性進(jìn)行驗(yàn)證，如接口版本、參數(shù)格式等要素是否與注冊信息保持一致；c)應(yīng)按照最小授權(quán)原則，對其相應(yīng)接口權(quán)限進(jìn)行授權(quán)管理，當(dāng)接口需求變更時(shí)，需及時(shí)評估和調(diào)整接口權(quán)限；d)應(yīng)對API的調(diào)用有效期進(jìn)行控制（如單次有效、階段性有效、協(xié)議期限內(nèi)有效）。10.4接口調(diào)用接口調(diào)用應(yīng)滿足以下要求：5DB4101/T105—2024a)應(yīng)建立接口使用備案審核機(jī)制，審核通過后為接口調(diào)用方提供唯一標(biāo)識、密鑰等憑證信息；b)應(yīng)合法合規(guī)使用接口，明確接口具體的使用單位、使用場景、數(shù)據(jù)安全措施等，接口使用備案表模板見附錄D；c)應(yīng)首先取得信息主體授權(quán)后使用接口，其內(nèi)容應(yīng)包含授權(quán)有效期；d)應(yīng)遵循保密規(guī)定，未經(jīng)允許，不應(yīng)泄露給第三方；e)若發(fā)現(xiàn)接口存在安全缺陷，應(yīng)采取補(bǔ)救措施并及時(shí)通知接口管理方。未經(jīng)許可，不得將缺陷細(xì)節(jié)透露給任何其他第三方；f)應(yīng)妥善使用和保管相關(guān)密鑰等憑證，對于密鑰存儲(chǔ)應(yīng)采取加密等方式進(jìn)行安全防護(hù)，防范密鑰丟失或泄露。10.5接口下線接口下線應(yīng)滿足以下要求：a)已發(fā)布并被正常調(diào)用的接口下線時(shí)，應(yīng)提前通知接口調(diào)用方；b)應(yīng)建立備案審核機(jī)制，備案內(nèi)容包括但不限于接口下線原因、計(jì)劃下線時(shí)間等，接口下線備案表模板見附錄E；c)應(yīng)在相關(guān)服務(wù)確認(rèn)終止之后執(zhí)行，在下線之前應(yīng)設(shè)置擋板（如服務(wù)接口終止提示信息），明示服務(wù)接口已終止；d)應(yīng)將有關(guān)數(shù)據(jù)進(jìn)行歸檔處理，數(shù)據(jù)保留期限應(yīng)按照國家與行業(yè)主管部門相關(guān)規(guī)定與規(guī)則執(zhí)行；e)應(yīng)對接口認(rèn)證信息（如接口調(diào)用方唯一標(biāo)識、密鑰等）進(jìn)行作廢處理，歸檔并保存待查。11安全保障要求11.1基本要求應(yīng)遵循GB/T41479要求，保證政務(wù)數(shù)據(jù)及服務(wù)接口安全，滿足以下基本要求：a)應(yīng)進(jìn)行分類管理，劃分相應(yīng)的安全級別，定期評估，動(dòng)態(tài)調(diào)整，實(shí)施不同級別安全保護(hù)，同時(shí)對接入風(fēng)險(xiǎn)進(jìn)行評估，并報(bào)送主管部門進(jìn)行備案；b)應(yīng)設(shè)計(jì)不同級別的用戶身份認(rèn)證機(jī)制；c)應(yīng)對接口交互的數(shù)據(jù)進(jìn)行完整性保護(hù)，保證數(shù)據(jù)傳輸?shù)耐暾?，宜使用?shù)字簽名技術(shù)；d)應(yīng)采用SSL/TLS等安全通道連接進(jìn)行通信，交互流程結(jié)束后及時(shí)清除相關(guān)信息，防范攻擊者通過讀取臨時(shí)文件、內(nèi)存數(shù)據(jù)等方式獲得全部或部分信息。11.2運(yùn)行監(jiān)測應(yīng)對接口運(yùn)行狀態(tài)進(jìn)行監(jiān)測，發(fā)現(xiàn)異常應(yīng)及時(shí)處理，具體要求如下：a)應(yīng)監(jiān)測接口狀態(tài)（包括耗時(shí)、調(diào)用量、成功率等參數(shù)），并建立告警機(jī)制和接口可用性主動(dòng)監(jiān)測機(jī)制，保障服務(wù)接口的可用性；b)應(yīng)具備接口調(diào)用流量控制能力，控制規(guī)則包括最大允許接口調(diào)用并發(fā)數(shù)、單位時(shí)間最大調(diào)用量等，控制措施包括告警、暫停、拒絕等；c)應(yīng)建立未授權(quán)和冒用接口的監(jiān)測機(jī)制，發(fā)現(xiàn)問題及時(shí)處理；d)應(yīng)設(shè)計(jì)熔斷機(jī)制，熔斷規(guī)則包括設(shè)置失敗次數(shù)閾值、接口調(diào)用失敗閾值等，熔斷措施包括拒絕請求、暫停服務(wù)調(diào)用等；e)應(yīng)具備接口健康主動(dòng)監(jiān)測功能，包括接口訪問地址、版本號等在線檢測和監(jiān)測。11.3管理制度6DB4101/T105—2024應(yīng)遵循GB/T38664.2基本要求，制定安全管理制度，明確安全責(zé)任，保障原始政務(wù)數(shù)據(jù)不出域，可用不可見，具體要求如下：a)應(yīng)建立覆蓋接口全生命周期的安全管理制度與控制措施，并對管理制度與控制措施的有效性進(jìn)行驗(yàn)證，保證接口效率及安全性；b)應(yīng)以合同或協(xié)議的方式，明確規(guī)定接口的數(shù)據(jù)安全與個(gè)人信息保護(hù)等方面的安全責(zé)任；c)應(yīng)具備安全審計(jì)能力，提供接口訪問、授權(quán)等歷史操作日志記錄，日志記錄至少包含來源IP、日期、時(shí)間、日志級別、代碼位置、日志內(nèi)容、響應(yīng)結(jié)果等內(nèi)容；d)應(yīng)對日志記錄進(jìn)行完整性保護(hù)，確保日志不被篡改、刪除、覆蓋，根據(jù)日志級別存儲(chǔ)到不同位置，定期備份，留存時(shí)間應(yīng)不少于六個(gè)月，對于重要日志宜采取離線存儲(chǔ)方式；e)應(yīng)設(shè)置數(shù)據(jù)安全關(guān)鍵崗位，定期開展數(shù)據(jù)安全風(fēng)險(xiǎn)自查、教育培訓(xùn)等工作。7DB4101/T105—2024（資料性）接口信息表A.1概述接口信息包含接口描述、請求參數(shù)、響應(yīng)參數(shù)等，示例見表A.1。表A.1接口信息示例表是是是是是N是N8DB4101/T105—2024（資料性）響應(yīng)碼示例B.1公共響應(yīng)碼接口公共響應(yīng)碼示例見表B.1。表B.1公共響應(yīng)碼示例auth.invalid-app-auth-tokeB.2業(yè)務(wù)響應(yīng)碼接口業(yè)務(wù)響應(yīng)碼示例見表B.2。表B.2業(yè)務(wù)響應(yīng)碼示例carBaseInfoVerify.entity-pcarBaseInfoVerify.entitycarBaseInfoVerify.ecarBaseInfoVerify.e9DB4101/T105—2024（資料性）接口注冊備案表C.1接口注冊備案