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

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