《廣東省冷鏈?zhǔn)称纷匪?數(shù)據(jù)共享與交換接口規(guī)范》（送審稿）

ICS35.240.99CCSL6744GuangdongcoldchainfoodtIDB44/TXXXX—XXXX前言 2規(guī)范性引用文件 3術(shù)語和定義 4縮略語 5基本要求 5.1數(shù)據(jù)安全性 5.2數(shù)據(jù)可靠性 5.3數(shù)據(jù)可拓展性 6接口協(xié)議 6.1通訊協(xié)議 26.2接口協(xié)議數(shù)據(jù)結(jié)構(gòu) 27數(shù)據(jù)共享和交換要求 37.1數(shù)據(jù)共享要求 37.2數(shù)據(jù)交換方式 37.3數(shù)據(jù)交換與內(nèi)容格式 37.4數(shù)據(jù)交換請求 37.5數(shù)據(jù)交換返回 3附錄A（資料性）數(shù)據(jù)交換共享請求JSON示例 5附錄B（資料性）數(shù)據(jù)交換成功返回JSON示例 6附錄C（資料性）數(shù)據(jù)交換失敗返回JSON示例 7參考文獻 8DB44/TXXXX—XXXX本文件按照GB/T1.1—2020《標(biāo)準(zhǔn)化工作導(dǎo)則第1部分：標(biāo)準(zhǔn)化文件的結(jié)構(gòu)和起草規(guī)則》的規(guī)定起草。請注意本文件的某些內(nèi)容可能涉及專利，本文件的發(fā)布機構(gòu)不承擔(dān)識別專利的責(zé)任。本文件由廣東省市場監(jiān)督管理局提出。本文件由廣東省市場監(jiān)督管理局歸口。本文件起草單位：廣東省市場監(jiān)督管理局、天河區(qū)市場監(jiān)督管理局、廣州執(zhí)信網(wǎng)絡(luò)技術(shù)有限公司、廣州中科易德科技有限公司、廣州軟件應(yīng)用技術(shù)研究院、珠海復(fù)旦創(chuàng)新研究院。本文件主要起草人：袁敏夫、李引、董雯雯、林淑英、廖娟、鐘百川、譚教珠、楊世峰、何川、何維、王一龍、肖景賢、劉東成、孫微微、鄭翔蔚、王俊宇、高自立、李露露。1DB44/TXXXX—XXXX廣東省冷鏈?zhǔn)称纷匪輸?shù)據(jù)共享與交換接口規(guī)范本文件規(guī)定了廣東省冷鏈?zhǔn)称纷匪葜械臄?shù)據(jù)傳輸基本要求、數(shù)據(jù)接口協(xié)議以及數(shù)據(jù)共享與交換要求。本文件適用于企業(yè)系統(tǒng)、地市監(jiān)管系統(tǒng)與廣東省冷鏈?zhǔn)称纷匪菹到y(tǒng)之間數(shù)據(jù)的對接與傳輸。2規(guī)范性引用文件下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中，注日期的引用文件，僅該日期對應(yīng)的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適用于本文件。GB/T11457信息技術(shù)軟件工程術(shù)語GB/T35295信息技術(shù)大數(shù)據(jù)術(shù)語GB/T36345信息技術(shù)通用數(shù)據(jù)導(dǎo)入接口GB/T38672信息技術(shù)大數(shù)據(jù)接口基本要求GB/T43195進口冷鏈?zhǔn)称纷匪葑匪菹到y(tǒng)開發(fā)指南3術(shù)語和定義GB/T11457、GB/T35295界定的術(shù)語和定義適用于本文件。4縮略語下列縮略語適用于本文件。JSON：JS對象標(biāo)記（JavaScriptObjectNotation）HTTPS：安全超文本傳輸協(xié)議（HyperTextTransferProtocolSecure）5基本要求5.1數(shù)據(jù)安全性數(shù)據(jù)傳輸和認(rèn)證過程中應(yīng)采用可靠加密方案，宜使用國密系列算法。5.2數(shù)據(jù)可靠性傳輸過程應(yīng)通過有效的校驗機制驗證數(shù)據(jù)包的完整性和正確性。5.3數(shù)據(jù)可拓展性接口設(shè)計應(yīng)具備靈活性，能夠適應(yīng)數(shù)據(jù)量與業(yè)務(wù)需求的增長，支持橫向擴展及兼容未來技術(shù)升級。6接口協(xié)議2DB44/TXXXX—XXXX6.1通訊協(xié)議數(shù)據(jù)通信基于TCP/IP協(xié)議和HTTPS協(xié)議，并符合GB/T36345的要求。包括以下情況：a)建立連接：采用HTTPS通信方式，進行端口監(jiān)聽，準(zhǔn)備接收連接請求，并根據(jù)業(yè)務(wù)需求進行數(shù)據(jù)傳輸，傳輸結(jié)束后斷開網(wǎng)絡(luò)；b)超時重發(fā)：一條指令發(fā)出后，在規(guī)定時間內(nèi)未收到回應(yīng)，則認(rèn)為超時；超時后應(yīng)重發(fā)，重發(fā)3次后，仍未收到回應(yīng)，則認(rèn)為通訊失敗，應(yīng)自動重建連接。超時時間可根據(jù)具體情況自行設(shè)c)通信周期：支持被動傳輸和主動定時傳輸兩種數(shù)據(jù)傳輸模式，主動定時傳輸周期可從5min到24h靈活配置。6.2接口協(xié)議數(shù)據(jù)結(jié)構(gòu)6.2.1數(shù)據(jù)包組成接口協(xié)議數(shù)據(jù)包的組成應(yīng)符合圖1的規(guī)定。其中實體數(shù)據(jù)為經(jīng)過加密的JSON格式數(shù)據(jù)，加密后以ASCII碼的格式進行傳輸，其他數(shù)據(jù)明碼傳輸。圖1數(shù)據(jù)包的組成6.2.2數(shù)據(jù)包的結(jié)構(gòu)數(shù)據(jù)包的結(jié)構(gòu)見表1。表1數(shù)據(jù)包的結(jié)構(gòu)6.2.3實體數(shù)據(jù)的結(jié)構(gòu)實體數(shù)據(jù)的結(jié)構(gòu)見表2。3DB44/TXXXX—XXXX表2實體數(shù)據(jù)的結(jié)構(gòu)標(biāo)識了發(fā)送者的數(shù)據(jù)序號，應(yīng)答時，本項內(nèi)容應(yīng)按根據(jù)數(shù)據(jù)序號，內(nèi)容不同，數(shù)據(jù)內(nèi)容是經(jīng)過加密的JSON格式數(shù)據(jù)，加密后以ASCII碼的格式進行傳7數(shù)據(jù)共享和交換要求7.1數(shù)據(jù)共享要求數(shù)據(jù)共享應(yīng)符合以下要求：a)數(shù)據(jù)共享以WEB服務(wù)方式提供，按照GB/T36345和GB/T38672的要求進行；b)數(shù)據(jù)共享服務(wù)的設(shè)計、封裝、開發(fā)按照GB/T43195的要求進行。7.2數(shù)據(jù)交換方式數(shù)據(jù)交換按照GB/T43195的要求進行，分為以下三個階段：a)數(shù)據(jù)使用方通過HTTPS向數(shù)據(jù)提供方發(fā)起數(shù)據(jù)交換請求；b)數(shù)據(jù)提供方收到數(shù)據(jù)交換請求，解析數(shù)據(jù)報文，進行校驗后對合法數(shù)據(jù)進行發(fā)送，非法數(shù)據(jù)則發(fā)送錯誤代碼；c)數(shù)據(jù)使用方接收數(shù)據(jù)并存儲，返回一個數(shù)據(jù)報文，數(shù)據(jù)提供方根據(jù)返回數(shù)據(jù)報文判斷本次數(shù)據(jù)交換是否成功。7.3數(shù)據(jù)交換與內(nèi)容格式數(shù)據(jù)交換的內(nèi)容采用JSON作為數(shù)據(jù)交換的媒介。7.4數(shù)據(jù)交換請求7.4.1數(shù)據(jù)交換請求JSON格式數(shù)據(jù)交換請求JSON格式應(yīng)包含以下參數(shù)：a)accessToken：調(diào)用接口的令牌。登陸成功后，返回一個32位的Hash字符串；b)timestamp：接口使用方發(fā)出請求的客戶端時間（采用東八區(qū)系統(tǒng)時間UTC/GMT+08:00）；c)totalNum：表示數(shù)據(jù)交換所攜帶的記錄數(shù)量；d)data：為JSON數(shù)組，存放交換數(shù)據(jù)。7.4.2數(shù)據(jù)交換請求示例可參見附錄A。7.5數(shù)據(jù)交換返回7.5.1數(shù)據(jù)交換返回JSON格式數(shù)據(jù)交換返回JSON格式包括以下信息：4DB44/TXXXX—XXXXa)errorCode：為錯誤代碼，表明數(shù)據(jù)交換失敗的原因。當(dāng)數(shù)據(jù)交換成功時，該參數(shù)為0；當(dāng)數(shù)據(jù)交換失敗時，該參數(shù)為自定義的錯誤代碼；b)errorMessage：為返回結(jié)果信息，描述數(shù)據(jù)交換出錯的具體情況。當(dāng)數(shù)據(jù)交換成功時，該參數(shù)為空值；當(dāng)數(shù)據(jù)交換失敗時，該參數(shù)為自定義的錯誤原因；c)success：標(biāo)志此次數(shù)據(jù)交換是否成功。成功為true，失敗為false；d)data：當(dāng)數(shù)據(jù)交換成功時，則data參數(shù)為空值；當(dāng)數(shù)據(jù)交換失敗時，data參數(shù)存放交換失敗的數(shù)據(jù)。7.5.2數(shù)據(jù)交換返回示例可參見附錄B和附錄C。5DB44/TXXXX—XXXX（資料性）數(shù)據(jù)交換共享請求JSON示例下面給出數(shù)據(jù)交換共享請求的JSON示列,見圖A.1。https://{SERVER_IP}accessToken=C7ABF9DAD2F94BB1907ADE0AFE3F4EC1&resourceCode=0104001&timeContent-Type:applicat"ENT_CREDIT_CODE":"5CFC5CABA549CA9DE050A8C0DD013}圖A.1數(shù)據(jù)交換請求JSON示例6DB44/TXXXX—XXXX（資料性）數(shù)據(jù)交換成功返回JSON示例下面給出數(shù)據(jù)交換成功返回JSON示例,見圖B.1。{}",,圖B.1數(shù)據(jù)交換成功返回JSON示例7DB44/TXXXX—XXXX（資料性）數(shù)據(jù)交換失敗返回JSON示例下面給出數(shù)據(jù)交換失敗返回JSON示例，見圖C.1。{"errorMessage":"JSON數(shù)據(jù)驗證}圖C.1數(shù)據(jù)交換失敗返回JSON示例8DB44/TXXXX—XXXX參考文獻[