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