数据云打印机对接说明

2、数据云打印机在门店的绑定过程

2.1、打印机连接POS主机

  1. 将打印机配套的USB线连接到POS主机;
  2. 连接电源线,打开打印机电源,等待打印机启动完成;

2.2、下载商米助手并注册

  1. 手机下载【商米助手】(或在应用商店下载):https://sj.qq.com/myapp/detail.htm?apkName=com.sunmi.assistant
  2. 安装【商米助手】,手机号注册门店管理账号;
  3. 为了让打印机能够连接到网络,需要将打印机与门店进行绑定。

2.3、使用商米助手绑定打印机

1. 安装【商米助手】APP,注册并登录,进入【设备】管理页

2. 点击【+】添加设备,选择【云打印机】

3. 根据提示,长按打印机底部的配对按钮3秒,听到提示音后松开按钮。点击【开始设置】

4. 此时会开始蓝牙搜索打印机,选择搜索到的云打印机(打印机名称以CloudPrint开头,后面四位数字是打印机SN号码的最后四位)

5. 选择需要打印机连接哪个Wi-Fi进行联网(打印机仅支持2.4GHz网络,不支持5GHz频段),在弹窗中输入wifi密码。等待打印机提示连接网络完成。

6. 完成添加,设备列表显示刚添加的云打印机

2.4、使用数字店铺查看采集到的打印数据

1. 完成设备配置后,使用打印机进行打印(USB打印或者蓝牙打印),打印数据将被自动采集上报。

注意:因为云端解析采用了AI自动算法,务必确保打印的收银小票是真实的票据格式小票,否则小票识别率将非常低。

2. 此时可以使用与【商米助手】APP相同的账号登录【商米数字店铺】(https://store.sunmi.com),选择【交易>小票列表】,点击【查看订单详情】可以看到上报的数据。

小票数据的解析基于AI训练,如果没能正确识别,请联系商米支持人员进行处理。

数据云打印机对接说明

1、了解一下对接流程

警告语:

本商用打印设备具备向您( 商户) 所在的商场运营方或物业管理方( 统称“管理方”) 上传打印数据的功能。管理方已承诺就上传数据获取您的授权。若您的打印数据包含消费者的个人信息,您应确保已获得消费者授权。若您已向管理方授权并获得消费者的相应授权,则您可以打开包装并使用本设备;若您未向管理方授权或未取得消费者的相应授权,则应停止使用本设备。

【小票数据流转路径(图中橙色路径)】:

  1. 收银机将打印指令发送至打印机,打印机就会打印出票据。
  2. 打印票据的同时,打印机会将采集到的小票信息原始数据上传到商米云端服务器。
  3. 商米云端对原始数据进行解析以后,依据合作伙伴提供的回调URL地址,将解析后的小票格式化数据推送给合作伙伴云端接口。
  4. 合作伙伴接收到格式化数据以后就可以进行存储和分析了。

【对接开发步骤】:

  1. 手机下载安装【商米助手】APP,并注册开通门店,然后绑定数据云打印机;
  2. 利用POS主机的USB接口或者蓝牙接口,给打印机发送打印数据,打印机将打印出收银小票;(注意:因为云端解析采用了AI自动算法,务必确保打印的收银小票是真实的票据格式小票,否则小票识别率将非常低。)打印机windows驱动下载
  3. 登录【商米数字店铺】平台,在【小票列表】中检查是否收到刚刚打印的数据记录;
  4. 注册【合作伙伴平台】账号,联系商米获取开发者app_id;
  5. 在合作伙伴云端开发门店绑定功能,并将打印机执行绑定门店动作;
  6. 在合作伙伴云端开发数据接收接口,将开发完成的接口【回调URL地址】和需要的【消息类型event】告诉商米对接技术人员;
  7. 此时已经完成基础对接,打印机打印票据的时候,就会同步将数据推送到合作伙伴云端。

云打印机对接说明

5. 开发对接API接口(方案二:直推方式)

特别声明:

直推方式合作伙伴云的数据会推送到商米云,再由商米云推送给打印机。商米将采用安全的方法保护合作伙伴的数据隐私。如果希望让数据隐私得到更好的保护,可以采用“方法一:回调方式”让打印机从合作伙伴云直接获取数据,避免数据中转。

参数说明:

  1. 每个请求的参数包含两部分:公共参数和私有参数,详细请看以下对应说明。
  2. 传参方式为key-value方式,请求头加上“application/x-www-form-urlencoded”。
  3. 以下每个接口只列出私有参数和返回结果,其他请看请求和公共参数说明。
  4. 返回结果皆为json格式数据。

请求公共参数说明(所有请求都必须传递的参数):

请求参数名类型说明
signstring签名,参考下面签名生成方式。注意:签名sign必须全部32位大写MD5
app_idstring商米提供的app_id,申请开通通道时获得
msnstring设备SN号
timestampstringUnix时间戳(秒)

返回公共参数说明:

返回参数名类型说明
codeint返回码,参见常见错误码列表
data不指定数据类型和内容详见私有返回参数data,如果有错误,返回null
msgstring结果提示信息,如果有错误返回错误信息描述

公共请求参数sign生成说明:

签名算法:MD5

签名生成方式举例(此处以打印机绑定接口为例):
app_id:sm5b9b4daef3463 
msn:NT1234DF23456 
timestamp:1589277365 
shop_id:1

步骤1:以“key=value”格式,按参数名称ASCII字典顺序排序:
stringA=“app_id=sm5b9b4daef3463&msn=NT1234DF23456&shop_id=1&timestamp=1589277365”;

步骤2:拼接的关键app_key,假定app_key是“dd3ac24736589ae17d333e362859bf4c”,那么
stringB=“app_id=sm5b9b4daef3463&msn=NT1234DF23456&shop_id=1&timestamp=1589277365dd3ac24736589ae17d333e362859bf4c”

步骤3:对stringB进行MD5加密得到最终签名sign,即sign=MD5(stringB)。即sign=“946720303FEFF4516626A4431D2753CA”

以上参数值仅作为签名生成方式举例所用,实际签名生成所需参数值以实际情况为准

基于以上签名生成方式,其中私密参数app_id和app_Key,由商米科技统一分配。注意:签名sign必须全部32位大写MD5

常见错误码说明:

错误码说明
10000接口调用成功
20000服务不可用
20001授权失败
40001缺少所需参数
40002非法参数

此上为全局常见错误码说明,后续会继续补充。除公共错误码以外,具体业务错误码参见具体业务接口内容。

推送接口URL地址:

请求URL地址:https://openapi.sunmi.com/

1)打印机绑定接口

接口名:

  • /v1/printer/printerAdd

请求方式:

  • POST

公共参数:

参数名类型说明
signstring签名,参考上面签名生成方式。注意:签名sign必须全部32位大写MD5
app_idstring商米提供的app_id
msnstring设备SN号
timestampstringUnix时间戳(秒)

私有参数:

参数名类型说明
shop_idstring合作伙伴名下的商户Id,最大长度小于32位字符。
此处的shop_id是相对于合作伙伴APP中店铺管理而言的店铺id号,并非商米的店铺。因为打印机一般需要绑定到店铺下,才能建立店铺和设备的对应关系,设备查询时也要依据店铺来查询设备的联网状态。这个shop_id由合作伙伴进行管理,传什么值商米就保存什么值。
shop_id是对合作伙伴名下设备进行分组管理的唯一条件,查询店铺设备状态列表时使用。若无店铺需关联可传””,那么设备状态列表结果集将只返回shop_id为空的设备,不会返回shop_id不为空的设备。

成功返回示例:

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

成功返回参数说明:

参数名类型说明
datastring包含成功和失败信息

失败返回示例:

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

失败错误码说明:

错误码说明
60001超出时间范围请求无效
60002sn号不存在
60003不属于该渠道设备
60004绑定失败
60007绑定异常
60008设备已绑定,请检查是否已在商米助手绑定过,需在商米助手中解绑后才能执行本渠道绑定
60012 shop_id超长,请限制在32位字符以内

2)打印机解绑接口

接口名:

  • /v1/printer/printerUnBind

请求方式:

  • POST

公共参数:

参数名类型说明
signstring签名,参考上面签名生成方式。注意:签名sign必须全部32位大写MD5
app_idstring商米提供的app_id
msnstring设备SN号
timestampstringUnix时间戳(秒)

私有参数:

参数名类型说明
shop_idstring合作伙伴名下的商户Id ,需要与绑定时一致

shop_id必传,否则无法将该打印机从该店铺下解绑

成功返回示例:

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

成功返回参数说明:

参数名类型说明
datastring包含成功和失败信息

失败返回示例:

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

失败错误码说明:

错误码说明
60001超出时间范围请求无效
60002sn号不存在
60003不属于该渠道设备
60005解绑失败

3)查询店铺下已绑定设备状态

接口名:

  • /v1/machine/queryBindMachine

请求方式:

  • POST

公共参数:

参数名类型说明
signstring签名,参考上面签名生成方式。注意:签名sign必须全部32位大写MD5
app_idstring商米提供的app_id
timestampstringUnix时间戳(秒)

私有参数:

参数名类型说明
shop_idstring合作伙伴商户Id ,需要与绑定时一致

成功返回示例:

{
    "code": "10000",
    "data": [
        {
            "is_online": "1",//1表示设备在线,0表示离线
            "msn": "N302D94D40068"//设备SN号
        }
    ],
    "msg": ""
}

成功返回参数说明:

参数名类型说明
dataObjectmsn:设备sn号;is_online:设备是否在线 1-在线 0-不在线

失败返回示例:

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

失败错误码说明:

错误码说明
60001超出时间范围请求无效
60002sn号不存在
60003不属于该渠道设备
60006商户Id不存在

4)语音内容推送

接口名:

  • /v1/printer/pushVoice

请求方式:

  • POST

公共参数:

参数名类型说明
signstring签名,参考上面签名生成方式。注意:签名sign必须全部32位大写MD5
app_idstring商米提供的app_id
msnstring设备SN号
timestampstringUnix时间戳(秒)

私有参数:

参数名类型说明
call_contentstring 需要语音播报的字符串,与call_url只能使用一个,无数据时传””
call_url string 需要设备播放的语音文件下载路径,与call_content只能使用一个,无数据时传””。文件格式只能为MP3或WAV格式(MP3要求16bit单声道8000Hz采样率。WAV要求16bit单声道8000Hz采样率)
expTimestampint语音消息有效截止Unix系统时间戳,一般为当前时间延后300s
cycleint语音播放次数,0 不提示,1 播报1次,3 播报3次,999 循环播放
delayint播报中间间隔时间,单位秒,一般间隔2秒

成功返回示例:

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

成功返回参数说明:

参数名类型说明
datastring包含成功和失败信息

失败返回示例:

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

失败错误码说明:

错误码说明
60001超出时间范围请求无效
60002sn号不存在
60003不属于该渠道设备

5)推送订单详情

接口名:

  • /v1/printer/pushContent

请求方式:

  • POST

公共参数:

参数名类型说明
signstring签名,参考上面签名生成方式。注意:签名sign必须全部32位大写MD5
app_idstring商米提供的app_id
msnstring设备SN号
timestampstringUnix时间戳(秒)

私有参数:

参数名类型说明
pushIdstring推送唯一ID,每张打印票据ID不同就认为是不同的打印内容
voiceCntint票据语音播放次数,0 不提示,1 播报1次,3 播报3次,999 循环播放
voicestring 需要语音播报的字符串,voice与voiceUrl内容只能使用一个,无数据时传””
voiceUrl string 需要设备播放的语音文件http下载路径,voice与voiceUrl内容只能使用一个,无数据时传””。文件格式只能为MP3或WAV格式(MP3要求16bit单声道8000Hz采样率。WAV要求16bit单声道8000Hz采样率)
orderCntint打印票据张数
orderTypeint打印票据类型,1 新订单,2 取消订单,3 催单,4 退单,5 其它
orderDatastring打印票据内容。所有文本内容采用UTF8编码,再转换成十六进制格式传输。在内容中可以直接使用ESC/POS指令集控制打印,以获得所需的票据排版格式。

内容转换示例:

//PHP代码示例:  

$str = chr(27). chr(33). chr(48)."南国超市".chr(27). chr(33). chr(0). chr(0x0A);  //chr(27). chr(33). chr(48)是ESC/POS指令的字体效果倍高宽;chr(27). chr(33). chr(0)是ESC/POS指令的字体效果标准大小;0A是换行
$str = $str."台号:01       工号:01".chr(0x0A);
$str = $str."时间:12:45:28".chr(0x0A);
$str = $str."单号:00554789713585".chr(0x0A);
$str = $str."商品名称     单价*数量       金额".chr(0x0A);
$str = $str."--------------------------------".chr(0x0A);
$str = $str."百事利精装糖果  7.00*1      7.00".chr(0x0A);
$str = $str."旺旺雪饼        8.00*1      8.00".chr(0x0A);
$str = $str."可口可乐        2.50*1      2.50".chr(0x0A);
$str = $str."喜之朗果冻     10.00*1     10.00".chr(0x0A);
$str = $str."巧克力饼干     10.00*1     10.00".chr(0x0A);
$str = $str."--------------------------------".chr(0x0A);
$str = $str."总件数:5          总计RMB: 27.00".chr(0x0A);
$str = $str.chr(0x0A);
$str = $str.chr(27). chr(33). chr(16). "      谢谢惠顾欢迎下次光临". chr(27). chr(33). chr(0). chr(0x0A);//显示效果是字体倍高;0A是换行

$orderData = bin2hex(strToUtf8($str));  //$orderData为:1b2130e58d97e59bbde8b685e5b8821b21000ae58fb0e58fb73a303120202020202020e5b7a5e58fb73a30310ae697b6e997b43a31323a34353a32380ae58d95e58fb73a30303535343738393731333538350ae59586e59381e5908de7a7b020202020202020202020202020e58d95e4bbb72ae695b0e9878f202020202020e98791e9a29d0a2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d0ae799bee4ba8be588a9e7b2bee8a385e7b396e69e9c2020202020202020372e30302a312020202020202020372e30300ae697bae697bae99baae9a5bc2020202020202020202020202020382e30302a312020202020202020382e30300ae58fafe58fa3e58fafe4b9902020202020202020202020202020322e35302a312020202020202020322e35300ae5969ce4b98be69c97e69e9ce586bb202020202020202020202031302e30302a312020202020202031302e30300ae5b7a7e5858be58a9be9a5bce5b9b2202020202020202020202031302e30302a312020202020202031302e30300a2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d0ae680bbe4bbb6e695b02020342e303020202020202020202020e680bbe8aea1524d4220202020202032372e30300a0a1b2110202020202020e8b0a2e8b0a2e683a0e9a1bee6aca2e8bf8ee4b88be6aca1e58589e4b8b41b21000a

//该方法判断字符串内容是否是UTF8编码,如果是直接返回,如果不是则将字符串转换为UTF8编码
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);
    }
}

成功返回示例:

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

成功返回参数说明:

参数名类型说明
datastring包含成功和失败信息

失败返回示例:

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

失败错误码说明:

错误码说明
60001超出时间范围请求无效
60002sn号不存在
60003不属于该渠道设备
60009推送唯一ID不能为空
60010推送唯一ID已存在
60011推送失败

6)清空待打印队列

接口名:

  • /v1/printer/clearPrintList

请求方式:

  • POST

公共参数:

参数名类型说明
signstring签名,参考上面签名生成方式。注意:签名sign必须全部32位大写MD5
app_idstring商米提供的app_id
msnstring设备SN号
timestampstringUnix时间戳(秒)

私有参数:

参数名类型说明

成功返回示例:

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

成功返回参数说明:

参数名类型说明
dataObject删除完成返回成功单数count;没有需要删除的订单时返回null

失败返回示例:

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

失败错误码说明:

错误码说明
60001超出时间范围请求无效
60002sn号不存在
60003不属于该渠道设备

7)查询订单打印状态

接口名:

  • /v1/printer/getPrintStatus

请求方式:

  • POST

公共参数:

参数名类型说明
signstring签名,参考上面签名生成方式。注意:签名sign必须全部32位大写MD5
app_idstring商米提供的app_id
msnstring设备SN号
timestampstringUnix时间戳(秒)

私有参数:

参数名类型说明
pushIdstring查询打印票据ID。为避免造成服务器压力,请勿频繁调用此接口,相同ID查询建议间隔1分钟以上

成功返回示例:

//订单打印完成
{
    "code": "10000",
    "data": {
        "msn"    : "NT210XXXXXXXX", 
        "isPrint": "1", //1表示已打印,0表示未打印,-1表示打印异常
        "unixTime": "1577425708" //打印成功的Unix时间
    },
    "msg" : ""
}
//订单未打印
{
    "code": "10000",
    "data": {
        "status": "0", //1表示已打印,0表示未打印,-1表示打印异常
        "unixTime":  null //打印成功的Unix时间
    },
    "msg" : ""
}

成功返回参数说明:

参数名类型说明
dataObject无可查询数据时返回null;查询成功返回打印信息:
“status”1 订单打印成功、0 订单打印失败、-1 订单打印异常;
“unixTime”已打印成功返回打印Unix时间”、未打印或异常的返回null

失败返回示例:

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

失败错误码说明:

错误码说明
60001超出时间范围请求无效
60002sn号不存在
60003不属于该渠道设备

商米云打印机合作伙伴对接说明

特别声明: 商米云打印机对接通道为更好的保护合作伙伴的数据隐私,又能实现完整的订单打印过程,特订立以下对接规范,并需要商米与合作伙伴双方共同努力才能实现打印通道业务。

1、了解一下对接流程

2、注册一个合作伙伴账号

3、下载配网SDK

4、开发对接API接口(方案一:回调方式)

5、开发对接API接口(方案二:直推方式)

6、打印机常用ESC/POS指令集

7、需要了解的其他FAQ