食品安全信息追溯基礎技術規(guī)范 第3部分：數(shù)據(jù)接口

1DB53/TXXXX.3—2022食品安全信息追溯基礎技術規(guī)范第3部分：數(shù)據(jù)接口本文件規(guī)定了食品安全信息追溯的數(shù)據(jù)接口技術要求、數(shù)據(jù)接口參數(shù)和接口安全。本文件適用于食品安全信息追溯的數(shù)據(jù)交換、傳輸和認證。2規(guī)范性引用文件下列文件中的內容通過文中的規(guī)范性引用而構成本文件必不可少的條款。其中，注日期的引用文件，僅該日期對應的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適用于本文件。GB/T7408數(shù)據(jù)元和交換格式信息交換日期和時間表示法GB/T7635.1全國主要產品分類與代碼第1部分：可運輸產品GB12904商品條碼零售商品編碼與條碼表示GB/T38155重要產品追溯追溯術語RFC1945超文本傳輸協(xié)議1.0(Hypertexttransferprotocol--HTTP/1.0)RFC2616超文本傳輸協(xié)議1.1(Hypertexttransferprotocol--HTTP/1.1)RFC4627JSON格式定義(Theapplication/JSONmediatypeforjavascriptObjectnotation)RFC4825可擴展標記語言配置接入?yún)f(xié)議(Theextensiblemarkuplanguage(XML)configurationaccessprotocol(XCAP))3術語和定義下列術語和定義適用于本文件。3.1數(shù)據(jù)接口datainterface一組用于數(shù)據(jù)交換的服務，包括服務的功能、位置以及通訊的協(xié)議、傳輸格式和認證方法。3.2接口協(xié)議interfaceprotocol需要進行信息交換的接口間需要遵從的通信方式和要求。其內容包括協(xié)議約定、消息頭域、消息體內容等，確定通信程序發(fā)送消息和接收消息的規(guī)則。3.3消息頭MessageHeader消息頭包含了關于消息本身的元數(shù)據(jù)（例如，發(fā)送者和目標詳細信息、消息屬性、消息類型），不同傳輸?shù)念^包含不同類型的信息。3.4安全認證securitycertificate保證數(shù)據(jù)傳輸安全的加密方法和身份認證方法。3.5“名稱/值”對name/valuepair2DB53/TXXXX.3—2022JSON的數(shù)據(jù)存儲格式，“名稱/值”對組合中的名稱寫在前面雙引號中，值寫在后面雙引號中，中間用冒號隔開，“名稱/值”對之間由逗號分隔。3.6追溯系統(tǒng)中對追溯單元進行唯一標識的代碼。[來源：GB/T38155—2019，2.10]4縮略語下列縮略語適用于本文件。HTTPS：安全超文本傳輸協(xié)議（HyperTextTransferProtocoloverSecureSocketLayer）JSON：一種輕量級的數(shù)據(jù)交換格式(JavaScriptObjectNotation)MD5：消息摘要算法第五版（Message-DigestAlgorithm5）RESTFul：基于HTTPS協(xié)議，可以使用XML格式定義或JSON格式定義Token：是服務端生成的一串加密字符串、以作客戶端進行請求的一個“令牌”URL：互聯(lián)網(wǎng)服務程序上用于指定信息位置的表示方法（UniformResourceLocator）UTF-8：一種可變長度字符編碼(8-bitUnicodeTransformationFormat)XML：可擴展標記語言（ExtensibleMarkupLanguage）5技術要求5.1基本要求5.1.1接口要求接口通過服務調用實現(xiàn)信息交換，應符合下列要求：——采用符合GB/T7408規(guī)定的日期類型；——接口請求與接口響應均采用JSON數(shù)據(jù)格式；——建立接口日志記錄，能識別數(shù)據(jù)異?；蜃匪萁粨Q數(shù)據(jù)情況。5.1.2容錯要求發(fā)生錯誤時，接口服務方將詳細的錯誤信息返回至接口調用方，由接口調用方對錯誤進行記錄分析和整改。5.2接口協(xié)議接口協(xié)議方式包括：——采用基于HTTPS傳輸協(xié)議的RESTFul接口方式；——采用JSON格式報文打包方式。5.3消息頭基本參數(shù)5.3.1安全認證接口Header參數(shù)安全認證接口Header參數(shù)見表1。3DB53/TXXXX.3—2022表1安全認證接口Header參數(shù)表參數(shù)名稱參數(shù)描述Authorization接口授權采用默認值5.3.2業(yè)務交互接口Header參數(shù)業(yè)務交互接口Header參數(shù)見表2。表2業(yè)務交互接口Header參數(shù)表接口授權授權token，格式為：bearer+token例如：bearereyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJpc3N1c2VyIiwiYXVkIjoiYXVkaWVuY2UiLCJ0ZW5hbnRfaWQiOiIwMDAwMDAiLCJ1c2VyX25hbWUiOiLkupHljZfkupHpgJ_kv6Hmga_mioDmnK_mnInpmZDlhazlj7giLCJ0b2tlbl90eXBlIjoiYWNjZXNzX3Rva2VuIiwicm9sZV9uYW1lIjoiZW50ZXJwcmlzZSIsInVzZXJfdHlwZSI6Im1hc3RlciIsInVzZXJfaWQiOiI5OTY0NTgzMDUxMTgxMjE4MyIsInJvbGVfaWQiOiIxNDAyNDM3NTkyMDc4NzQ5Njk3Iiwibmlja19uYW1lIjoi5LqR5Y2X5LqR6YCf5L-h5oGv5oqA5pyv5pyJ6ZmQ5YWs5Y-4IiwiZGV0YWlsIjp7InR5cGUiOiJ3ZWIifSwiZW50ZXJwcmlzZV9jb2RlIjoiOTE1MzAxMDJNQTZLNEtBNTdRIiwiZGVwdF9pZCI6IjIzNyIsImFjY291bnQiOiI5MTUzMDEwMk1BNks0S0E1N1EiLCJjbGllbnRfaWQiOiJzYWJlciIsImV4cCI6MTY1NTM3MDM4MCwibmJmIjoxNjU1MzY2NzgwfQ.M8o2wrI6eKb9JovCDKLGhZVAB4k4tmwA-GmUGEGzZ71zCStoL62e0vmRlzppuniuOcvQa8cbqHyz1E_uk-MyEQ采用默認值5.4基本數(shù)據(jù)類型基本數(shù)據(jù)類型說明見表3。表3數(shù)據(jù)類型說明表6數(shù)據(jù)接口6.1數(shù)據(jù)接口分類4DB53/TXXXX.3—2022數(shù)據(jù)接口分類見圖1所示。圖1數(shù)據(jù)接口分類6.2基本信息接口6.2.1安全認證接口獲取用戶登錄token信息，進行用戶安全認證，相關參數(shù)見表4。表4安全認證接口數(shù)據(jù)是是是是是6.2.2商品類別查詢接口查詢追溯商品類別，參數(shù)見表5。表5商品類別查詢接口數(shù)據(jù)是String是查詢追溯商品類別，返回值見表6。5DB53/TXXXX.3—2022表6商品類別查詢返回值String6.2.3圖片文件上傳接口上傳食品追溯相關數(shù)據(jù)時所需提供的圖片文件，參數(shù)見表7。表7圖片文件上傳接口數(shù)據(jù)File是String是圖片文件上傳接口，返回值見表8。表8返回值86.2.4新增食品生產經營市場主體信息備案上傳新增食品生產企業(yè)、食品經營企業(yè)的基本備案信息，如：企業(yè)統(tǒng)一社會信用代碼、企業(yè)名稱等，參數(shù)見表9。表9新增食品市場主體信息備案是是是是是是是是6DB53/TXXXX.3—2022表9新增食品市場主體信息備案（續(xù)）是是營業(yè)執(zhí)照圖片URL地址是許可證圖片圖片URL地址新增食品市場主體信息備案，返回值見表8所示。6.2.5新增原輔料信息備案上傳新增追溯食品的原輔料基本備案信息，如：類別、名稱、來源等，參數(shù)見表10。表10新增原輔料備案數(shù)據(jù)是是是是4是是是是是是2是是新增原輔料信息備案，返回值見表8所示。6.2.6新增生產食品信息備案上傳新增生產食品備案基本信息，包括食品類別、食品名稱等，參數(shù)見表11。表11新增生產食品信息備案數(shù)據(jù)是是是是7DB53/TXXXX.3—2022表11新增生產食品信息備案數(shù)據(jù)（續(xù)）否是保質期單位，D天M月Y年是是是4是是是是是是否4是是新增生產食品信息備案，返回值見表8所示。6.2.7新增采購食品信息備案上傳新增采購食品備案基本信息，包括食品類別、食品名稱等，參數(shù)見表12。表12新增采購食品信息備案數(shù)據(jù)是是是是是是4是是是是是是4是新增采購食品信息備案，返回值見表8所示。8DB53/TXXXX.3—20226.2.8新增倉庫備案上傳新增倉庫備案基本信息，參數(shù)見表13。表13新增倉庫備案數(shù)據(jù)warehouseName是warehouseAddr是warehouseType是是是是是是新增倉庫備案，返回值見表8所示。6.3追溯信息接口6.3.1新增生產食品數(shù)據(jù)上傳新增生產食品數(shù)據(jù)信息，包括批次號、生產日期等，參數(shù)見表14。表14新增生產食品數(shù)據(jù)是Array是是是是是是是新增生產食品數(shù)據(jù)，返回值見表8所示。6.3.2上傳質檢報告上傳生產食品的質檢報告圖片，參數(shù)見表15。表15上傳質檢報告數(shù)據(jù)是是質檢報告圖片URL地址9DB53/TXXXX.3—2022上傳質檢報告，返回值見表8所示。6.3.3新增原輔料進貨數(shù)據(jù)上傳新增原輔料進貨信息，包括原料類別、數(shù)量等，參數(shù)見表16。表16新增原輔料進貨數(shù)據(jù)是是是是是是是是新增原輔料進貨數(shù)據(jù)，返回值見表8所示。6.3.4新增首站進貨數(shù)據(jù)流通企業(yè)上傳新增食品首站進貨數(shù)據(jù)，參數(shù)見表17。表17新增首站進貨數(shù)據(jù)是是是是是是是是是是是4是是是是是新增首站進貨數(shù)據(jù)，返回值見表8所示。DB53/TXXXX.3—20226.3.5新增食品銷貨數(shù)據(jù)流通企業(yè)上傳新增食品銷貨訂單數(shù)據(jù)，參數(shù)見表18。表18新增食品銷貨數(shù)據(jù)String4是String是String是String是String是Datetime是String否是新增食品銷貨數(shù)據(jù)，返回值見表8所示。6.4追溯碼生成接口6.4.1追溯碼下載接口食品追溯碼的下載，參數(shù)見表19。表19追溯碼下載數(shù)據(jù)是String是是是追溯碼下載，返回值見表8所示。6.4.2追溯碼樣式新增新增追溯碼樣式（帶碼值和圖片），參數(shù)見表20。表20追溯碼樣式新增數(shù)據(jù)String是String是String是String是二維碼示例圖URL地址是是String是DB53/TXXXX.3—2022追溯碼樣式下載，返回值見表8所示。6.4.3追溯碼樣式生成生成追溯碼（帶碼值，有圖片），參數(shù)見表21。表21追溯碼樣式生成數(shù)據(jù)是是追溯碼樣式生成，返回值見表8所示。6.4.4追溯碼生成生成追溯碼（只有碼值），參數(shù)見表22。表22追溯碼生成數(shù)據(jù)String是String是String是是追溯碼生成，返回值見表8所示。6.4.5追溯碼賦碼綁定生產企業(yè)追溯碼綁定對應食品，參數(shù)見表23。表23追溯碼賦碼綁定數(shù)據(jù)String是String是String是String是String否追溯碼賦碼綁定，返回值見表8所示。7接口安全7.1安全認證食品安全信息追溯數(shù)據(jù)接口采用數(shù)字令牌的方式實現(xiàn)安全認證。即服務端生成的一串加密字符串、以作客戶端進行請求的一個“令牌”，如果“令牌”不存在，說明請求無效。7.2安全傳輸DB53/TXXXX.3—2022使用食品安全信息追溯信息數(shù)據(jù)接口的生產經營者，可以申請具有相應資質的CA中心簽發(fā)的數(shù)字證書。采用HTTPS的方式，使用數(shù)字證書對接口的傳輸內容進行數(shù)字簽名,實現(xiàn)身份識別和數(shù)據(jù)傳輸安全。7.3數(shù)字令牌使用食品安全信息追溯數(shù)據(jù)接口的生產經營者,可以申請追溯平臺簽發(fā)的唯一的數(shù)字令牌。使用接口傳輸數(shù)據(jù)時附加數(shù)字令牌,實現(xiàn)身份識別認證。數(shù)字令牌的有效期為1小時，令牌失效后生產經營者需要重新申請新的令牌，生產經營者的新令牌一經頒發(fā)，原有令牌即刻失效。7.4密碼算法數(shù)字證書和數(shù)字令牌采用的密碼算法，應采用符合國家規(guī)定的密碼算法。DB53/TXXXX.3—2022HTTP狀態(tài)碼表HTTP響應報文狀態(tài)碼，見表A.1。表A.1HTTP響應報文狀態(tài)碼表HTTP狀態(tài)碼POST/PUT消息，帶消息體消息已接收不帶消息體BadRequestUnauthorizedForbiddenNotFoundTooManyRequestInternalServerErrorDB53/TXXXX.3—2022響應報文樣例（JSON格式）B.1安全認證接口B.1.1認證請求請求示例：tenantId:000000username:91530102MA6K4KA57Qpassword:xxxxxxxgrant_type:passwordB.1.2信息返回{"tenant_id":"91530102MA6PHKJ764","user_id":"99645830511814941","dept_id":"530102","post_id":"-1","role_id":"1402437592078749697","oauth_id":"","account":"91530102MA6PHKJ764","user_name":"云南xxxxxx技術有限公司","nick_name":"xxx","role_name":"enterprise","avatar":"冷鏈系統(tǒng)企業(yè)用戶","access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJpc3N1c2VyIiwiYXVkIjoiYXVkaWVuY2UiLCJ0ZW5hbnRfaWQiOiIwMDAwMDAiLCJ1c2VyX25hbWUiOiLkupHljZfpvI7ogIDkv6Hmga_mioDmnK_mnInpmZDlhazlj7giLCJ0b2tlbl90eXBlIjoiYWNjZXNzX3Rva2VuIiwicm9sZV9uYW1lIjoiZW50ZXJwcmlzZSIsInVzZXJfdHlwZSI6Im1hc3RlciIsInBvc3RfaWQiOiItMSIsInVzZXJfaWQiOiI5OTY0NTgzMDUxMTgxNDk0MSIsInJvbGVfaWQiOiIxNDAyNDM3NTkyMDc4NzQ5Njk3Iiwibmlja19uYW1lIjoi5p2O5paH5aqbIiwiZGV0YWlsIjp7InR5cGUiOiJ3ZWIifSwiZW50ZXJwcmlzZV9jb2RlIjoiOTE1MzAxMDJNQTZQSEtKNzY0IiwiZGVwdF9pZCI6IjUzMDEwMiIsImFjY291bnQiOiI5MTUzMDEwMk1BNlBIS0o3NjQiLCJjbGllbnRfaWQiOiJzYWJlciIsImV4cCI6MTY1NTM2ODA4OSwibmJmIjoxNjU1MzY0NDg5fQ.FO7so_nz1QRNRpITxgH_Uv9bMNxYuHv3kutET_yKNibzQi6rz18ZzT_kC1E1gp4RVMmvlwhWy8s2hsJu7S9phg","refresh_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJpc3N1c2VyIiwiYXVkIjoiYXVkaWVuY2UiLCJ1c2VDB53/TXXXX.3—2022yX2lkIjoiOTk2NDU4MzA1MTE4MTQ5NDEiLCJ0b2tlbl90eXBlIjoicmVmcmVzaF90b2tlbiIsImNsaWVudF9pZCI6InNhYmVyIiwiZXhwIjoxNjU1OTY5Mjg5LCJuYmYiOjE2NTUzNjQ0ODl9.Yjnj2aLG6P6J3qHhwrQt1Z3c1lzlPS0oi19UXGKRKGazPRsFPKxOiG5s_Iy_PXpk20jYKDvp50JVsiXj3iBztA","token_type":"bearer","expires_in":3600,"detail":{"license":"poweredbyyunsu"}B.2商品類別查詢接口{"success":true,{"id":-1,"goodsCatalogId":"99645830511722496","hasChildren":false,"goodsCatalogName":"冷鏈畜類","parentId":-1,{"id":"99645830511722496","goodsCatalogId":"99645830511722917","hasChildren":false,"goodsCatalogName":"整頭及半頭鮮或冷藏的野牛肉","parentId":"99645830511722496","msg":"操作成功"B.3圖片文件上傳接口{"code":"200","msg":"操作成功"“data”:DB53/TXXXX.3—2022{"name":"/foodTraceFile/upload/20220926/03eb98dd5e6a2988a6b7a10bd9d9e49d.jpeg"},"success":true,B.4新增食品生產經營市場主體信息備案{"code":"200","msg":"操作成功""success":true,B.5新增原輔料備案{"code":"200","msg":"操作成功""data":["entMateriaInfoId":"1530067222014230529"],"success":true,B.6