長三角地區(qū)食品和食用農(nóng)產(chǎn)品信息追溯第3部分+數(shù)據(jù)接口

1長三角地區(qū)食品和食用農(nóng)產(chǎn)品信息追溯第3部分：數(shù)據(jù)接口本文件規(guī)定了長三角地區(qū)食品和食用農(nóng)產(chǎn)品追溯的數(shù)據(jù)共享方式、數(shù)據(jù)接口技術(shù)要求、數(shù)據(jù)結(jié)構(gòu)和接口安全要求等內(nèi)容。本文件適用于長三角地區(qū)（上海市、江蘇省、浙江省、安徽?。﹥?nèi)食品和食用農(nóng)產(chǎn)品追溯信息交換、共享、傳輸和認證的接口實現(xiàn)。2規(guī)范性引用文件下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中，注日期的引用文件，僅該日期對應(yīng)的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適用于本文件。GB/T7408-2005數(shù)據(jù)元和交換格式信息交換日期和時間表示法GB/T38155重要產(chǎn)品追溯追溯術(shù)語DB31/T310XX.1長三角地區(qū)食品和食用農(nóng)產(chǎn)品信息追溯第1部分：通則DB31/T310XX.2長三角地區(qū)食品和食用農(nóng)產(chǎn)品信息追溯第2部分：數(shù)據(jù)元IETFRFC1945超文本傳輸協(xié)議1.0(Hypertexttransferprotocol--HTTP/1.0)IETFRFC2616超文本傳輸協(xié)議1.1(Hypertexttransferprotocol--HTTP/1.1)IETFRFC2818TLS上的HTTP(HTTPoverTLS)IETFRFC3548Base16、Base32、Base64數(shù)據(jù)編碼（TheBase16,Base32,andBase64DataEncodings）IETFRFC3629UTF-8，UTF-8，ISO10646轉(zhuǎn)換格式（UTF-8,atransformationformatofISO10646）IETFRFC4627JSON格式定義(Theapplication/JSONmediatypeforjavascriptObjectnotation)3術(shù)語和定義GB/T38155、DB31/T310XX.1界定的以及下列術(shù)語和定義適用于本文件。3.1數(shù)據(jù)接口datainterface用于數(shù)據(jù)交換的服務(wù)，包括服務(wù)的功能、位置以及通訊的協(xié)議、傳輸格式和認證方法。3.2數(shù)據(jù)接口協(xié)議datainterfaceprotocol用來和數(shù)據(jù)接口服務(wù)進行通訊的應(yīng)用層協(xié)議，包括定義消息的內(nèi)容、消息類型的語法結(jié)構(gòu)、域所包含的信息的含義，確定通信程序何時發(fā)送消息和接收消息的規(guī)則。3.3接口傳輸規(guī)范interfacetransmissionstandard定義數(shù)據(jù)源和數(shù)據(jù)宿之間傳送的數(shù)據(jù)內(nèi)容的格式和標記語言。3.4安全認證securitycertificate保證數(shù)據(jù)傳輸安全的加密方法和身份認證方法。23.5數(shù)字令牌digitaltoken分發(fā)給傳輸方，代表傳輸方身份及權(quán)限的加密字符串。3.6“名稱/值”對name/valuepairJSON的數(shù)據(jù)存儲格式，“名稱/值”對組合中的名稱寫在前面雙引號中，值寫在后面雙引號中，中間用冒號隔開，“名稱/值”對之間由逗號分隔。4縮略語下列縮略語適用于本文件。CA：數(shù)字證書認證機構(gòu)（CertificateAuthority）HTTPS：安全超文本傳輸協(xié)議（HyperTextTransferProtocoloverSecureSocketLayer）JSON：一種輕量級的數(shù)據(jù)交換格式（JavaScriptObjectNotation）TLS：傳輸層安全協(xié)議（TransportLayerSecurity）URL：統(tǒng)一資源定位符（UniformResourceLocator）UTF-8：一種可變長度字符編碼（8-bitUnicodeTransformationFormat）5數(shù)據(jù)共享方式5.1長三角地區(qū)食品和食用農(nóng)產(chǎn)品信息追溯，采用各省/直轄市提供統(tǒng)一數(shù)據(jù)接口服務(wù)的共享方式，各省/直轄市按實際情況提供信息的共享接口，供其他省/直轄市的系統(tǒng)使用。5.2各省/直轄市在需要其他省/直轄市的相關(guān)信息追溯時，可以調(diào)用對應(yīng)省/直轄市的數(shù)據(jù)接口服務(wù)，獲取追溯數(shù)據(jù)，用于各自的功能需要。6數(shù)據(jù)接口技術(shù)要求6.1基本要求長三角地區(qū)食品和食用農(nóng)產(chǎn)品信息追溯數(shù)據(jù)接口通過服務(wù)調(diào)用獲取所需的信息，應(yīng)符合下列要求：a)采用符合IETFRFC2818的HTTPS協(xié)議作為底層承載協(xié)議；b)采用符合IETFRFC3629規(guī)定的UTF-8字符集；c)采用符合GB/T7408規(guī)定的日期類型；d)采用符合IETFRFC3548規(guī)定的Base64編碼規(guī)則將圖片、文件二進制字節(jié)流轉(zhuǎn)換為字符串；e)接口響應(yīng)采用RFC4627規(guī)定的JSON數(shù)據(jù)格式；f)建立接口日志記錄，能識別數(shù)據(jù)異?；蜃匪萁粨Q數(shù)據(jù)情況；g)發(fā)生錯誤時，接口將詳細的錯誤代碼和錯誤信息返回給接口使用方，以利于接口使用方進行記錄分析和整改。6.2接口格式定義數(shù)據(jù)接口格式定義主要包括：a)接口地址：請求的URL地址，一般由域名或IP、端口號、接口路徑組成，參見附錄A中A.1；b)功能說明：數(shù)據(jù)接口功能的簡要描述，參見附錄A中A.2；3追溯參與11111食品和食用農(nóng)產(chǎn)品基礎(chǔ)信食品和食用農(nóng)產(chǎn)品生產(chǎn)信追溯參與11111食品和食用農(nóng)產(chǎn)品基礎(chǔ)信食品和食用農(nóng)產(chǎn)品生產(chǎn)信c)參數(shù)說明：調(diào)用數(shù)據(jù)接口的輸入?yún)?shù)或者輸出參數(shù)情況，參見附錄A中A.3；d)請求示例：數(shù)據(jù)接口的請求參數(shù)示例，參見附錄A中A.4；e)返回示例：數(shù)據(jù)接口調(diào)用正?；虍惓５膱笪闹黧w示例，參見附錄A中A.5；f)接口響應(yīng)碼說明：數(shù)據(jù)接口的響應(yīng)狀態(tài)碼，參見附錄A中A.6。6.3數(shù)據(jù)類型數(shù)據(jù)接口應(yīng)支持的數(shù)據(jù)類型包括：a)字符型，用String表示；b)整數(shù)型，用Integer表示；c)浮點型，用Float表示；d)布爾型，用Boolean表示；e)日期時間型，用DateTime表示，應(yīng)符合GB/T7408-2005中定義的擴展時間表示法。日期格式為：YYYY-MM-DD，時區(qū)為中國北京時間(GMT+8)；時間格式為：YYYY-MM-DDThh:mm:ss，時區(qū)為中國北京時間(GMT+8)；根據(jù)信息交換中各方的約定，在不會引起日期和時間組合的日的表示法與本標準定義的其他表示法出現(xiàn)混淆的情況下，字符[T]可以省略；f)文件型，用字符串標識，應(yīng)采用data:<mediatype>；base64,<data>的字符串格式進行拼接。其中：<mediatype>表示文件的類型，例如application/pdf；<data>表示文件二進制字節(jié)流的Base64編碼字符串；g)對象型，用Object表示，對應(yīng)JSON中的“對象符號”；h)數(shù)組型，用Array表示，是一個或多個JSON對象符號的集合；i)空，用NULL表示。7數(shù)據(jù)結(jié)構(gòu)7.1追溯數(shù)據(jù)的總體數(shù)據(jù)結(jié)構(gòu)7.2應(yīng)對接口交換的長三角食品安全信息追溯平臺追溯數(shù)據(jù)的數(shù)據(jù)集進行封裝，追溯數(shù)據(jù)的數(shù)據(jù)集由多條追溯數(shù)據(jù)構(gòu)成，每一條追溯數(shù)據(jù)由追溯參與方和追溯單元構(gòu)成，總體數(shù)據(jù)結(jié)構(gòu)見圖1：食品和食用農(nóng)產(chǎn)品生產(chǎn)經(jīng)食品和食用農(nóng)產(chǎn)品流通信食品和食用農(nóng)產(chǎn)品抽檢信圖中實線表示必須包含，虛線表示可以包含。線段上的數(shù)字表示可以包含的數(shù)量，例如：1表示可以包含1條，0..∞：表示可以包含0到多條數(shù)據(jù)。4圖1總體數(shù)據(jù)結(jié)構(gòu)總體數(shù)據(jù)結(jié)構(gòu)組成元素見表1。表1總體數(shù)據(jù)結(jié)構(gòu)組成元素是是追溯數(shù)據(jù)對象，包括一組追溯參與方和一組追溯單元信息組成，并是追溯參與方信息數(shù)據(jù)包括一組食品和食用農(nóng)產(chǎn)品生產(chǎn)經(jīng)營者信息對是追溯單元數(shù)據(jù)包括一組食品和食用農(nóng)產(chǎn)品基礎(chǔ)信息（以參數(shù)名稱product標識）、一組食品和食用農(nóng)產(chǎn)品生產(chǎn)信息（以參數(shù)名稱production標識）、一組或多組食品和食用農(nóng)產(chǎn)品流通信息（以參數(shù)名稱circulation標識）、零或多組食品和食用農(nóng)產(chǎn)品抽檢信息對象（以參數(shù)名稱inspection標識），信息的內(nèi)容應(yīng)符合DB31/T是8接口安全8.1安全認證數(shù)據(jù)接口采用數(shù)字令牌簽名的方式進行安全認證。8.2數(shù)字令牌數(shù)據(jù)接口調(diào)用者需要向數(shù)據(jù)接口服務(wù)提供方申請數(shù)字令牌，數(shù)字令牌通常包含appKey和appSecret兩部份，appKey是調(diào)用者身份的標識，appSecret是調(diào)用者的密鑰，調(diào)用者使用appSecret以約定的算法對參數(shù)數(shù)據(jù)進行簽名。數(shù)據(jù)接口服務(wù)提供方可以通過驗證參數(shù)數(shù)據(jù)的簽名的方式，識別調(diào)用者的身份。8.3傳輸安全數(shù)據(jù)接口服務(wù)方提供基于CA頒發(fā)的數(shù)字證書和基于TLS之上的HTTPS協(xié)議的數(shù)據(jù)接口服務(wù)，應(yīng)符合IETFRFC2818中的規(guī)范建立連接并傳輸數(shù)據(jù)。8.4數(shù)據(jù)加密長三角地區(qū)食品和食用農(nóng)產(chǎn)品信息追溯數(shù)據(jù)宜通過約定的加密算法，對明文數(shù)據(jù)進行加密處理后，再進行數(shù)據(jù)傳輸。5（資料性）長三角食品安全信息平臺追溯數(shù)據(jù)接口JSON格式數(shù)據(jù)示例A.1接口地址接口地址由請求的URL地址，一般由域名或IP、端口號、接口路徑組成。A.2功能說明追溯信息查詢的服務(wù)接口。根據(jù)請求調(diào)用返回某個追溯碼對應(yīng)的追溯信息。A.3參數(shù)說明A.3.1提交方法(Method)：Get。A.3.2請求頭(Header)：如表A.1所示。表A.1請求頭(Header)表是是接口調(diào)用時間，采用YYYY-MM-DDThh:mm:ss的格式轉(zhuǎn)化為字符串是請求簽名，用于驗證此次請求的合法性，由調(diào)用者根據(jù)實際的輸入?yún)?shù)，并憑密鑰（appSecret）和約定的A.3.3請求參數(shù)以URL參數(shù)格式傳輸，如表A.2所示。表A.2請求參數(shù)表是否否A.3.4返回內(nèi)容類型(Content-Type)：application/json;charset=utf-8。A.3.5返回數(shù)據(jù)的參數(shù)說明，如表A.3所示。表A.3返回參數(shù)表是是否是是是6表A.3返回參數(shù)表（續(xù)）是是否否否否A.4請求示例請求的消息示例參見表A.4。表A.4請求的消息示例請求方法：GetURL：/api/trace?traceCode=010690123456789910999999請求頭:appKey:ak00001timestamp:2023-05-31T09:09:09signature:xxxxxxxxxxxA.5返回示例返回的解密后的消息明文示例參見A.5。表A.5返回消息代碼示例表{"success":true,"result":[{"enterprise":{"enterpriseName":"上海市xxxx有限公司","enterpriseTrademark":"上海xxx","enterpriseType":"0","uniSCID":"91310000000000000000","licNo":"JY00000000000000","certPicture":"data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=",表A.5返回消息代碼示例表（續(xù)）7"certEffectiveDate":"2020-01-01","certExpiryDate":"2030-01-01","legalRepresentative":"張xx","supervisoryAgency":"xxx街道市場監(jiān)管所","scope":"食品生產(chǎn)、銷售","address":"黃浦區(qū)xxx路xxx號","contactPerson":"張xx","contactPhone":,"legalPersonType":"0","establishmentDate":"2020-01-01","businessLicensePicture":"data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=","registeredAddress":"黃浦區(qū)xxx路xxx號","registrationAuthority":"黃浦區(qū)市場監(jiān)督管理局","businessModel":"生產(chǎn)、批發(fā)","certificateStatus":"1""productionName":"飲料A","producerName":"生產(chǎn)廠商A","standard":"500ml","shelfLife":"180","category":"5","barcode":"6930000000001","certNo":"12345678","certPicture":"data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=""production":{"productionDate":"2022-01-01","batchNumber":"20220101","origin":"上海市","certificationPicture":"data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=","certNoOfOrigin":"CDZ000001","certNoOfOriginPicture":"data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=","CIQNo":"CIQ0000001","CIQPicture":"data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=","quarantineInstitution":"檢疫機構(gòu)A","certNoOfQuarantine":"JYZS000001",8表A.5返回消息代碼示例表（續(xù)）"certNoOfQuarantinePicture":"data:application/jpeg;base64,dk8234kljOksjdfkl23iosdf=","executiveStandard":"GB/TXXXXXX""circulation":[{"quantity":1000,"saleDate":"2022-02-01","customerName":"江蘇省南京市xxxx有限公司","customerAddr":"江蘇省南京市xxx路xxx號","customerTel":"138000000