家電領(lǐng)域國家二級(jí)節(jié)點(diǎn)接口規(guī)范

PAGE5國家二級(jí)節(jié)點(diǎn)平臺(tái)技術(shù)規(guī)范接口規(guī)范1范圍本規(guī)范規(guī)定了國家頂級(jí)節(jié)點(diǎn)、企業(yè)節(jié)點(diǎn)以及其他業(yè)務(wù)系統(tǒng)與家電行業(yè)國家二級(jí)節(jié)點(diǎn)平臺(tái)進(jìn)行對(duì)接或數(shù)據(jù)交換的接口規(guī)范。本部分適用于外部系統(tǒng)與家電行業(yè)國家二級(jí)節(jié)點(diǎn)平臺(tái)的接口，完成產(chǎn)品、標(biāo)識(shí)等信息的交換。2規(guī)范性引用文件下列文件對(duì)于本文件的應(yīng)用是必不可少的。但是注日期的引用文件，僅注日期的版本適用于本文件。凡是不注日期的文件，其最新版本（包括所有的修改單）適用于本文件。ITU-TM.3010電信網(wǎng)絡(luò)管理基本原則GB/T29262面向服務(wù)體系結(jié)構(gòu)（SOA）術(shù)語GB/T29798基于Web服務(wù)的IT資源管理規(guī)范3術(shù)語和定義下列術(shù)語和定義適用于本文件。3.1HTTPHyperTextTransferProtocol 超文本傳輸協(xié)議3.2SSL SecureSocketsLayer 安全套接層3.3JSON JavaScriptObjectNotation JS對(duì)象簡(jiǎn)譜3.4SNP-API 國家二級(jí)節(jié)點(diǎn)平臺(tái)3.5請(qǐng)求方 Request 發(fā)起請(qǐng)求的用戶角色3.6實(shí)現(xiàn)方 Implementer 實(shí)現(xiàn)接口具體業(yè)務(wù)邏輯的開發(fā)角色3.7授權(quán) Authorization 調(diào)用的許可，如果沒有對(duì)調(diào)用方的授權(quán)那么對(duì)方是不可以調(diào)用服務(wù)的3.8驗(yàn)簽 CheckSign 為了防止接口被攻擊，需要在服務(wù)端做驗(yàn)簽的邏輯，校驗(yàn)請(qǐng)求的合法性3.9ES elasticsearch 分布式搜索引擎系統(tǒng)3.10REST RepresentationalStateTransfer 一組架構(gòu)約束條件和原則4系統(tǒng)接口要求4.1接口組成4.1.1概述家電行業(yè)國家二級(jí)節(jié)點(diǎn)平臺(tái)接口系統(tǒng)應(yīng)包括登錄接口、產(chǎn)品分頁查詢接口、產(chǎn)品新增接口、產(chǎn)品啟用接口、產(chǎn)品模板分頁查詢接口、產(chǎn)品模板新增接口、標(biāo)識(shí)創(chuàng)建接口、標(biāo)識(shí)狀態(tài)更新接口和標(biāo)識(shí)查詢接口。4.1.2登錄接口應(yīng)支持用戶名和密碼通過驗(yàn)證、密碼加密、不通過報(bào)錯(cuò)返回等功能。4.1.3產(chǎn)品分頁查詢接口應(yīng)支持產(chǎn)品信息（包含產(chǎn)品編碼、名稱、模板編碼、模板名稱、產(chǎn)品序列號(hào)等）查詢等功能。4.1.4產(chǎn)品新增接口應(yīng)支持新增產(chǎn)品的產(chǎn)品信息（包含產(chǎn)品編碼、名稱、模板編碼、模板名稱、產(chǎn)品序列號(hào)等）及明細(xì)屬性的存儲(chǔ)插入等功能。4.1.5產(chǎn)品啟用接口應(yīng)支持禁用狀態(tài)產(chǎn)品的啟用等功能。4.1.6產(chǎn)品模板分頁查詢接口用支持產(chǎn)品模板信息（包含產(chǎn)品模板編碼，名稱，描述）查詢等功能。4.1.7產(chǎn)品模板新增接口應(yīng)支持新增產(chǎn)品模板的信息（包含模板編碼、模板名稱、描述）及明細(xì)屬性的存儲(chǔ)插入等功能。4.1.8標(biāo)識(shí)創(chuàng)建接口應(yīng)支持標(biāo)識(shí)信息（包含標(biāo)識(shí)編碼、產(chǎn)品序列號(hào)、產(chǎn)品編碼、產(chǎn)品名稱、企業(yè)前綴等）及明細(xì)屬性的存儲(chǔ)插入等功能。4.1.9標(biāo)識(shí)狀態(tài)更新接口應(yīng)支持標(biāo)識(shí)的狀態(tài)啟用、停用等功能。4.1.10標(biāo)識(shí)查詢接口應(yīng)支持標(biāo)識(shí)信息（包含標(biāo)識(shí)編碼、產(chǎn)品序列號(hào)、產(chǎn)品編碼、產(chǎn)品名稱、企業(yè)前綴等）及明細(xì)屬性的查詢功能。4.2接口技術(shù)要求——宜采用基于RestAPI接口；——數(shù)據(jù)的請(qǐng)求和返回結(jié)果宜采用JSON格式；——應(yīng)支持跨系統(tǒng)、跨平臺(tái)調(diào)用。4.3接口使用流程4.3.1接口使用流程參考接口使用可以參考以下流程：圖1接口使用流程圖4.3.2業(yè)務(wù)接口需要登錄后才可以對(duì)SNP系統(tǒng)業(yè)務(wù)方面的產(chǎn)品、標(biāo)識(shí)等功能操作。4.3.3通過Http?式調(diào)?SNP-API接?，接口遵循REST規(guī)范，所有的請(qǐng)求和響應(yīng)數(shù)據(jù)編碼皆為utf-8格式，請(qǐng)求的Content-Type是application/json；請(qǐng)求參數(shù)包括公共參數(shù)和業(yè)務(wù)參數(shù)。公共參數(shù)是所有請(qǐng)求必須有的參數(shù)，用戶請(qǐng)求的認(rèn)證，驗(yàn)簽等。4.3.4要求請(qǐng)求頭中必須帶有accessToken。例如：Content-Type:application/jsonaccessToken:XXXXXXXXXXXX注：傳輸使?https加密協(xié)議；json數(shù)據(jù)交換格式；需?持http協(xié)議。5接口模型及參數(shù)5.1請(qǐng)求模型圖2接口請(qǐng)求模型5.2返回模型圖2接口返回模型5.3接口參數(shù)接口的具體請(qǐng)求和返回參數(shù)應(yīng)符合附錄A要求。附錄A（規(guī)范類附錄）接口及其參數(shù)說明A.1登錄接口A.1.1簡(jiǎn)要描述登錄SNP系統(tǒng)獲取登錄令牌。A.1.2請(qǐng)求URL{HOST}/exLoginA.1.3請(qǐng)求?式GET

表A.1登錄接口請(qǐng)求參數(shù)表參數(shù)名參數(shù)說明備注userCode用戶賬號(hào)SNP系統(tǒng)管理員提供secretKey加密后的用戶密碼SNP系統(tǒng)管理員提供A.1.4請(qǐng)求參數(shù)說明A.1.4.1Postman示例A.1.4.2請(qǐng)求參數(shù){"userCode":"XXX","secrectKey":"XXXX"}A.1.4.3返回值{"code":"0","data":{"accessToken":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","accountType":0,"asc":"asc","createTime":"2020-01-1917:03:49","createUserCode":"system","dataMap":{},"deleteFlag":0,"employeeStatus":1,"enableFlag":1,"enableGatedLaunchControl":false,"id":80562,"locale":"zh","masToken":"xxxxxxxxxxxxxxxx","orderBy":"1","orderByType":"asc","pageSize":30,"sex":0,"start":0,"superAdminFlag":0,"updateTime":"2020-01-1917:03:49","updateUserCode":"system","userCode":"jiangyw8","userName":"jiangyw","userType":1,"version":0},"msg":"Success","timestamp":"2020-04-0711:29:29.337"}A.2產(chǎn)品分頁查詢A.2.1簡(jiǎn)要描述產(chǎn)品分頁查詢A.2.2請(qǐng)求URL{HOST}/productSearchPageA.2.3請(qǐng)求?式POSTA.2.4請(qǐng)求參數(shù)說明表A.2產(chǎn)品分頁查詢請(qǐng)求參數(shù)表參數(shù)名參數(shù)說明備注productCode產(chǎn)品編碼productName產(chǎn)品名稱productTemplateId產(chǎn)品模板IdproductTemplateCode產(chǎn)品模板編碼productTemplateName產(chǎn)品模板名稱seqNumber產(chǎn)品序列號(hào)A.2.5Postman示例A.2.6請(qǐng)求參數(shù){"templateCode":"test001"}A.2.7返回值{"msg":"Success","code":"0","data":{"offset":30,"totalPage":1,"pageNo":1,"pageSize":30,"list":[{"createUserCode":"jiangyw8","updateUserName":"jiangyw","attributeList":[{"attributeValue":"100","createUserCode":"jiangyw8","updateUserName":"jiangyw","display":"Y","start":0,"pageSize":30,"orderBy":"1","updateTime":"2020-04-0714:48:35","createUserName":"jiangyw","tenantCode":"88.182.1","templateCode":"test001","version":0,"required":"Y","deleteFlag":0,"asc":"asc","updateUserCode":"jiangyw8","createTime":"2020-04-0714:48:35","attributeType":1,"dataMap":{},"effect":"Y","orderByType":"asc","attributeName":"毛重(KG)","seqNumber":3,"id":94},{"attributeValue":"北滘","createUserCode":"jiangyw8","updateUserName":"jiangyw","display":"Y","start":0,"pageSize":30,"orderBy":"1","updateTime":"2020-04-0714:48:35","createUserName":"jiangyw","tenantCode":"88.182.1","templateCode":"test001","version":0,"required":"Y","deleteFlag":0,"asc":"asc","updateUserCode":"jiangyw8","createTime":"2020-04-0714:48:35","attributeType":0,"dataMap":{},"effect":"Y","orderByType":"asc","attributeName":"產(chǎn)地","seqNumber":2,"id":93},{"attributeValue":"美的","createUserCode":"jiangyw8","updateUserName":"jiangyw","display":"Y","start":0,"pageSize":30,"orderBy":"1","updateTime":"2020-04-0714:48:35","createUserName":"jiangyw","tenantCode":"88.182.1","templateCode":"test001","version":0,"required":"Y","deleteFlag":0,"asc":"asc","updateUserCode":"jiangyw8","createTime":"2020-04-0714:48:35","attributeType":0,"dataMap":{},"effect":"Y","orderByType":"asc","attributeName":"品牌","seqNumber":1,"id":92}],"start":0,"pageSize":30,"orderBy":"1","updateTime":"2020-04-0714:48:35","createUserName":"jiangyw","tenantCode":"88.182.1","templateCode":"test001","source":"手工","version":0,"deleteFlag":0,"asc":"asc","updateUserCode":"jiangyw8","createTime":"2020-04-0714:48:35","templateName":"測(cè)試1","dataMap":{},"templateDescription":"測(cè)試1","orderByType":"asc","id":88,"status":"Y"}],"totalCount":1},"timestamp":"2020-04-0715:01:12.364"}A.3產(chǎn)品新增A.3.1簡(jiǎn)要描述產(chǎn)品新增A.3.2請(qǐng)求URL{HOST}/productSaveA.3.3請(qǐng)求?式POSTA.3.4請(qǐng)求參數(shù)說明表A.3產(chǎn)品新增請(qǐng)求參數(shù)表參數(shù)名參數(shù)說明備注productCode產(chǎn)品編碼productName產(chǎn)品名稱productTemplateId產(chǎn)品模板IdproductTemplateCode產(chǎn)品模板編碼productTemplateName產(chǎn)品模板名稱status狀態(tài)（Y=啟用，N=停用）jump是否跳轉(zhuǎn)(Y=是、N=否)linkhttp跳轉(zhuǎn)鏈接seqNumber產(chǎn)品序列號(hào)productAttributeList明細(xì)屬性A.3.5Postman示例A.3.6請(qǐng)求參數(shù){"productCode":"product001","productName":"產(chǎn)品測(cè)試001","productTemplateId":85,"productTemplateCode":"zhangji","productTemplateName":"zhangjp18","status":"Y","jump":"N","productAttributeList":[{"productCode":"product001","attributeName":"品牌","attributeType":0,"required":"Y","effect":"Y","display":"Y","attributeValue":"1","seqNumber":1},{"productCode":"product001","attributeName":"產(chǎn)地","attributeType":0,"required":"Y","effect":"Y","display":"Y","attributeValue":"1","seqNumber":2},{"productCode":"product001","attributeName":"毛重(KG)","attributeType":1,"required":"Y","effect":"Y","display":"Y","attributeValue":"1","seqNumber":3},{"productCode":"product001","attributeName":"aa","attributeType":0,"required":"Y","effect":"Y","display":"Y","attributeValue":"aa","seqNumber":4}]}A.3.7返回值{"msg":"Success","code":"0","data":1,"timestamp":"2020-04-0715:10:26.935"}A.4產(chǎn)品啟用A.3.1簡(jiǎn)要描述產(chǎn)品啟用A.3.2請(qǐng)求URL{HOST}/productEnableA.3.3請(qǐng)求?式POSTA.3.4請(qǐng)求參數(shù)說明表A.4產(chǎn)品啟用請(qǐng)求參數(shù)表參數(shù)名參數(shù)說明備注productCode產(chǎn)品編碼productName產(chǎn)品名稱productTemplateId產(chǎn)品模板IdproductTemplateCode產(chǎn)品模板編碼productTemplateName產(chǎn)品模板名稱seqNumber產(chǎn)品序列號(hào)A.3.5Postman示例略。A.3.6請(qǐng)求參數(shù){"productCode":"ss12545","status":"Y"}A.3.7返回值{"code":"0","msg":"Success","timestamp":"2020-04-0711:24:57.660"}A.5標(biāo)識(shí)創(chuàng)建A.5.1簡(jiǎn)要描述標(biāo)識(shí)創(chuàng)建A.5.2請(qǐng)求URL{HOST}/identityRegistryA.5.3請(qǐng)求?式POSTA.5.4請(qǐng)求參數(shù)說明表A.5標(biāo)識(shí)創(chuàng)建請(qǐng)求參數(shù)說明參數(shù)名參數(shù)說明備注identityCode標(biāo)識(shí)編號(hào)productCode產(chǎn)品編碼必須先新增產(chǎn)品productName產(chǎn)品名稱必須先新增產(chǎn)品seqNumber產(chǎn)品序列號(hào)必須先新增產(chǎn)品productTemplateCode產(chǎn)品模板編碼必須先新增產(chǎn)品模板productTemplateName產(chǎn)品模板名稱必須先新增產(chǎn)品模板prefixCode企業(yè)前綴website官網(wǎng)地址identityRule標(biāo)識(shí)規(guī)則link跳轉(zhuǎn)URLidentityAttributes標(biāo)識(shí)屬性json字符串createDate標(biāo)識(shí)生成日期createNum標(biāo)識(shí)生成數(shù)量startNum號(hào)段起始endNum號(hào)段截止batchNum當(dāng)前批次A.5.5Postman示例略A.5.6請(qǐng)求參數(shù){"productName":"midea0210","identityRule":"R01","template":"家電工業(yè)互聯(lián)網(wǎng)標(biāo)識(shí)打印模版","printCopies":1,"createNum":1,"createDate":"2020-04-07","startNum":"1546692040700001","endNum":"1546692040700001","seqNumber":54669,"link":"/omn/20190508/20190508A0AM10.html","productCode":"midea0210","productTemplateCode":"-","productTemplateName":"-"}A.5.7返回值{"code":"0","msg":"Success","timestamp":"2020-04-0714:36:39.283","data":"LOT171535AE9F800000002"}A.6標(biāo)識(shí)狀態(tài)更新A.6.1簡(jiǎn)要描述根據(jù)條件對(duì)當(dāng)前租戶的標(biāo)識(shí)更新A.6.2請(qǐng)求UR{HOST}/identityUpdateA.6.3請(qǐng)求?式POSTA.6.4請(qǐng)求參數(shù)說明表A.6標(biāo)識(shí)狀態(tài)更新請(qǐng)求參數(shù)說明參數(shù)名參數(shù)說明備注identityCode標(biāo)識(shí)編號(hào)productCode產(chǎn)品編碼productName產(chǎn)品名稱productTemplateCode產(chǎn)品模板編碼productTemplateName產(chǎn)品模板名稱prefixCode企業(yè)前綴identityRule標(biāo)識(shí)規(guī)則link跳轉(zhuǎn)URLidentityAttributes標(biāo)識(shí)屬性json字符串A.6.5Postman示例A.6.5請(qǐng)求參數(shù){ "identityCode":"1515652040700003", "status":"N"}A.6.6返回值{"code":"0","msg":"Success","timestamp":"2020-04-0714:35:12.241"}A.7標(biāo)識(shí)查詢A.7.1簡(jiǎn)要描述根據(jù)條件查詢當(dāng)前租戶的標(biāo)識(shí)A.7.2請(qǐng)求URL{HOST}/identitysA.7.3請(qǐng)求?式POSTA.7.4請(qǐng)求參數(shù)說明表A.7標(biāo)識(shí)查詢請(qǐng)求參數(shù)說明參數(shù)名參數(shù)說明備注identityCode標(biāo)識(shí)編號(hào)productCode產(chǎn)品編碼productName產(chǎn)品名稱productTemplateCode產(chǎn)品模板編碼productTemplateName產(chǎn)品模板名稱prefixCode企業(yè)前綴identityRule標(biāo)識(shí)規(guī)則link跳轉(zhuǎn)URLidentityAttributes標(biāo)識(shí)屬性json字符串A.7.5Postman示例略A.7.6請(qǐng)求參數(shù){ "identityCode":"1515652040700003"}A.7.7返回值{"msg":"Success","code":"0","data":{"offset":30,"totalPage":1,"pageNo":1,"pageSize":30,"list":[{"pageSize":30,"orderBy":"1","createUserName":"jiangyw","remark":"","prefixCode":"88.182.1","tenantCode":"88.182.1","identityCode":"1515652040700003","productName":"美的（Midea）C21-simple103","deleteFlag":0,"identityRule":"R01","dataMap":{},"productTemplateName":"美的電磁爐","createUserCode":"jiangyw8","updateUserName":"jiangyw","start":0,"updateTime":"2020-04-0714:26:55","version":0,"identityAttributes":"[{\"attributeValue\":\"美的\",\"attributeType\":\"0\",\"display\":\"Y\",\"attributeName\":\"品牌\",\"seqNumber\":1},{\"attributeValue\":\"中國大陸\",\"attributeType\":\"0\",\"display\":\"Y\",\"attributeName\":\"產(chǎn)地\",\"seqNumber\":2},{\"attributeValue\":\"3.44\",\"attributeType\":\"1\",\"display\":\"Y\",\"attributeName\":\"毛重(KG)\",\"seqNumber\":3},{\"attributeValue\":\"/api-file/ossDown/32883248FE8946CCA59DDB36C80BF571/lc_sit/QQ視頻20200204160614_1580984068704.mp4,\",\"attributeType\":\"3\",\"display\":\"Y\",\"attributeName\":\"視頻\",\"seqNumber\":4},{\"attributeValue\":\"/api-file/ossDown/32883248FE8946CCA59DDB36C80BF571/lc_sit/QQ圖片20200206143040_1580984075495.png,/api-file/ossDown/32883248FE8946CCA59DDB36C80BF571/lc_sit/微信圖片_20200207155033_1581061602007.png,\",\"attributeType\":\"2\",\"display\":\"Y\",\"attributeName\":\"圖片\",\"seqNumber\":5},{\"attributeValue\":\"56216006234\",\"attributeType\":\"0\",\"display\":\"Y\",\"attributeName\":\"商品編號(hào)\",\"seqNumber\":6},{\"attributeValue\":\"C21-Simple101\",\"attributeType\":\"0\",\"display\":\"Y\",\"attributeName\":\"貨號(hào)\",\"seqNumber\":7},{\"attributeValue\":\"觸摸式\",\"attributeType\":\"0\",\"display\":\"Y\",\"attributeName\":\"操控方式\",\"seqNumber\":8},{\"attributeValue\":\"350*280*60\",\"attributeType\":\"0\",\"display\":\"Y\",\"attributeName\":\"尺寸\",\"seqNumber\":9},{\"attributeValue\":\"2300W\",\"attributeType\":\"0\",\"display\":\"Y\",\"attributeName\":\"最大功率\",\"seqNumber\":10}]","asc":"asc","productTemplateCode":"mideadcl","printNumber":1,"updateUserCode":"jiangyw8","productCode":"MideaC21simple103","createTime":"2020-04-0714:26:55","orderByType":"asc","dataSource":"PC","status":"Y"}],"totalCount":1},"timestamp":"2020-04-0714:27:48.478"}附錄B（規(guī)范性附錄）錯(cuò)誤分類代碼B.1錯(cuò)誤分類代碼表B.1錯(cuò)誤分類代碼表錯(cuò)誤代碼錯(cuò)誤說明建議處理方式0Success1系統(tǒng)繁忙,請(qǐng)稍后再試101賬號(hào)或密碼錯(cuò)誤404請(qǐng)求頁面不存在500服務(wù)器異常210000保存標(biāo)識(shí)到es中報(bào)錯(cuò)210001企業(yè)前綴為空210002ES操作失敗210003標(biāo)識(shí)為空210004{0}獲取標(biāo)識(shí)屬性錯(cuò)誤210000保存標(biāo)識(shí)到es中報(bào)錯(cuò)210001企業(yè)前綴為空210002ES操作失敗210003標(biāo)識(shí)為空210004{0}獲取標(biāo)識(shí)屬性錯(cuò)誤210005企業(yè)前綴為空210006保存報(bào)錯(cuò)210007產(chǎn)品編碼不能為空210008生成日期不能為空210009{0}更新標(biāo)識(shí)失敗210010生成數(shù)量不能為空210011此區(qū)間標(biāo)識(shí)正在生成,請(qǐng)稍后再試210012請(qǐng)先維護(hù)系統(tǒng)管理的租戶配置210013標(biāo)識(shí)屬性為空210014產(chǎn)品序列號(hào)為空210015標(biāo)識(shí)碼[{0}]格式錯(cuò)誤210016{0}解析失敗或解析為空210017打印數(shù)量不能超過1000個(gè)210018注冊(cè)/解析標(biāo)識(shí)已超過最大標(biāo)識(shí)