4.Develop API for communication (method 1: Device to Cloud)
Important declare:
For better protection of partners’ data privacy, also SUNMI cloud printer can realize the complete order printing functions. It is need what our partners work hard together with SUNMI to achieve. The document as below define the interfaces (which are divided into two parts) to realize the communication of cloud printers. One API which is provided by SUNMI is order to bind devices and push messages. Another API which is provided by partners is open to the printer for completing printing function.
Parameter specification:
Each request contains common parameters and private parameters. For details, please see corresponding specifications below.
Parameters will be passed in a form of key-value, and “application/x-www-form-urlencoded” will be added to the request header.
Only private parameters and return results are listed in the following interfaces. For other information, please see the specifications of common request parameters.
The data format of return results is json.
Specification on common request parameters (the parameters that must be passed for all requests):
Request parameter
Type
Specification
sign
string
Signature. Please refer to the following signature how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_id
string
The app_id which is provided by SUNMI. It can be obtained when subscribing for SUNMI cloud printer channel service
msn
string
Device SN
timestamp
string
Unix timestamp (second)
Specification on returning common parameters:
Return parameter
Type
Specification
code
int
Return code. Please see common error code list.
data
all
Please refer to private return parameter data for data type and content. If there is an error, null will be returned.
msg
string
Information which indicates the result. If there is an error, the error description will be returned.
Specification on generating a common request parameter:
Signature algorithm: MD5
Example on how a signature is generated (It supposes that the required parameters are as below): app_id:sm5b9b4daef3463 msn:NT1234DF23456 timestamp:1589277365 shop_id:1
Step 1: place the parameters per their orders in ASCII in a form of “key=value”: stringA=”app_id=sm5b9b4daef3463&msn=NT1234DF23456&shop_id=1×tamp=1589277365″
Step2: supposing the app_key, the key part “dd3ac24736589ae17d333e362859bf4c” to join a character string, is: stringB=”app_id=sm5b9b4daef3463&msn=NT1234DF23456&shop_id=1×tamp=1589277365dd3ac24736589ae17d333e362859bf4c”
Step 3: encrypt stringB with MD5 to generate the final signature sign (sign=MD5(stringB), that is sign=”946720303FEFF4516626A4431D2753CA”
Among the steps above, the private parameters app_id and app_Key will be provided by SUNMI. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
Specification on common error codes:
Error code
Specification
10000
The interface is called successfully
20000
Unavailable service
20001
Failed to authorize
40001
Required parameter is missing
40002
Invalid parameter
The table above is a specification on global common error codes, and follow-up information will be added to the table. In addition to the common error codes, please refer to specific business error codes in content related to specific business interfaces.
4.1 SUNMI cloud API
Due to protect partner data privacy, SUNMI cloud does not directly obtain the print data, but adopts the message passing method, and the printer directly connects to the partner cloud to pull the required data for printing. The following interfaces are provided by SUNMI to realize device binding, order notification, voice transmission and other functions.
Signature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_id
string
The app_id which is provided by SUNMI
msn
string
Device SN
timestamp
string
Unix timestamp (second)
Private parameters:
Parameter
Type
Specification
shop_id
string
The partner’s shop ID
Shop_id is the only condition for grouping devices under the merchant account and is used when querying the status list of devices in the store. You can pass “” if this function is not needed, and null will be returned for the store device status list result set.
The device has been bound already. Please check whether you have bound the device in SUNMI Assistant, if so, please unbind the device in SUNMI Assistant before binding it to this channel
60012
shop_id to long. MAX 32 character.
2)Interface for unbinding a printer
Interface name:
/v1/printer/printerUnBind
Request method:
POST
Common parameters:
Parameter
Type
Specification
sign
string
Signature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_id
string
The app_id which is provided by SUNMI
msn
string
Device SN
timestamp
string
Unix timestamp (second)
Private parameter:
Parameter
Type
Specification
shop_id
string
The partner’s shop ID
Shop_id must be passed, otherwise the printer cannot be unbound from the shop
3)Query the status of devices which has been bound to the shop
Interface name:
/v1/machine/queryBindMachine
Request method:
POST
Common parameters:
Parameter
Type
Specification
sign
string
Signature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
Signature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
Signature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_id
string
The app_id which is provided by SUNMI
msn
string
Device SN
timestamp
string
Unix timestamp (second)
Private parameters
Parameter
Type
Specification
call_content
string
The character string which is need to voice playback. You can only choose one between call_content with call_url. Please pass “” if there is no data
call_url
string
The address of the voice file to be downloaded and played by the device. You can only choose one between call_content with call_url. Please pass “” if there is no data. The available formats are MP3 (16bit mono, 8000Hz) and WAV (16bit mono, 8000Hz)
expTimestamp
int
Unix timestamp which indicates when the voice message will expire
cycle
int
Voice playback times: 0 – do not remind; 1 – play once; 3 – play 3 times; 999 – loop
delay
int
The time interval (second) between voice playback, and the default is 2s
Due to protect partner data privacy, SUNMI cloud does not directly obtain the print data, but adopts the message passing method, and the printer directly connects to the partner cloud to pull the required data for printing. The following interfaces which is provided by partner cloud is for the printer to obtain order data and print.
Request URL address: to make sure that the printer can connect directly to the partner cloud API for completing print orders, an URL address which can be called should be provided to SUNMI cloud in advance.
Signature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
Return five order ID sets in the database. If the request fails, the data will be null
msg
If the request fails, error information will be returned in the msg, If the request successful, “” will be returned in the msg
Note: To make sure that the printer won’t miss any order, the order ID list returns a list of up to 5 order ID sets at a time in chronological order. The printer will print all the orders in turn and then request the interface to get the list of order IDs to be printed again until the interface returns empty.
2)Get order details
Interface name:
printTicket/getPrintTicketInfo
Request method:
GET
Parameters:
Parameter
Type
Specification
sign
string
Signature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_id
string
The app_id which is provided by SUNMI
msn
string
Device SN
timeStamp
string
Unix timestamp (second)
orderId
string
Order ID
Example on return result (json):
{
"code":1,
"data":{
"voiceCnt":1, //Voice playback times, 0 0 – do not remind; 1 – play once; 3 – play 3 times; 999 – loop
"voice":"Voice content", //Voice playback content. Only one of voice and voiceUrl can be used. Please pass "" if there is no data
"voiceUrl":"http://xxx.xxx.xxx/playaudio.MP3", //The address for downloading the voice playback file. Only one of voice and voiceUrl can be used. Please pass “" if there is no data. Voice is the text contains the message to be played. VoiceUrl is the voice file to be played. The available file formats are MP3 (16bit mono, 8000Hz) and WAV (16bit mono, 8000Hz)
"orderCnt":2, //The number of orders to be printed
"data":"1B21306D4B8BD5310A",//Use ESCPOS font (in double height and width) to print the content in “test 1", and there is a return command at the end of it
},
"msg":""
}
Specification on data: The content to be printed is transmitted in hexadecimal format and UTF8 encoding is adopted for all text contents. ESC/POS command set can be directly used in the contents to control printing, also for layout and format.
//PHP Sample code
$str = chr(27)．chr(33)．chr(48)．"Supermarket"．chr(27)．chr(33)．chr(0)．chr(0x0A); //chr(27)．chr(33)．chr(48)are font effect (double height and width) in ESC/POS command; chr(27)．chr(33)．chr(0)are the standard font size in ESC/POS command; 0A is carriage return
$str = $str．"Table:01 Employee ID:01"．chr(0x0A);
$str = $str．"Time:12:45:28"．chr(0x0A);
$str = $str．"Order No.:00554789713585"．chr(0x0A);
$str = $str．"Item Price*Num Amount"．chr(0x0A);
$str = $str．"--------------------------------"．chr(0x0A);
$str = $str．"Item1 7.00*1 7.00"．chr(0x0A);
$str = $str．"Item2 8.00*1 8.00"．chr(0x0A);
$str = $str．"Item3 2.50*1 2.50"．chr(0x0A);
$str = $str．"Item4 10.00*1 10.00"．chr(0x0A);
$str = $str．"Item5 10.00*1 10.00"．chr(0x0A);
$str = $str．"--------------------------------"．chr(0x0A);
$str = $str．"Total items:5 Total RMB: 27.00"．chr(0x0A);
$str = $str．chr(0x0A);
$str = $str．chr(27)．chr(33)．chr(16)．" Wish you a good day"．chr(27)．chr(33)．chr(0)．chr(0x0A);//The font shown is in double height and width; 0A is carriage return
$data = bin2hex(strToUtf8($str)); //$data is:1b2130e58d97e59bbde8b685e5b8821b21000ae58fb0e58fb73a303120202020202020e5b7a5e58fb73a30310ae697b6e997b43a31323a34353a32380ae58d95e58fb73a30303535343738393731333538350ae59586e59381e5908de7a7b020202020202020202020202020e58d95e4bbb72ae695b0e9878f202020202020e98791e9a29d0a2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d0ae799bee4ba8be588a9e7b2bee8a385e7b396e69e9c2020202020202020372e30302a312020202020202020372e30300ae697bae697bae99baae9a5bc2020202020202020202020202020382e30302a312020202020202020382e30300ae58fafe58fa3e58fafe4b9902020202020202020202020202020322e35302a312020202020202020322e35300ae5969ce4b98be69c97e69e9ce586bb202020202020202020202031302e30302a312020202020202031302e30300ae5b7a7e5858be58a9be9a5bce5b9b2202020202020202020202031302e30302a312020202020202031302e30300a2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d0ae680bbe4bbb6e695b02020342e303020202020202020202020e680bbe8aea1524d4220202020202032372e30300a0a1b2110202020202020e8b0a2e8b0a2e683a0e9a1bee6aca2e8bf8ee4b88be6aca1e58589e4b8b41b21000a
//The method can judge whether the character string content is UTF8 encoding. if so, it will be returned directly. Otherwise the character string will be turned into UTF8 encoding
function strToUtf8($str){
$encode = mb_detect_encoding($str, array("ASCII",'UTF-8',"GB2312","GBK",'BIG5'));
if($encode == 'UTF-8'){
return $str;
}else{
return mb_convert_encoding($str, 'UTF-8', $encode);
}
}
Return parameters:
Return parameter
Specification
code
1 request successful. -1 request failed
data
Return order content. If the request fails, the data will be null. If the request successful, the data will include voiceCnt (voice playback times), voice (voice playback content), orderCnt (print order number) and data (print order data) will be returned
msg
If the request fails, error information will be returned in the msg, otherwise “” will be returned in the msg
For the cloud printer is able to reprint an order, the interface should allow orders marked as printed and allow the printer to request order details per order ID to reprint an order.
3)Update order status
Interface name:
printTicket/updatePrintTicketStatus
Request method:
GET
Parameters:
Parameter
Type
Specification
sign
string
Signature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_id
string
The app_id which is provided by SUNMI
msn
string
Device SN
timeStamp
string
Unix timestamp (second)
orderId
string
Order ID
status
int
Status: 1 – print order successful; 0 – print order failed; -1 – order json format error; -2 – the data field is empty
Example on return result (json):
{
"code":1,
"data":"success",
"msg":""
}
Return parameters:
Parameter
Specification
code
1 request successful. -1 request failed
data
“success” will be returned if it is successful; “fail” will be returned if it failed
msg
If the request fails, error information will be returned in the msg, otherwise “” will be returned in the msg
