廣東省藥具智能發(fā)放機接口標準

廣東省藥具智能發(fā)放機接口標準（2021年7月12日）目錄TOC\o"1-2"\h\u一、接入要求 3二、發(fā)放機顯示能力要求 31、動態(tài)二維碼顯示 32、動態(tài)二維碼的生成 3三、發(fā)放機基礎能力要求 3四、通訊協(xié)議 4五、發(fā)放機的安裝、注冊和激活流程 5六、發(fā)放機使用流程 5七、消息通信接口標準定義 67.1消息主題定義 67.2消息格式定義 67.3指令定義 77.4指令示例 117.5指令執(zhí)行邏輯 12一、接入要求藥具智能發(fā)放機（以下簡稱“發(fā)放機”）可依據(jù)本標準完成同廣東省免費提供基本避孕藥具服務管理一體化信息平臺（以下簡稱“平臺”）的對接，將相關數(shù)據(jù)實時同步到平臺，不需要通過第三方轉存?zhèn)鬏?，?shù)據(jù)需要加密傳輸，確保數(shù)據(jù)可靠性和安全性。平臺通過控制接口，實現(xiàn)對發(fā)放機的實時控制。二、發(fā)放機顯示能力要求1、動態(tài)二維碼顯示發(fā)放機可根據(jù)平臺提供的動態(tài)二維碼接口生成動態(tài)二維碼，并顯示在發(fā)放機顯示屏上，要求發(fā)放機可定時請求數(shù)據(jù)接口對二維碼更新。2、動態(tài)二維碼的生成動態(tài)二維碼的構成分為兩部分，第一部分為平臺提供的動態(tài)二維碼服務地址，第二部分為平臺提供的發(fā)放機參數(shù)及時間戳信息封裝加密之后的字符串。發(fā)放機上電后，平臺將二維碼字符串發(fā)給發(fā)放機（指令見7.3節(jié)c106指令），發(fā)放機將二維碼字符串轉換成二維碼顯示在顯示屏上。當用戶掃描二維碼確認領取后，平臺對其進行領取校驗及判斷，發(fā)放機執(zhí)行平臺發(fā)出的指令并將反饋指令發(fā)給平臺，平臺將更新二維碼的指令發(fā)給發(fā)放機，發(fā)放機將新的動態(tài)二維碼更新在顯示屏上。三、發(fā)放機基礎能力要求發(fā)放機采用MQTT物聯(lián)網(wǎng)通信協(xié)議。發(fā)放機支持對自己的時鐘進行設置，定時向平臺的時鐘服務器請求當前時間，并進行更新（請求及響應指令見7.3節(jié)c109指令）。發(fā)放機通電后，自動連接MQTT消息服務，并告知平臺自身的信息，包括發(fā)放機編號、廠家代號、安放地址（GPS，格式“經(jīng)度，緯度”）、連接狀態(tài)、運行狀態(tài)、庫存狀態(tài)，平臺根據(jù)這些信息判斷發(fā)放機是否注冊，如果未注冊，則先進行注冊，同時判斷發(fā)放機的位置信息是否有變化，如果有變化則更新為新的地理位置。其中發(fā)放機編號使用發(fā)放機芯片的IMEI編號。（芯片的IMEI即代表了發(fā)放機，當芯片損壞更換芯片后，需要把該發(fā)放機對應的網(wǎng)點信息中的發(fā)放機標識也進行更新。當芯片正常，發(fā)放機其他部件損壞進行更換時，系統(tǒng)無需任何操作。）廠家代號由采購方提供，當發(fā)放機廠家計劃接入平臺時，向采購方進行申請。發(fā)放機具備采集地理位置坐標的能力，采集的坐標為百度坐標系，坐標采用十進制表示。每次發(fā)生領用或發(fā)放機狀態(tài)更改后，發(fā)放機主動將變動信息發(fā)送給MQTT消息服務。具備監(jiān)聽并響應MQTT消息服務發(fā)送給自己的消息的能力。具體的消息指令見7.3節(jié)。四、通訊協(xié)議要求發(fā)放機支持MQTT物聯(lián)網(wǎng)通信協(xié)議，可通過協(xié)議將發(fā)放機的數(shù)據(jù)信息同步到平臺，并實現(xiàn)平臺對發(fā)放機的實時控制。發(fā)放機支持4G全網(wǎng)通（移動/聯(lián)通/電信）移動通信網(wǎng)絡。五、發(fā)放機的安裝、注冊和激活流程發(fā)放機部署前，發(fā)放機廠家需要向采購方申請MQTT服務的連接地址、賬號密碼和廠家代碼，由采購方為發(fā)放機廠家進行分配。發(fā)放機的安裝、注冊和激活流程如下：發(fā)放機部署到發(fā)放位置后，安裝、上電，即自動完成同MQTT服務的連接和注冊。發(fā)放機管理人員通過微信公眾號注冊發(fā)放機網(wǎng)點，注冊時發(fā)放機標識填寫該發(fā)放機的IMEI編碼，完成網(wǎng)點和發(fā)放機的綁定。發(fā)放機管理員聯(lián)系本級或者上級單位完成網(wǎng)點出庫，給發(fā)放機補貨。補貨完成后，發(fā)放機等待群眾掃碼領取。六、發(fā)放機使用流程用戶通過微信掃描動態(tài)二維碼領取藥具流程：七、消息通信接口標準定義7.1消息主題定義規(guī)則：MQTT消息主題定義：廠家編碼/發(fā)放機ID。廠家編碼為GD，平臺服務器的ID編碼為GD001，發(fā)放機的ID采用IMEI號。例如：廠家編碼=GD，服務器的ID=GD001，發(fā)放機ID=861265732345497，則發(fā)放機接收消息的主題為GD/861265732345497。平臺服務器接收消息的主題為GD/GD001。備注：接收消息的主題必須是大寫。7.2消息格式定義名稱說明是否必填值對說明c【code】簡寫，通訊指令是string1-4位數(shù)字字符f【from】簡寫，發(fā)送方ID是string發(fā)布方的IDt【to】簡寫，接收送方ID是string接收方的IDs【saleid】簡寫，訂單號，系統(tǒng)唯一是string最長32位,大寫，C2，C3必填m【message】簡寫，消息內容是string由code碼來解析messagee【encryption】簡寫是string約定密鑰k生成e=md5(f+t+s+m+k)，32位，大寫k【key】簡寫string由采購方提供說明：1、當s、m沒有含義時，默認傳0。2、參數(shù)類型目前均為string。3、C3指令的s（即訂單號）參數(shù)，要使用C2指令的s參數(shù)值。7.3指令定義消息字段說明消息說明c=2s->c，平臺下發(fā)出貨指令m=N&CN:出貨盒數(shù)（1--99）C:出貨貨道（1-4）c=3c->s，發(fā)放機應答平臺出貨執(zhí)行結果m=R&TR:出藥具執(zhí)行結果狀態(tài)（3：訂單重復）T:該指令發(fā)出時間，如：2021-04-1115:10:21c=4s->c，平臺下發(fā)查詢指令m=0無參數(shù)，設置為“0”c=5c->s，發(fā)放機應答平臺查詢結果m=R&NR0：正常2：故障）N:已出數(shù)量（0--99999）（同C15）c=15c->s，發(fā)放機在貨將盡、缺貨、故障時主動上報狀態(tài)m=R&N&CHANNELINFOR0：正常2：故障(故障優(yōu)先缺貨)）當一個貨道故障時，機器為故障狀態(tài)當一個貨道缺貨時，機器為缺貨狀態(tài)（機器缺貨時會通知管理員補貨）N:已出數(shù)量（0--99999）CHANNELINFO：機器的貨道信息，包括貨道號、貨道運行狀態(tài)、貨道庫存狀態(tài)、貨道剩余庫存(注意順序，根據(jù)貨道號從小到大拼接)，各個貨道信息以“,”分隔，信息項以“-”分隔。貨道運行狀態(tài)：0-正常，1-故障；貨道庫存狀態(tài)：0-正常，1-缺貨，2-貨將盡如1-0-0-8,2-1-0-4,3-0-1-5c=106s->c，服務器下二維碼顯示指令m=QRCODE參數(shù)，二維碼字符串（最多80字符）c=107c->s，發(fā)放機應答m=R0：顯示OK1：顯示錯誤c=108c->s，發(fā)放機上電后告知平臺自身信息和狀態(tài)m=IMEI&MCODE&GPS&LOCTYPE&LINKSTSTUS&RUNSTSTUS&STOCKSTATUS&ICCID&ISMULCHANNEL&CHANNELNUM&CHANNELINFO&VERIMEI:發(fā)放機編號，MCODE：廠家代號，GPS：安裝坐標（十進制坐標，請使用百度坐標系，按照經(jīng)度在前，緯度在后用逗號拼接），LOCTYPE（坐標系），代碼GPS：標準坐標BAIDU：百度坐標系LINKSTSTUS：連接狀態(tài)：（0-正常，1-離線），RUNSTSTUS：運行狀態(tài)：（0-正常，1-故障），當一個貨道故障時，機器為故障狀態(tài)STOCKSTATUS：庫存狀態(tài)：（0-正常，1-缺貨），當一個貨道缺貨時，機器為缺貨狀態(tài)（機器缺貨時會通知管理員補貨）ICCID：移動物聯(lián)卡標識ISMULCHANNEL：是否支持多品種藥具（0-不支持，1-支持）CHANNELNUM：貨道數(shù)CHANNELINFO：機器的貨道信息，包括貨道號、貨道運行狀態(tài)、貨道庫存狀態(tài)、貨道剩余庫存(注意順序，根據(jù)貨道號從小到大拼接)，各個貨道信息以“,”分隔，信息項以“-”分隔，貨道運行狀態(tài)：0-正常，1-故障，貨道庫存狀態(tài)：0-正常，1-缺貨，2-貨將盡。如1-0-0-5,2-1-0-3,3-0-1-5,4-1-0-3VER：機器版本號（向采購方申請），如GD.V2.0.0如：861265732345497&GD&115.580402,35.177301&BAIDU&0&0&0&89860411101871395909&1&4&1-0-0-5,2-1-0-3，3-0-1-5，4-1-0-3&GD.V2.0.0c=109c->s，發(fā)放機請求平臺時鐘服務器時間M=0c=110s->c，平臺應答發(fā)放機請求M=TT:時鐘服務器當前時間如：2021-05-0610:10:24C=113s->c，平臺向發(fā)放機發(fā)送屏顯消息M=MSG消息內容如：“請微信掃碼領取藥具”“請在手機上選擇領取藥具”“請取貨”“領取失敗，請查看手機提示”“貨道【1,2,3】缺貨！”（根據(jù)缺貨貨道號，在中括號中逗號分隔顯示）“設備【故障】！”C=114c->s，發(fā)放機應答m=R0：顯示OK1：顯示錯誤C=115s->c，平臺向發(fā)放機發(fā)送開關燈時間段m=OpenOpen：開燈時間段示例：18:00-23:59（關燈時間段通過開燈時間段算出，一天24小時減去開燈時間則為關燈時間段）C=116c->s,發(fā)放機應答m=R0：設置OK1：設置錯誤C=117s->c,平臺向發(fā)放機發(fā)送開機時間段m=OpenOpen：開機時間段示例：6:00-23:59（關機時間段通過開機時間段算出,一天24小時減去開機時間則為關機時間段）C=118c->s,發(fā)放機應答m=R0：設置OK1：設置錯誤C=119s->c,平臺向發(fā)放機發(fā)送語音提示文本m=R注意：發(fā)放機根據(jù)接收到的平臺指令提示語音。消息內容如：0：“請取貨”1：“領取失敗，請查看手機提示”2：“請在手機上選擇領取藥具”C=120c->s，發(fā)放機應答m=R0：語音OK1：語音異常C=121s->c，平臺向發(fā)放機發(fā)送屏顯消息和語音提示文本m=R注意：發(fā)放機根據(jù)接收到的平臺指令在顯示屏顯示文本消息內容且進行語音提示。消息內容如：0：“請取貨”1：“領取失敗，請查看手機提示”2：“請在手機上選擇領取藥具”C=122c->s，設備向平臺發(fā)送門打開和門關閉指令m=R0：門打開1：門關閉C=123c->s，設備向平臺發(fā)送心跳檢測指令m=RRC=124s->c,平臺向設備發(fā)送心跳反饋指令m=RRC=125s->c,平臺向發(fā)放機發(fā)送二維碼失效處理指令m=QRCODEQRCODE：二維碼路徑注意：顯示屏顯示信息及語音提示信息為：“領取失敗，請查看手機提示”，同時更新二維碼7.4指令示例消息字段示例C=115{"c":"115","f":"GD001","t":"861265732345497","m":"18:00-24:00","s":"EDAF8EB5D1DE1E5AF233EEF20BDDAB11","e":"MD5加密生成"}C=116{"c":"116","f":"861265732345497","t":"GD001","m":"0","s":"324FB128D9024BC9B656E492ECF0A1D6","e":"MD5加密生成"}C=117{"c":"117","f":"GD001","t":"861265732345497","m":"6:00-24:00","s":"EDAF8EB5D1DE1E5AF233EEF20BDDAB11","e":"MD5加密生成"}C=118{"c":"118","f":"861265732345497","t":"GD001","m":"0","s":"324FB128D9024BC9B656E492ECF0A1D6","e":"MD5加密生成"}7.5指令執(zhí)行邏輯1、設備注冊：機器通電設備向服務器發(fā)送C108指令，指令正確，服務器返回C106指令及C113指令屏顯指令(“請微信掃碼領取藥具”)。機器[連接狀態(tài)/運行狀態(tài)]異常（[離線/故障]，LINKSTSTUS=1/RUNSTSTUS=1）則發(fā)送C113屏顯指令，屏顯故障信息。2、掃碼領?。河脩魭呙柙O備顯示二維碼，二維碼正常，服務器向設備發(fā)送C113（請在手機上領取藥具）及C119（2）指令，手機頁面進入藥具領取選擇頁面，用戶選擇需要領取的藥具，點擊領取，服務器向設備發(fā)送C106指令及藥具出貨C2指令，進入出貨等待頁面。設備向服務器發(fā)送C3指令。二維碼失效：服務器向設備發(fā)送C106指令及C113（領取失敗，請查看手機）和C119（1）指令。出貨成功：服務器向設備發(fā)送C113(請取貨)指令及C119（0）。5秒后在推送C113（請微信掃碼領取藥具）指令重置屏顯信息(請微信掃碼領取藥具)。出貨失?。悍掌飨蛟O備發(fā)送C113(領取失敗請查看手機提示)指令及C119（1）。5秒后在推送C113（請微信掃碼領取藥具）指令重置屏顯信息(請微信掃碼領取藥具)。備注：二維碼正常--設備通電