Cloud Printer Product R&D Instruction

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:

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

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

Request parameterTypeSpecification
signstringSignature. 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_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 common return parameters:

Return parameterTypeSpecification
codeintReturn code. Please see common error code list
dataindefinitePlease 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, 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&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.

URL address of the interface for pushing:

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

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 parameter:

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. Please 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
60007Binding 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
60012 shop_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:

ParameterValueSpecification
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)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 MD
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. Default to 300 seconds delay of current time
cycleintVoice playback times: 0 – do not remind again; 1 – play once; 3 – play 3 times; 999 – loop
delayintThe time interval (second) between voice messages, 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

5)Push order details

Interface name:

  • /v1/printer/pushContent

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
pushIdstringPush unique ID. Different ID of each print order means different print content
voiceCntintVoice playback times: 0 – do not remind; 1 – play once; 3 – play 3 times; 999 – loop
voicestringThe 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
voiceUrlstringThe 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)
orderCntintThe number of orders to be printed (1 by default)
orderTypeintThe type of order printed: 1. New order; 2. Cancelled order; 3. Order reminder; 4. Refund; 5. Others
orderDatastringThe 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);
    }
}

Example on return result (success):

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

Specification on the return parameter (success):

ParameterTypeSpecification
datastringContains success or failure information

Example of 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
60009The unique ID which is pushed cannot be empty
60010The unique ID already exists
60011Failed to push

6)Clear the print queue

Interface name:

  • /v1/printer/clearPrintList

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
N/A

Example on return result (success):

{
    "code": "10000",
    "data":{
       "count":2
    },
    "msg" : ""
}

Specification on return parameters (success):

ParameterTypeSpecification
dataObjectThe order count which has been clear will be returned. If no order need to be cleared, null will be returned

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

7)Query the status of printing order

Interface name:

  • /v1/printer/getPrintStatus

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
pushIdstringThe 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.

Example on return result (success):

//Order printing completed
{
    "code": "10000",
    "data": {
        "msn"    : "NT210XXXXXXXX", 
        "isPrint": "1", //1-printing completed, 0-printing not completed,-1-printing abnormal
        "unixTime": "1577425708" //the Time of printing completed
    },
    "msg" : ""
}
//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):

ParameterTypeSpecification
dataObjectIf 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

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