DB14-T 3323-2025 政務(wù)數(shù)據(jù)共享交換平臺 服務(wù)接口管理規(guī)范

ICS35.240.01CCSL6714IDB14/T3323—2025前言 12規(guī)范性引用文件 13術(shù)語和定義 14縮略語 25基本要求 26接口設(shè)計 27接口開發(fā) 38接口文檔 39注冊與發(fā)布 410變更與撤銷 511申請與使用 512接口安全 6附錄A（規(guī)范性）保留字清單 7附錄B（資料性）接口文檔模板 8附錄C（資料性）接口申請表模版 10DB14/T3323—2025本文件按照GB/T1.1—2020《標準化工作導(dǎo)則第1部分：標準化文件的結(jié)構(gòu)和起草規(guī)則》的規(guī)定起草。本文件由山西省政務(wù)信息管理局提出并組織實施。本文件由山西省電子政務(wù)信息標準化技術(shù)委員會(SXS/TC17)歸口。本文件起草單位：山西省數(shù)字政府服務(wù)中心、中國標準化研究院。本文件主要起草人：楊俊芳、張國業(yè)、張欣亮、胡興才、王春艷、張雪飛、李斌鑫、張娜、鄭鷹、李慧卓、李美悅。DB4/T3323—20251政務(wù)數(shù)據(jù)共享交換平臺服務(wù)接口管理規(guī)范本文件規(guī)定了政務(wù)數(shù)據(jù)共享交換平臺用于服務(wù)接口管理的術(shù)語和定義、縮略語、基本要求、接口設(shè)計、接口開發(fā)、接口文檔、注冊與發(fā)布、變更與撤銷、申請與使用、接口安全。本文件適用于省級政務(wù)數(shù)據(jù)共享交換平臺服務(wù)接口的管理工作。市縣級政務(wù)數(shù)據(jù)共享交換平臺服務(wù)接口的管理工作可參照執(zhí)行。2規(guī)范性引用文件下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中，注日期的引用文件，僅該日期對應(yīng)的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適用于本文件。GB/T38664.1—2020信息技術(shù)大數(shù)據(jù)政務(wù)數(shù)據(jù)開放共享第1部分：總則GB/T39477—2020信息安全技術(shù)政務(wù)信息共享數(shù)據(jù)安全技術(shù)要求GB/T42877—2023氣象數(shù)據(jù)服務(wù)接口規(guī)范3術(shù)語和定義GB/T38664.1—2020、GB/T39477—2020、GB/T42877—2023界定的以及下列術(shù)語和定義適用于本文件。3.1政務(wù)數(shù)據(jù)共享交換平臺（以下簡稱共享交換平臺）由各級人民政府確定的面向各級政務(wù)部門，維護政務(wù)數(shù)據(jù)資源目錄，匯聚基礎(chǔ)數(shù)據(jù)資源、管理共享交換需求，提供數(shù)據(jù)安全與運行監(jiān)控保障，支撐跨部門、跨地區(qū)開展政務(wù)數(shù)據(jù)共享交換的關(guān)鍵信息基礎(chǔ)設(shè)施。[來源：GB/T38664.1—2020，3.5，有修改]3.2服務(wù)接口（以下簡稱接口）在政務(wù)數(shù)據(jù)共享過程中，為提供特定業(yè)務(wù)服務(wù)功能而發(fā)布的可供其他系統(tǒng)調(diào)用的應(yīng)用編程函數(shù)。[來源：GB/T42877—2023，3.2，有修改]3.3接口提供方通過政務(wù)數(shù)據(jù)共享交換平臺，為其他部門提供政務(wù)數(shù)據(jù)共享服務(wù)接口并且是責(zé)任主體的政務(wù)部門或組織機構(gòu)。[來源：GB/T39477—2020，3.3，有修改]3.4接口使用方DB14/T3323—20252根據(jù)履行職責(zé)需要，通過政務(wù)數(shù)據(jù)共享交換平臺，使用其他部門提供的政務(wù)數(shù)據(jù)共享服務(wù)接口的政務(wù)部門或組織機構(gòu)。[來源：GB/T39477—2020，3.5，有修改]3.5接口授權(quán)碼接口使用方的使用申請通過審核后，政務(wù)數(shù)據(jù)共享交換平臺為接口使用方生成調(diào)用該接口的唯一驗證和授權(quán)訪問的編碼。4縮略語下列縮略語適用于本文件。HTTP：超文本傳輸協(xié)議（HyperTextTransferProtocol）SOAP：簡單對象訪問協(xié)議（SimpleObjectAccessProtocol）OAuth：開放的授權(quán)協(xié)議（OpenAuthorization）JWT：基于JSON格式的輕量級、自包含的身份驗證和授權(quán)機制（JSONWebToken）5基本要求5.1接口設(shè)計與開發(fā)應(yīng)命名清晰、明確，路徑規(guī)整，請求方式規(guī)范，有版本控制，高效、安全、穩(wěn)定且易于維護。5.2接口只支持HTTP和SOAP協(xié)議類型。5.3接口文檔應(yīng)內(nèi)容明確、結(jié)構(gòu)清晰、易于閱讀和理解。5.4接口文檔中不能暴露原始接口地址、認證信息等。5.5接口注冊與發(fā)布、撤銷與變更、申請與使用應(yīng)符合本級共享交換平臺管理要求。6接口設(shè)計6.1安全性接口應(yīng)采用安全的技術(shù)和協(xié)議并建立身份驗證和權(quán)限管理機制。6.2時效性接口應(yīng)提供當(dāng)前最新的政務(wù)數(shù)據(jù)。6.3準確性接口數(shù)據(jù)應(yīng)準確，不存在錯誤、遺漏或誤導(dǎo)性信息。6.4完整性接口應(yīng)提供完整的數(shù)據(jù)集，包括所有必要信息和關(guān)聯(lián)數(shù)據(jù)。6.5穩(wěn)定性接口應(yīng)具備良好的容錯和恢復(fù)能力，能夠持續(xù)穩(wěn)定地提供服務(wù)。6.6開放性DB14/T3323—20253應(yīng)采用通用、主流的接口設(shè)計方法及協(xié)議。6.7松耦合接口應(yīng)與接口提供方的業(yè)務(wù)系統(tǒng)解耦。6.8高內(nèi)聚包括以下要求：——功能明確。接口應(yīng)只負責(zé)一個明確的功能或一組緊密相關(guān)的功能，避免將多個不相關(guān)的功能混合在一個接口中；——粒度適中。接口應(yīng)既不過于龐大導(dǎo)致功能復(fù)雜，也不過于細碎導(dǎo)致調(diào)用繁瑣；——減少內(nèi)部依賴。接口內(nèi)部應(yīng)減少對其他模塊的依賴，降低模塊間的耦合度，提高接口的獨立性和可重用性。6.9可擴展性接口應(yīng)能夠滿足接口使用方對接口響應(yīng)時間、并發(fā)數(shù)等技術(shù)要求。6.10易用性接口應(yīng)有錯誤提示和日志記錄功能，文檔應(yīng)清晰、簡潔。7接口開發(fā)7.1版本控制接口開發(fā)時應(yīng)做好版本控制，版本升級時應(yīng)不影響已發(fā)布版本的使用。7.2接口地址接口只能用唯一服務(wù)路徑作為接口地址，不能多個接口共用一個服務(wù)路徑。7.3接口分類接口按功能可分為查詢、驗證、數(shù)據(jù)傳輸、下載和其他5種類型。7.4接口參數(shù)接口請求頭中的參數(shù)不應(yīng)與各級平臺的保留字沖突，保留字清單見附錄A。7.5返回數(shù)據(jù)接口返回數(shù)據(jù)的格式應(yīng)規(guī)范、清晰易懂，應(yīng)包括結(jié)果狀態(tài)碼及相應(yīng)的提示信息。7.6狀態(tài)碼接口提供方應(yīng)將服務(wù)響應(yīng)狀態(tài)碼的含義在接口文檔中進行詳細說明。8接口文檔8.1概述DB14/T3323—20254共享交換平臺應(yīng)該制定統(tǒng)一的接口文檔模版，接口文檔模板見附錄B。8.2接口名稱應(yīng)清晰、簡潔地命名且名稱與接口功能和用途相關(guān)。8.3接口版本應(yīng)明確標記接口的版本信息，并記錄接口的更新歷史，包括更新日期、更新內(nèi)容等。8.4接口描述應(yīng)清晰、簡潔地描述接口功能及用途。8.5接口認證應(yīng)對需要認證的接口明確說明支持的認證方法并提供示例展示。8.6請求方法應(yīng)標明接口支持的HTTP請求方法。8.7請求參數(shù)應(yīng)詳細列出所有請求參數(shù)，包括字段名、類型、是否必填、長度、描述等信息，對于結(jié)構(gòu)復(fù)雜的請求參數(shù)，應(yīng)提供示例數(shù)據(jù)。8.8返回參數(shù)應(yīng)列出返回值的數(shù)據(jù)類型、格式、示例數(shù)據(jù)和可能返回的錯誤碼及其含義。8.9使用示例應(yīng)提供使用接口的請求示例和響應(yīng)示例。8.10申請材料應(yīng)明確接口申請時需要補充提交的材料，有格式要求的應(yīng)提供模版。8.11數(shù)據(jù)字典應(yīng)在數(shù)據(jù)字典中對請求或返回參數(shù)中數(shù)據(jù)類型為布爾、枚舉等類型的數(shù)據(jù)元素進行詳細描述和定義。9注冊與發(fā)布9.1注冊a)應(yīng)采用中文接口名稱，準確描述接口能夠提供的業(yè)務(wù)、能力及分類等信息；b)應(yīng)準確描述接口其他信息，包括請求方法、請求參數(shù)、返回參數(shù)、接口描述、每天最大調(diào)用次數(shù)、超時設(shè)置、技術(shù)支持信息等。9.2發(fā)布DB14/T3323—20255接口注冊完成后，應(yīng)由接口提供方、共享交換平臺管理方進行審核，通過后發(fā)布到共享交換平臺。審核內(nèi)容包括但不限于接口描述、接口名稱、接口方式、接口地址、授權(quán)方式、入?yún)⒊鰠?、調(diào)用示例等。10變更與撤銷10.1變更10.1.1變更有申請記錄接口a)接口提供方應(yīng)先行評估變更影響，優(yōu)先保障已對接接口業(yè)務(wù)的正常使用；b)接口提供方應(yīng)向共享交換平臺管理方發(fā)起變更申請，說明變更事由、變更影響、變更內(nèi)容、變更計劃等信息，變更計劃制定時需征詢接口使用方的意見，接口使用方需要進行同步變更的，需預(yù)留一定的調(diào)整時間；c)共享交換平臺管理方應(yīng)對變更事由、變更影響、變更內(nèi)容、變更計劃等信息進行審核，通過后完成接口變更；d)變更執(zhí)行應(yīng)選擇非工作時間進行，接口提供方應(yīng)做好版本控制、聯(lián)調(diào)測試工作，測試失敗時應(yīng)及時回滾。10.1.2變更無申請記錄接口a)接口提供方應(yīng)向共享交換平臺管理方發(fā)起變更申請，說明變更事由、變更內(nèi)容、變更計劃等信息；b)共享交換平臺管理方進行變更審核，通過后完成接口變更。10.2撤銷10.2.1撤銷有申請記錄接口a)接口提供方應(yīng)先行評估撤銷的影響，優(yōu)先保障已對接接口業(yè)務(wù)的正常使用，有影響時需延遲撤銷操作或者提供替代方案；b)接口提供方應(yīng)向共享交換平臺管理方發(fā)起撤銷申請，說明撤銷事由、撤銷影響、撤銷計劃等信息。撤銷計劃制定時需征詢接口使用方的意見，給接口使用方預(yù)留一定的業(yè)務(wù)調(diào)整時間；c)共享交換平臺管理方應(yīng)對撤銷事由、撤銷影響、撤銷計劃等信息進行審核，通過后由共享交換平臺向接口使用方發(fā)出撤銷通知；d)撤銷應(yīng)按撤銷計劃執(zhí)行。10.2.2撤銷無申請記錄接口a)接口提供方向共享交換平臺發(fā)起撤銷申請，說明撤銷的原因，計劃撤銷時間等；b)共享交換平臺管理方應(yīng)對撤銷申請進行審核，通過后按計劃撤銷接口。11申請與使用11.1申請a)接口使用方應(yīng)按共享交換平臺及接口提供方的要求，提交接口申請表和補充資料，接口申請表模板見附錄C；b)申請?zhí)峤缓笥筛骷壒蚕斫粨Q平臺及接口提供方進行審核；DB14/T3323—20256c)審核通過后，由共享交換平臺為接口使用方提供接口授權(quán)碼、接口地址及接口文檔等相關(guān)信11.2使用a)接口用于互聯(lián)網(wǎng)或跨網(wǎng)使用時，聯(lián)接方式及安全策略應(yīng)符合有關(guān)要求；b)接口使用方應(yīng)按照平臺提供的接口文檔要求，在授權(quán)的業(yè)務(wù)范圍內(nèi)使用接口。12接口安全12.1共享交換平臺a)應(yīng)做好接口發(fā)布、申請、審核的管理工作；b)應(yīng)建設(shè)授權(quán)、認證等安全保護能力；c)應(yīng)對接口調(diào)用情況進行日志記錄。12.2接口提供方a)接口發(fā)布前應(yīng)對接口數(shù)據(jù)進行數(shù)據(jù)安全檢查與評估，識別數(shù)據(jù)安全風(fēng)險，存在風(fēng)險的應(yīng)采取措施消除風(fēng)險；b)接口發(fā)布前應(yīng)確保接口不存在安全漏洞；c)接口發(fā)布后應(yīng)定期對接口等進行安全性檢查，及時修復(fù)存在的安全漏洞；d)應(yīng)對接口調(diào)用情況進行日志記錄。12.3接口使用方a)應(yīng)妥善保管接口授權(quán)信息，不得向第三方泄露，不得將接口用于非授權(quán)用途；b)應(yīng)定期對使用接口的應(yīng)用系統(tǒng)進行安全檢查，及時修復(fù)存在的安全漏洞；c)應(yīng)按共享交換平臺的要求進行接口調(diào)用，不能進行惡意請求或濫用接口；d)應(yīng)根據(jù)數(shù)據(jù)的敏感程度結(jié)合應(yīng)用場景使用合適的技術(shù)手段對接口返回的敏感數(shù)據(jù)進行保護；e)應(yīng)對使用接口的用戶進行身份驗證和授權(quán)管理并記錄操作日志。DB14/T3323—20257（規(guī)范性）保留字清單保留字應(yīng)符合表A.1的要求。表A.1保留字清單序號保留字說明備注1sxspt_rid請求者標識省政務(wù)數(shù)據(jù)共享交換平臺2sxspt_sid要調(diào)用的服務(wù)編碼3sxspt_rtime請求的時間戳4sxspt_sign發(fā)送方簽名5client_id請求者標識太原市政務(wù)數(shù)據(jù)共享交換平臺6client_secret請求者密鑰7access_token請求授權(quán)碼8appCode請求者標識大同市政務(wù)數(shù)據(jù)共享交換平臺9apiToken請求者授權(quán)碼appkey請求者標識朔州、忻州、陽泉、晉中、呂梁、長治、運城市政務(wù)數(shù)據(jù)共享交換平臺X-Client-Id請求者標識省級數(shù)據(jù)直達系統(tǒng)X-Timestamp時間戳X-Nonce隨機字符串X-Signature數(shù)字簽名DB14/T3323—20258接口文檔模版B.1接口名稱清晰、簡潔地命名接口，使其與接口功能和用途相關(guān)。如“企業(yè)基本信息批量獲取接口”。B.2接口版本明確標記接口的版本信息。B.3接口描述清晰、簡潔描述接口功能及用途。B.4接口認證對于訪問時需要認證的接口，需要列明認證方法，如OAuth2.0、JWT、基本認證等。并提供示例展示如何在請求中包含必要的認證信息，以及如何處理響應(yīng)中的認證結(jié)果。B.5請求方法標明接口支持的HTTP請求方法，如GET、POST等,SOAP協(xié)議不需要填寫。B.6請求參數(shù)請求參數(shù)填入表B.1。表B.1請求參數(shù)1Y2N3B.7返回參數(shù)返回參數(shù)填入表B.2。表B.2返回參數(shù)123456DB14/T3323—20259B.8使用示例B.8.1請求示例提供詳細的接口請求示例。B.8.2響應(yīng)示例提供詳細的接口響應(yīng)示例，相關(guān)狀態(tài)見表B.3狀態(tài)碼。表B.3狀態(tài)碼123B.9申請材料明確接口申請時需要補充提交的材料，有格式要求的應(yīng)提供模版。B.10數(shù)據(jù)字典數(shù)據(jù)字典填入表B.4。表B.4數(shù)據(jù)字典123DB14/T3323—2025（資料性）接口申請表模版接口申請表模板見表C.1。表C.1接口申請表模版服務(wù)接口提供單位服務(wù)接口使用單位使用單位社會統(tǒng)一填寫數(shù)據(jù)使用單位社會統(tǒng)一信用代碼填寫數(shù)據(jù)使用單位數(shù)據(jù)使用部門負