5.Develop API for communication (method 2: Cloud to Cloud)
Important declare:
Through cloud to cloud method, the data on partner cloud will be pushed to SUNMI cloud, and then pushed to the printer by SUNMI cloud. SUNMI will adopt a secure method to protect the data privacy of partners. If you want to better protect your data privacy, method 1 (device to cloud) is recommended, because data will be obtained from partner cloud directly.
Parameter specification:
Each request contains common parameters and private parameters. Please refer to the following corresponding specification for details.
Parameters will be passed in a form of key-value, and “application/x-www-form-urlencoded” will be added on the request header.
Only private parameters and return results are listed for the following interfaces. For other information, please see the specification on common request parameters.
The returned results are all json format data.
Specification on common request parameters (the parameters must be passed in all requests):
Request parameter
Type
Specification
sign
string
Signature. Refer to the content below 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. It can be obtained when subscribing for SUNMI cloud printer channel service
msn
string
Device SN
timestamp
string
Unix timestamp (second)
Specification on common return parameters:
Return parameter
Type
Specification
code
int
Return code. Please see common error code list
data
indefinite
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, an 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.
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 is the only condition for grouping devices under the merchant account and is used when querying the status list of devices in the store. Please 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
Value
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 MD
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. Default to 300 seconds delay of current time
cycle
int
Voice playback times: 0 – do not remind again; 1 – play once; 3 – play 3 times; 999 – loop
delay
int
The time interval (second) between voice messages, and the default is 2s
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
pushId
string
Push unique ID. Different ID of each print order means different print content
voiceCnt
int
Voice playback times: 0 – do not remind; 1 – play once; 3 – play 3 times; 999 – loop
voice
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
voiceUrl
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)
orderCnt
int
The number of orders to be printed (1 by default)
orderType
int
The type of order printed: 1. New order; 2. Cancelled order; 3. Order reminder; 4. Refund; 5. Others
orderData
string
The order content to be printed. 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
Example on content conversion:
//PHP code example:
$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
$orderData = bin2hex(strToUtf8($str)); //$orderData 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);
}
}
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 parameter:
Parameter
Type
Specification
pushId
string
The order ID which is need to be queried.To avoid server pressure, do not call this interface frequently.The recommended interval for querying the same ID is more than 1 minute.
//Order printing not completed
{
"code": "10000",
"data": {
"status": "0", //1-printing completed,0-printing not completed，-1-printing abnormal
"unixTime": null //the Unix Time of printing completed
},
"msg" : ""
}
Specification on return parameters (success):
Parameter
Type
Specification
data
Object
If no order which can to be queried, null will be returned.Return print information if query successful： “status”1-printing completed,0-printing not completed，-1-printing abnormal. “unixTime”The Unix time will be returned if print successful”、Null will returned if print not successful
