商米外置打印机开发说明

4、打印机SDK接口API说明

1、连接指定打印机类型

方法voidconnectPrinter(Context context, SunmiPrinter sunmiPrinter,ConnectCallback callback)
说明指定打印机连接,局域网打印机请使用connectNetPrinter方法
输入context:上下文会话sunmiPrinter:指定打印机类型 SunmiPrinter.SunmiYKPriner 自助打印机 SunmiPrinter.SunmiNTPrinter NT210商米热敏打印机callback:连接打印机结果回调
返回

2、连接局域网打印机

方法voidconnectPrinter(Context context, String ip,ConnectCallback callback)
说明指定打印机连接,局域网打印机请使用connectNetPrinter方法
输入ontext:上下文会话ip:打印机的ip地址,可通过网络自检获取callback:连接打印机结果回调
返回

3、断开当前打印机

方法voiddisconnectPrinter(Context context)
说明结束并断开当前的打印机,将释放资源
输入context:上下文会话
返回

4、打印机连接状态

方法booleanisConnected()
说明当前API使用的打印机连接状态
输入
返回是否连接

5、指定打印机连接状态

方法booleanisConnected(SunmiPrinter sunmiPrinter)
说明sunmiPrinter:指定打印机的连接状态
输入
返回是否连接

6、获取打印机状态

方法int getPrinterStatus()
说明获取打印机运行状态当打印机处于事务模式时将不支持调用
输入
返回-1 打印机脱机或打印服务还未连接打印机0 打印机运行正常1 打印机开盖2 打印机缺纸3 打印机即将缺纸4 打印机过热

7、打印机初始化

方法voidprinterInit()
说明初始化打印机将使打印机设置状态恢复默认
输入
返回

8、打印机按行高走纸

方法void lineWrap(int n)
说明打印机走纸n行如果打印机打印缓冲区有数据,将输出数据并走纸n行如果行高被设置为0,则走纸距离为0
输入行数( 0 < n < 256 )
返回

9、打印机按像素走纸

方法void pixelWrap(int n)
说明打印机走纸n点行如果打印机打印缓冲区有数据,将输出数据并走纸n点行
输入像素点数( 0 < n < 256 )
返回

10、刷新缓冲区

方法void flush()
说明刷新打印缓冲区,当缓冲区有数据时将输出,如果没有数据将进纸一行
输入
返回

11、水平定位

方法void tab()
说明将打印位置移动到下一个水平定位点位置如果水平定位点超出打印区域则移动到行尾如果此时已经在行尾则会执行换行操作
输入
返回

12、设置横向水平定位点

方法void setHorizontalTab(int[ ] k )
说明将标记水平定位的位置,每个标记点位置由k[n]个ascii字符宽度指定,默认的水平定位点以8个ascii字符宽度为一个定位点
输入k 横向定位点数组k[n], 数组长度n最大可以是32,0 < k[n] < 256数组中必须是升序排列,否则将抛出异常k设置为null时将恢复默认定位点,默认位置为8个字符间隔
返回

13、打印文本内容

方法void printText(String text)
说明此方法会将输入文本转为对应字符集编码的十六进制字节流打印服务默认将文本内容转换为gb18030编码
输入text要打印的文本内容
返回

14、设置gb18030字符集编码

方法voidsetGb18030CharSet(booleanset)
说明打印机默认识别gb18030字符集,当设置关闭时,将不能识别gb18030字符集,会将其当成单字节处理
输入是否设置为GB18030字符集识别
返回

15、设置打印机映射页表

方法voidsetPageTable(int n)
说明此方法映射单字节码0x80-0xff在不同页上的内容,只有setGb18030CharSet(false)此方法才生效
输入n 对应页表
返回

16、设置国际字符集编码

方法voidsetInterCharSet(int n)
说明部分国家的ascii码中特殊字符有所区别,通过选择国家,可以打印对应国家编码的字符
输入n 对应国家
返回

17、设置字符右间距

方法voidsetCharRightSpace(int n)
说明设置字符的右间距空间,仅对ascii码有效,对其它字符无效
输入n 间距像素点
返回

18、设置汉字左右间距

方法voidsetHanziSpace(int m,int n)
说明设置汉字的左右间距
输入m 汉字左边间距n 汉字右边间距
返回

19、设置字体大小

方法voidsetFontZoom(int hori, int veri)
说明由于打印机硬字库限制,字体大小仅能倍数放大,本方法可以控制字体在横向和纵向方向的放大倍数
输入hori 、veri 的范围为1-8,表示在横向、纵向上字体的放大倍数,若设置在范围外将返回错误参数
返回

20、设置对齐方式

方法voidsetAlignMode(int type)
说明设置打印内容的对齐方式
输入0居左(默认)、1居中、2居右
返回

21、设置绝对位置

方法voidmoveAbsolutePos(int pos)
说明将打印距离移动到距离起始位置指定像素点
输入pos 距离起始位置像素点
返回

22、设置相对位置

方法voidmoveRelativePos(int pos)
说明将打印位置移动到相对当前位置指定像素点
输入pos 距离当前位置像素点
返回

23、启用或关闭下划线

方法voidenableUnderline(boolean enable)
说明启用或关闭字符下划线功能
输入enable 是否开启或关闭
返回

24、启用或关闭加粗

方法voidenableBold(booleanenable)
说明启用或关闭字符加粗功能
输入enable 是否开启或关闭
返回

25、启用或关闭重叠效果(一般同加粗)

方法voidenableDouble(boolean enable)
说明启用或关闭字符重叠效果
输入enable 是否开启或关闭
返回

26、设置打印机的行间距

方法voidsetLineSpace(int value)
说明设置打印机行间当行间距小于字符高度时将按字符高度
输入value 当设置小于0时将恢复默认行间距否则设置行间距为对应值
返回

27、设置打印机的左边距

方法voidsetLeftSpace(int value)
说明设置打印左边距大小像素点设置值过大可能导致打印区域小时
输入value 左边距大小
返回

28、设置打印宽度

方法voidsetPrintWidth(int width)
说明设置可打印区域大小像素点
输入width 可打印大小
返回

29、打印条形码

方法void printBarCode(String code, int type, int width, int height, int hriPos)
说明打印自定内容的条形码
输入code 条形码内容 (根据条码类型不同,条码内容需满足其格式)type 条形码类型 0:UPC-A; 1:UPC-E; 2:EAN13; 3:EAN8; 4:CODE39; 5:ITF; 6:CODABAR; 7:CODE93; 8:CODE128width 条形码宽度 2-6 像素 (若条码宽度设置过宽,整个条码超过纸张宽度将不会输出条码内容)height 条形码高度 1-255 像素hriPos HRI位置 0:不打印; 1:条形码上方; 2:条形码下方; 3:条形码上下方
返回

30、打印二维码

方法void printQrCode(String code, int modeSize, int errorlevel)
说明打印二维码
输入code 要打印的二维码内容,默认为utf-8字符集modeSize 二维码块大小 1-16 像素点errorlevel 二维码纠错等级 0-3 四个等级
返回

31、打印图片方法1

方法void printBitmap(Bitmap bitmap, int mode)
说明将bitmap图转成光栅位图方式打印此方法适合打印宽度在打印纸内的图片注意数据过大时可能会导致发送失败,此时建议通过mode设置倍数放大
输入bitmap 要打印的bitmap非透明图像mode 0:普通 1:倍宽 2:倍高 3:倍高倍宽
返回

32、打印图片方法2

方法void printBitmap2(Bitmap bitmap, int mode)
说明将bitmap图转成位图模式发送此方法需要将行间距设置为0此方法与printBitmap区别是不会造成数据失败后打印机未初始化的乱码注意数据过大时可能会导致发送失败,此时建议通过mode设置倍数放大
输入bitmap 要打印的bitmap非透明图像mode 0:8点单密度 1:8点双密度 32:24点单密度 33:24点双密度(原始大小)
返回

33、切刀切纸

方法void cutPaper(int m, int n)
说明切纸
输入m 切纸模式 0:全切; 1:半切; 2:进纸切纸n 进纸距离 此参数只有在设置 m=2时有效, 由于打印机型号不同切刀到打印头距离不同,当n=0时将自动走纸此距离,n>0将走额外设置距离
返回

34、表格打印

方法void printColumnsText(String[] colsTextArr, int[] colsWidthArr, int[] colsAlign)
说明以表格方式输出打印内容,每个数组表示在此列上的数据及格式,需要多次调用此方法才可以达到表格输出的样式效果
⚠️注意:调用此方法后会将之前设置样式初始化!
输入colsTextArr: 每列要打印的内容,支持中文及ascii码colsWidthArr:每列可容纳的最大字符数量,字符数以ascii码个数为单位(一个中文等于两个ascii码数量),当文本内容超出可容纳的最大数量时将移动到本列下一行,当所有列的最大字符数量超出一行所能容纳的字符数时,将不会打印colsAlign:每列内容的对齐方式,仅当内容字符数小于最大字符数量时才有效果
返回

35、发送数据指令

方法void sendRawData(byte[] cmd)
说明发送原始esc控制指令
输入cmd 发送的epson指令
返回

36、启用事务模式

方法voidstartTransBuffer(boolean isClear)
说明启用事务模式,用于控制打印内容的执行顺序和执行状态,只有在事务模式下才可以精确的获取打印内容的结果当进入事务模式后所有的打印指令会缓存待提交时发给打印机,所以未提交数据时将不会打印机
⚠️注意:暂时只有云打印机局域网打印支持事务模式
输入isClear是否清除未提交的缓存数据
返回

37、提交事务数据

方法voidcommitTransBuffer(TransCallback callback)
说明提交本次事务获取本次事务打印的执行情况建议等待提交事务结果后再执行下一次的事务提交注意:暂时只有云打印机局域网打印支持事务模式
输入callback 事务提交的执行结果
返回

38、退出事务模式

方法voidendTransBuffer()
说明退出事务模式之后的打印指令均直接发给打印机,不再关注打印执行情况注意:暂时只有云打印机局域网打印支持事务模式
输入
返回

商米外置打印机开发说明

3、局域网IP打印机

基于安卓系统编程DEMO下载:【SDK DEMO

注意:到手的云打印机因为没有配置过现场wifi网络,所以在开发的时候联网很不方便。所以我们提供了一个安装在安卓手机上的配网工具给合作伙伴下载使用。点击下载【wifi配网工具

SDK说明

为更好的简化打印机指令编程过程,商米打印机SDK将复杂的ESC/POS指令集成为简单易懂的API接口,使得您可以快速调用各种打印接口库,实现所有打印排版、样式设置功能,并且随着不断更新完善,大大减少开发者对于打印机设备配置、ESC/POS指令学习等工作;

当前SDK支持连接的LAN口、WIFI打印机:

商米58智能云打印机(NT21x系列)

商米80后厨云打印机 (NT31x系列)

· 集成方式:

aar包导入参考官方导入方式:https://developer.android.com/studio/projects/android-library?hl=zh-cn

· 避免混淆,在proguard-rules.pro混淆文件中增加以下配置:

-dontwarn  com.sunmi.externalprinteribrary.**-keep public class  com.sunmi.externalprinterlibrary.**{*;}

· SDK支持枚举的打印机

通过枚举类SunmiPrinter选择要连接打印机,可选择的打印机如下:

SunmiPrinter.SunmiNetPrinter—-商米云打印机局域网方式

· 局域网打印

目前局域网打印使用connectNetPrinter接口直接指定IP地址连接局域网内的商米云打印机,使用方法如下:

(1)初始化

SunmiPrinterApi.getInstance().connectNetPrinter(context,  “ip address”, 
    new  ConnectCallback{
         void onFound(){
              //发现打印机会回调此方法
        }
  
         void onUnfound(){
              //如果没找到打印机会回调此方法
        }
  
         void onConnect(){
              //连接成功后会回调此方法,则可以打印
        }
  
         void onDisconnect(){
              //连接中打印机断开会回调此方法,此时将中断打印
              //局域网打印机需要调用isConnected()接口主动查询
        }
});
 

(2)调用打印接口

当确定打印机已经连接成功后,就可以开始构建自己的打印内容,如下打印一行数字:

SunmiPrinterApi.getInstance().printText(“123456789\n”);

注意所有打印接口均会抛出打印机异常:

PrinterException error

当未连接打印机、接口参数错误等情况下会跑出异常;

由于局域网打印接口通过socket通讯,所以接口调用打印请创建单独线程使用不能应用于主线程,否则将抛出

PrinterException:Api can't run on MainThread!

(3)当不再使用打印机时,尽可能断开打印机连接,这样将释放资源给更多设备接入打印

SunmiPrinterApi.getInstance().disconnectPrinter();

(4)更多的使用方法请参考【打印机SDK接口API说明

商米外置打印机开发说明

2、外置蓝牙打印机

基于安卓系统编程DEMO下载:【SDK DEMO

SDK说明

为更好的简化打印机指令编程过程,商米打印机SDK将复杂的ESC/POS指令集成为简单易懂的API接口,使得您可以快速调用各种打印接口库,实现所有打印排版、样式设置功能,并且随着不断更新完善,大大减少开发者对于打印机设备配置、ESC/POS指令学习等工作;

当前SDK支持连接的蓝牙打印机:

商米58智能云打印机(NT21x系列)

商米80后厨云打印机 (NT31x系列)

· 集成SDK方式:

手动集成:

aar包导入参考官方导入方式:https://developer.android.com/studio/projects/android-library?hl=zh-cn

⾃动集成:

在项⽬build.gradle⽂件中添加依赖和属性配置:

dependencies{
 compile 'com.sunmi:external-printerlibrary:1.0.8'
}

· 避免混淆,在proguard-rules.pro混淆文件中增加以下配置:

-dontwarn  com.sunmi.externalprinteribrary.**-keep public class  com.sunmi.externalprinterlibrary.**{*;}

· SDK支持枚举的打印机

通过枚举类SunmiPrinter选择要连接打印机,可选择的打印机如下:

SunmiPrinter.SunmiBlueToothPrinter—-商米云打印机蓝牙方式

· 使用打印机

(1)初始化

通过指定打印机(SunmiPrinter.SunmiBlueToothPrinter),调用连接接口,因为连接打印机是个耗 时过程,需要通过回调确认

SunmiPrinterApi.getInstance().connect(context, SunmiPrinter.SunmiNTPrinter,
	new ConnectCallback{
		 void onFound(){
		 //发现打印机会回调此⽅法
		 }
		 void onUnfound(){
		 //如果没找到打印机会回调此⽅法
		 }
		 void onConnect(){
		 //连接成功后会回调此⽅法,则可以打印
		 }
		 void onDisconnect(){
		 //连接中打印机断开会回调此⽅法,此时将中断打印
		 }
	});	

(2)调用打印接口

当确定打印机已经连接成功后,就可以开始构建自己的打印内容,如下打印一行数字:

SunmiPrinterApi.getInstance().printText(“123456789\n”);

注意所有打印接口均会抛出打印机异常:

PrinterException error

当未连接打印机、接口参数错误等情况下会抛出出异常;

(3)当不再使用打印机时,尽可能断开打印机连接,这样将释放资源给更多设备接入打印

SunmiPrinterApi.getInstance().disconnectPrinter();

(4)更多的使用方法请参考【打印机SDK接口API说明

商米外置打印机开发说明

1、外置USB打印机

基于安卓系统编程DEMO下载:【SDK DEMO

SDK说明

为更好的简化打印机指令编程过程,商米打印机SDK将复杂的ESC/POS指令集成为简单易懂的API接口,使得您可以快速调用各种打印接口库,实现所有打印排版、样式设置功能,并且随着不断更新完善,大大减少开发者对于打印机设备配置、ESC/POS指令学习等工作;

当前SDK支持连接的USB打印机:

商米58热敏票据打印机(NT210)

商米58智能云打印机(NT21x系列)

商米80后厨云打印机 (NT31x系列)

· 集成SDK方式:

手动集成:

aar包导入参考官方导入方式:https://developer.android.com/studio/projects/android-library?hl=zh-cn

⾃动集成:

在项⽬build.gradle⽂件中添加依赖和属性配置:

dependencies{
 compile 'com.sunmi:external-printerlibrary:1.0.8'
}

· 避免混淆,在proguard-rules.pro混淆文件中增加以下配置:

-dontwarn  com.sunmi.externalprinteribrary.**-keep public class  com.sunmi.externalprinterlibrary.**{*;}

· SDK支持枚举的打印机

通过枚举类SunmiPrinter选择要连接打印机,可选择的打印机如下:

SunmiPrinter.SunmiCloudPrinter——商米云打印机NT21x系列等

SunmiPrinter.SunmiKitchenPrinter——商米80后厨云打印机NT31x系列等

SunmiPrinter.SunmiNTPrinter——商米58热敏票据打印机NT210

· 使用打印机

(1)初始化

通过指定USB打印机(如NT210-SunmiPrinter.SunmiNTPrinter),调用连接接口,因为连接打印机是个耗 时过程,需要通过回调确认

SunmiPrinterApi.getInstance().connect(context, SunmiPrinter.SunmiNTPrinter,
	new ConnectCallback{
		void onFound(){
		//发现打印机会回调此⽅法
		}
	
		void onUnfound(){
		//如果没找到打印机会回调此⽅法
		}
	
		void onConnect(){
		//连接成功后会回调此⽅法,则可以打印
		}
	
		void onDisconnect(){
		//连接中打印机断开会回调此⽅法,此时将中断打印
		}
	});

(2)调用打印接口

当确定打印机已经连接成功后,就可以开始构建自己的打印内容,如下打印一行数字:

SunmiPrinterApi.getInstance().printText(“123456789\n”);

注意所有打印接口均会抛出打印机异常:

PrinterException error

当未连接打印机、接口参数错误等情况下会跑出异常;

(3)当不再使用打印机时,尽可能断开打印机连接,这样将释放资源给更多设备接入打印

SunmiPrinterApi.getInstance().disconnectPrinter();

(4)更多的使用方法请参考【打印机SDK接口API说明

数据云打印机对接说明

4、开发数据回调API接口

特别说明:商米数据云打印机的数据采集服务集成在【商米数字店铺】和【商米助手】APP中。所以只有执行了【商米助手】APP将打印机与门店进行设备绑定,打印机的打印数据才会上报到对应的门店下,然后通过本API接口将合作伙伴云与门店进行绑定,才能接收到打印机数据。

绑定前获取门店对接凭证

登录【商米数字店铺】,在【基础数据>组织管理>组织详情>获取对接凭证】中获取【对接店铺编号sunmi_shop_no】和【对接店铺密钥sunmi_shop_key】,记录下来为后续绑定接口提供参数(为了保证信息的有效性和安全性,对接凭证的有效期为24小时,过期之后可以重新获取)。

协议说明

  1. 对接的接口目前只开放HTTPS方式推送消息,所有的消息一律采用POST方式。
  2. 商米接口请求URL地址:https://store.sunmi.com/openapi
  3. 传参请求头Content-Type需要加上”application/x-www-form-urlencoded”。
  4. 以下每个接口只列出私有参数和返回结果,其他参数请求请看公共参数说明。
  5. 请求和返回内容皆为json格式数据。
  6. 字符编码均为UTF-8。

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

参数名必填类型说明
app_idstring软件合作伙伴的唯一身份标识,同步获取的还有签名校验参数secret key
randomstring随机字符串,由数字和大小写字母组成,长度范围为6-10位
timestampint当前的unix时间戳,精度到秒级,10位数字,格式参考https://tool.chinaz.com/tools/unixtime.aspx
signstring签名信息,详见下文签名规则的说明

请求公共参数sign签名说明

  1. 对所有包含key的请求参数按照ASCII码顺序从小到大排序,将key value键值对依此拼接成字符串(文件参数不参与验签)
  2. 在字符串尾部拼接该软件合作伙伴独有的签名校验secret key
  3. 对字符串进行MD5加密,再将生成的MD5加密转化为32位全大写字符

示例:如果接口包含下列参数:
app_id:87F380B846C51FF7
random:289192
timestamp:1603718252
shop_id:100001
company_id:10000
shop_nam:myShop
company_name:myCompany
sunmi_shop_no:470826116009
sunmi_shop_key:MG4LJ5ERHUBDMF5XOOU8
contact_person:LiLei
phone:13166668888

则签名生成步骤为:
步骤1:按照key的ASCII码顺序从小到大排序并拼接成字符串
str1 = “app_id=87F380B846C51FF7&company_id=10000&company_name=myCompany&contact_person=LiLei&phone=13166668888&random=289192&shop_id=100001&shop_nam=myShop&sunmi_shop_key=MG4LJ5ERHUBDMF5XOOU8&sunmi_shop_no=470826116009&timestamp=1603718252”

步骤2:在字符串尾部拼接secret key
str2 = str1 + “&key=kdsofkdsnflke9382938k”

步骤3:对str2进行MD5加密,并转为32位全大写字符,就可以获得最终签名sign
sign = MD5(str2).upper() = 6413A7275DBE256D936AAEF5F1D958B9

返回公共参数说明

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

请求后,返回结果作为HTTP消息返回,如果消息签名认证失败,HTTP消息会返回 401等作为提示。

如果消息签名认证通过,则进入业务层处理,此次HTTP请求返回200 OK。

具体业务层面的操作返回JSON值在消息体中。

返回常见错误代码说明

错误码说明
0成功
5090sign校验不正确
5091timestamp的请求过期

4.1、商米云API接口-门店绑定接口

接口描述

通过本接口调用,用户可以将第三方对接软件上的某门店与【商米数字店铺】中的门店进行绑定。

接口名:

/shop/bind

接口私有参数

参数名称是否必须类型说明
shop_idstring第三方对接软件中门店的标识,对接的软件提供shop_id 与 sunmi_shop_no 具有一一对应关系。对于v2.0 及以后版本的所有接口,建议采用sunmi_shop_no作为店铺标识。对于已经使用shop_id作为参数的接口保持后向兼容,不需要进行修改。
company_idstring第三方对接软件中商户的标识,对接的软件提供商户是门店的上一级组织。记录商户与门店对应关系,可以据此处理后续商户级别业务,以及商户内跨门店业务。对于单商户-多门店模式的用户,建议商户-门店的对应关系在第三方对接软件和【商米数字店铺】体系中保持一致。
shop_namestring第三方对接软件中门店的门店名称
company_namestring商户名称
sunmi_shop_nostring【商米数字店铺】的门店【对接店铺编号】,可在【商米数字店铺】的【基础管理>组织管理>组织详情】中获取
sunmi_shop_keystring【商米数字店铺】的门店【对接店铺密钥】,可在【商米数字店铺】的【基础管理>组织管理>组织详情】中获取
contact_personstring联系人姓名
phonestring联系人电话
industry_idint门店行业类别编号
industry_namestring门店行业类别名称
provincestring所在省份
citystring所在市
districtstring所在区县
addressstring商户门店地址
mailstring联系人邮箱
formatint门店业态 0-无 1 – 餐前付款, 2 – 餐后付款,默认0
statusint门店状态 1 – 启用, 2 – 停用, 默认1

请求示例

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/shop/bind",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "shop_id": "10096",
    "shop_name": "myShop",
    "sunmi_shop_no": "560279010307",
    "sunmi_shop_key": "MG4LJ5ERHUBDMF5XOOU8",
    "company_id": "10000",
    "company_name": "myCompany",
    "contact_person": "LiLei",
    "phone": "13166668888",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值

{
    "code": 0,   /* 其他错误参考错误列表 */
    "msg": "succeed",
    "data": {}
}

错误编号列表:

错误编号错误原因
5000数据库错误
5032非法店铺
5041非法对接软件
5042对接软件中的门店已绑定
5043对接商米店铺密钥错误

4.2、商米云API接口-门店解绑接口

接口描述

通过本接口调用,用户可以将SaaS上的某门店与【商米数字店铺】中的门店解除绑定。

接口名:

/shop/unbind

接口私有参数

参数名称是否必须类型说明
shop_idstring第三方对接软件中门店的标识,对接的软件提供
company_idstring第三方对接软件中商户的标识,对接的软件提供
sunmi_shop_nostring【商米数字店铺】的门店【对接店铺编号】

请求示例

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/shop/unbind",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "shop_id": "10096",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值

{
    "code": 0,   /* 其他错误参考错误列表 */
    "msg": "succeed",
    "data": {}
}

错误列表:

错误编号错误原因
5032非法店铺
5041非法对接软件
5000数据库错误

4.3、合作伙伴云API接口-数据接收接口

接口描述:

当商米云收到打印机的小票数据并完成解析后,会调用软件合作方提供的一个接口发送数据。在合作伙伴云端开发完成了本数据接收接口以后,还需要将本接口的【回调URL地址】和【消息类型event】告诉商米对接技术人员;商米后台设置以后才会回传数据到合作伙伴云。

接口名:

/uploaddata

接口私有参数:

参数名必填类型说明
sunmi_shop_nostring【商米数字店铺】平台门店的唯一编号
shop_idstring店铺在对接软件体系下的唯一标识
eventint触发消息的类型,具体请参考下文
payloadstring消息的具体格式(根据消息不同会有不同的json),具体请参考下文

注意:如果回调消息发送失败,会触发重传机制。一共会触发4次重传,时间间隔分别为15秒, 30 秒, 1分钟和2分钟。

数据事件和消息event

1、event=6001 未经处理的文字小票上传消息

报文格式: application/x-www-form-urlencoded;param=value;charset=UTF-8

消息体格式:
{ 
  "app_id": 'CSJGYI6T8P237',                //唯一标识接入身份,联系商米数字店铺提供
  "event": '6002',                          // 触发消息的类型
  "payload": '{
       "id":"70dcd2f600e45736e1",           // 系统生成的小票ID
       "sn":"N302D9WZC0064",                // 打印设备SN
       "text": "abc"                        // 文字小票内容
  }',
  "random": 'NDL8GXR',                          // 随机字符串,由数字和字母组成,长度范围为6-10位
  "shop_id": '29203',                           // 店铺在SaaS软件体系下的唯一标识, 没有或者不需要则为空
  "sign": '738D9FF2482D59E5DC1FB32B6F445464',   //签名校验
  "sunmi_shop_no": '28393437387',               // 商米数字店铺平台门店唯一编号, 没有或者不需要则为空
  "timestamp": '1604567375'                     //当前的unix timestamp,精度到秒级,10位数字
}

备注:payload字段对应的值为string类型,解析对此string类型内容进行json解析

2、event=6002 未经处理的图片小票上传消息

报文格式: application/x-www-form-urlencoded;param=value;charset=UTF-8

消息体格式:
{ 
  "app_id": 'CSJGYI6T8P237',                //唯一标识接入身份,联系商米数字店铺提供
  "event": '6002',                          // 触发消息的类型
  "payload": '{
       "id":"70dcd2f600e45736e1",           // 系统生成的小票ID
       "sn":"N302D9WZC0064",                // 打印设备SN
       "base64_image":"DKJOIFDNLKSDJLSJDISDNLKFJDLSLDJF==",  // 图片小票的base64 encoded string
  }',
  "random": 'NDL8GXR',                          // 随机字符串,由数字和字母组成,长度范围为6-10位
  "shop_id": '29203',                           // 店铺在SaaS软件体系下的唯一标识, 没有或者不需要则为空
  "sign": '738D9FF2482D59E5DC1FB32B6F445464',   //签名校验
  "sunmi_shop_no": '28393437387',               // 商米数字店铺平台门店唯一编号, 没有或者不需要则为空
  "timestamp": '1604567375'                     //当前的unix timestamp,精度到秒级,10位数字
}

备注:payload字段对应的值为string类型,解析对此string类型内容进行json解析

3、event=6003 经过处理的小票消息

报文格式: application/x-www-form-urlencoded;param=value;charset=UTF-8

消息体格式:
{ 
  "app_id": 'CSJGYI6T8P237',                //唯一标识接入身份,联系商米数字店铺提供
  "event": '6003',                          // 触发消息的类型
  "payload": '{
       "id":"70dcd2f600e45736e1",           // 系统生成的小票ID
       "sn":"N302D9WZC0064",                // 打印设备SN
       "order_time":"2020-11-05 17:45:00",  // 小票生成时间 
       "order_id":"202011051707",           // 小票上的订单ID 
       "order_received_amount":"20",          // 小票金额 
       "sales_detail_list":[                // 明细列表
            { "amount":"4",                   // 商品单价
              "item":"维他柠檬茶",           // 商品名字
              "quantity":"1"                  // 商品数量
            }, 
            {"amount":"7","item":"梅汤","quantity":"1"},
            {"amount":"6","item":"旺仔牛奶","quantity":"1"}, 
            {"amount":"3","item":"罐","quantity":"1"}
      ]
  }',
  "random": 'NDL8GXR',                          // 随机字符串,由数字和字母组成,长度范围为6-10位
  "shop_id": '29203',                           // 店铺在SaaS软件体系下的唯一标识, 没有或者不需要则为空
  "sign": '738D9FF2482D59E5DC1FB32B6F445464',   //签名校验
  "sunmi_shop_no": '28393437387',               // 商米数字店铺平台门店唯一编号, 没有或者不需要则为空
  "timestamp": '1604567375'                     //当前的unix timestamp,精度到秒级,10位数字
}

备注:payload字段对应的值为string类型,解析对此string类型内容进行json解析

数据云打印机对接说明

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

  1. 为了保障合作伙伴与商米对接的安全性,合作伙伴需要在商米【合作伙伴平台】注册一个账户。该账户用于绑定打印机设备的出库归属权(打印机在商米出库时渠道一定要选择该账户,否则会因归属权问题无法调用接口绑定设备)
  2. 【合作伙伴平台】注册的流程请参考:https://docs.sunmi.com/developers/registration-for-partners/
  3. 注册完成后,请联系商米技术支持人员,提供公司名称和邮箱,商米将会发送【app_id】和【secret_key】给贵司,用于对接联调使用。
  4. 该参数对于每个合作伙伴平台账户是唯一的,适用于该软件合作伙伴账户下所有的商户门店和打印机,也适用于【商米数字店铺】中电子价签和摄像头的对接。

数据云打印机对接说明

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. 此时已经完成基础对接,打印机打印票据的时候,就会同步将数据推送到合作伙伴云端。