Cloud Printer Product R&D Instruction

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:

  1. Each request contains common parameters and private parameters. For details, please see corresponding specifications below.
  2. Parameters will be passed in a form of key-value, and “application/x-www-form-urlencoded” will be added to the request header.
  3. Only private parameters and return results are listed in the following interfaces. For other information, please see the specifications of common request parameters.
  4. The data format of return results is json.

Specification on common request parameters (the parameters that must be passed for all requests):

Request parameterTypeSpecification
signstringSignature. 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_idstringThe app_id which is provided by SUNMI. It can be obtained when subscribing for SUNMI cloud printer channel service
msnstringDevice SN
timestampstringUnix timestamp (second)

Specification on returning common parameters:

Return parameterTypeSpecification
codeintReturn code. Please see common error code list.
dataallPlease refer to private return parameter data for data type and content. If there is an error, null will be returned.
msgstringInformation 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&timestamp=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&timestamp=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 codeSpecification
10000The interface is called successfully
20000Unavailable service
20001Failed to authorize
40001Required parameter is missing
40002Invalid 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.

Request URL address: https://openapi.sunmi.com/

Document of developing API demo(PHP): https://file.cdn.sunmi.com/SUNMIDOCS/CloudPrinter-Request_PHP_DEMO.rar

1)Interface for binding a printer

Interface name:

  • /v1/printer/printerAdd

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. 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_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameters:

ParameterTypeSpecification
shop_idstringThe 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.

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on return parameters (success):

ParameterTypeSpecification
datastringContains success or failure information

Example on return result (failure):

{
  "code": "10000",
  "data": {
     "subCode": "60001",
     "subMessage": "",
  },
  "msg":  "string"
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel
60004Bind failed
60007Bind exception
60008The 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
60012shop_id to long. MAX 32 character.

2)Interface for unbinding a printer

Interface name:

  • /v1/printer/printerUnBind

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. 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_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameter:

ParameterTypeSpecification
shop_idstringThe partner’s shop ID

Shop_id must be passed, otherwise the printer cannot be unbound from the shop

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on return parameter (success):

ParameterTypeSpecification
datastringContains success or failure information

Example on return result (failure):

{
  "code": "10000",
  "data": {
     "subCode": "60001",
     "subMessage": "",
  },
  "msg":  "string"
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel
60005Unbind failed

3)Query the status of devices which has been bound to the shop

Interface name:

  • /v1/machine/queryBindMachine

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. 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_idstringThe app_id which is provided by SUNMI
timestampstringUnix timestamp (second)

Private parameter:

ParameterTypeSpecification
shop_idstringThe partner’s shop ID

Example on return result (success)

{
    "code": "10000",
    "data": [
        {
            "is_online": "1",//1 device online, 0 device offline
            "msn": "N302D94D40068"//Device SN
        }
    ],
    "msg": ""
}

Specification on return parameter (success):

ParameterTypeSpecification
dataObjectmsn: device SN; is online: whether the device is online. 1 – online; 2 – offline

Example on return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel
60006Invalid shop ID

4)Notification on new orders

Interface name:

  • /v1/printer/newOrderNotice

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. 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_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameters:

ParameterTypeSpecification
hasOrderint1-there is a new order
orderIdstringOrder ID

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on the return parameter (success):

ParameterTypeSpecification
subDatastringContains success or failure information

Example on return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel

5)Push Voice messages

Interface name:

  • /v1/printer/pushVoice

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. 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_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameters

ParameterTypeSpecification
call_contentstringThe 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_urlstringThe 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)
expTimestampintUnix timestamp which indicates when the voice message will expire
cycleintVoice playback times: 0 – do not remind; 1 – play once; 3 – play 3 times; 999 – loop
delayintThe time interval (second) between voice playback, and the default is 2s

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on the return parameter (success):

ParameterTypeSpecification
datastringContains success or failure information

Example on return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel

4.2 Partner 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 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.

Document of developing API demo(GO):https://file.cdn.sunmi.com/SUNMIDOCS/CloudPrinter_CallBack_GO_DEMO.zip

1)Get order list

Interface name:

  • printTicket/getPrintTicketOrderId

Request method:

  • GET

Parameters:

ParameterTypeSpecification
signstringSignature. 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_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timeStampstringUnix timestamp (second)

Example on return result (json):

{
    "code":1,
    "data":["id","id","id","id","id"],
    "msg":""
}

Return parameters:

ParameterSpecification
code1 request successful. -1 request failed
dataReturn five order ID sets in the database. If the request fails, the data will be null
msgIf 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:

ParameterTypeSpecification
signstringSignature. 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_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timeStampstringUnix timestamp (second)
orderIdstringOrder 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 parameterSpecification
code1 request successful. -1 request failed
dataReturn 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
msgIf 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:

ParameterTypeSpecification
signstringSignature. 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_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timeStampstringUnix timestamp (second)
orderIdstringOrder ID
statusintStatus: 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:

ParameterSpecification
code1 request successful. -1 request failed
data“success” will be returned if it is successful; “fail” will be returned if it failed
msgIf the request fails, error information will be returned in the msg, otherwise “” will be returned in the msg