商米外置打印机开发说明

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说明

商米外置打印机开发说明

说明

商米支持的打印机主要分为两种形态,一种是商米一体机中内置的打印机,一种是外置独立的打印机。本文档主要针对外置打印机SDK进行说明。开发打印机程序之前,您需要对票据打印机的工作原理和ESC/POS指令集有一定的理解,才能理解票据排版所需的基本知识。

1、外置USB打印机

2、外置蓝牙打印机

3、局域网IP打印机

4、打印机SDK接口API说明

商米云打印机实用工具使用说明

下载商米云打印机实用工具

连接打印机

使用商米云打印机实用工具对打印机进行设置前,首先需要连接打印机.

打印机开机,并通过Type-C USB线将打印机与电脑连接起来,或者将打印机和电脑接入同一个局域网(无线网络或有线网络均可).

运行sunmi-cloud-printer-utility.exe,单击主界面左上方工具栏上的”连接”图标,会弹出一个对话框,列出当前与电脑连接的打印机,如下图所示:

连接打印机图1

如果打印机没有在列表中出现,请检查打印机电源是否开启、USB线是否正确连接、或者打印机与电脑是否接入了相同的局域网,再单击”扫描”按钮刷新列表.

“连接类型”栏,”网络”字样后面的括号里是打印机的IP地址.

选择需要连接的打印机,单击”连接”按钮.

与打印机连接成功后,主界面会显示打印机信息,左下方状态栏会显示”已连接”字样.

查看设备信息

在”设备信息”页面,可以查看打印机的型号、序列号、软硬件版本号等信息.如下图所示,这些信息是不能修改的.

查看设备信息1

配置以太网静态IP地址

在”以太网”页面,可以查看打印机在以太网络动态获取的IP地址和设置静态IP地址.如下图所示:

配置以太网静态IP地址图1

大多数情况下,可以按照以下方法配置静态IP地址:

  1. 将打印机通过网线连接到宽带路由器或交换机.
  2. 如果动态分配的IP地址和子网掩码都是0.0.0.0,等待约10秒后再单击工具栏上的”刷新”图标.
  3. 出现动态分配的IP地址和子网掩码后,”IP地址(静态分配)”的前三个数字设为跟”IP地址(动态分配)”一样,最后一个数字设为不一样的;”子网掩码(静态分配)”设为跟”子网掩码(动态分配)”一样.

即使打印机未接入有线网络,仍然可以设置静态IP地址. 设置完成后,需要单击”保存”按钮才能生效.

单击”打印测试页”按钮可以通过有线网络打印一张测试小票.如果配置了静态IP地址,则会通过静态IP地址打印测试页,否则会通过动态IP地址打印测试页.

配置4G网络

在”4G”页面,可以查看4G网络的状态.如下图所示:

配置4G网络图1

需要注意的是,”使用指定的接入点名称和拨号号码”只针对插入式SIM的硬件来配置APN和拨号号码.在没有特别说明情况下,目前品牌中文版都采用内置ESIM方式,产品有自带拨号的一系列参数,一定不能勾选并使用此选项,否则会干扰内置参数影响上网.

修改了接入点名称和拨号号码后,需要单击”保存”按钮,并点击”重启模块…”按钮或重新开机才能生效.

配置Wi-Fi静态IP地址

在”Wi-Fi”页面,可以查看打印机在无线网络动态获取的IP地址和设置静态IP地址.如下图所示:

配置WIFI静态IP地址图1

大多数情况下,可以按照以下方法配置静态IP地址:

  1. 将打印机接入Wi-Fi网络.可参考第5章”配置Wi-Fi SSID”,或在手机上使用商米助手进行配置.
  2. 如果动态分配的IP地址和子网掩码都是0.0.0.0,等待约10秒后再单击工具栏上的”刷新”图标.
  3. 出现动态分配的IP地址和子网掩码后,”IP地址(静态分配)”的前三个数字设为跟”IP地址(动态分配)”一样,最后一个数字设为不一样的;”子网掩码(静态分配)”设为跟”子网掩码(动态分配)”一样.

即使打印机未接入无线网络,仍然可以设置静态IP地址. 设置完成后,需要单击”保存”按钮才能生效.

单击”打印测试页”按钮可以通过无线网络打印一张测试小票.如果配置了静态IP地址,则会通过静态IP地址打印测试页,否则会通过动态IP地址打印测试页.

配置Wi-Fi SSID

在”Wi-Fi”页面,单击”配置SSID…”按钮,可以配置打印机Wi-Fi的SSID,将打印机接入Wi-Fi网络.如下图所示:

配置WIFI SSID图1

在”SSID”栏输入无线网络的SSID,在”密码”栏输入无线网络的密码,然后单击”确认”按钮.打印机成功接入Wi-Fi网络后,单击工具栏上的”刷新”图标,会显示分配到的动态IP地址和Wi-Fi网络的SSID.

单击”打印测试页”按钮可以通过无线网络打印一张测试小票.如果配置了静态IP地址,则会通过静态IP地址打印测试页,否则会通过动态IP地址打印测试页.

串口设置

云打印机支持串口打印.默认的串口设置是:波特率115200,8位数据位,1位停止位,无奇偶校验位,无硬件流控.如果上位机无法适配这样的串口设置,可以修改云打印机的串口设置以满足上位机的要求.

串口设置图1

设置完成后,需要单击”保存”按钮才能生效.

单击”打印测试页…”按钮,选择正确的串口,可以通过串口打印一张测试小票.

打印设置

在”打印设置”页面,可以进行打印相关的一些设置.如下图所示:

打印设置图1.jpg

更改设置后,需要单击”保存”按钮后才能生效.如果没有保存更改,单击工具栏上的”刷新”图标,所做的修改会丢失.

打印纸设置

打印纸类型支持”普通票据”和”带黑标的票据”两种.

“普通票据”为最常见的热敏打印纸.选择”普通票据”后,可以选择当打印机仓盖合上时,是否自动走一小段纸并切纸.

“带黑标的票据”每隔一定距离,在打印纸的两侧或中间会有小黑块.选择”带黑标的票据”后,需要根据所使用的黑标打印纸,正确选择黑标的位置,并设置合理的切纸位置和打印位置.

“切纸位置”指定在黑标上边沿上方多少毫米处进行切纸.如果希望在黑标上边沿的下方进行切纸,可以将数值设为负值.可以设置的数值范围为-100.0 ~ 25.0mm.

“打印位置”指定在切纸位置下方多少毫米处开始打印.不能指定在切纸位置上方开始打印.可以设置的数值范围为10.0 ~ 100.0mm.

单击”黑标打印测试”按钮可以测试黑标打印的效果.

未取纸设置

打印小票并切纸后,如果小票未被取走,打印机上的报警灯带会一直闪烁,另外还可以设置是否播报语音提醒和是否允许继续打印.

如果勾选了”停止打印”复选框,必须取走小票后才能继续打印. 如果勾选了”语音提醒”复选框,取走小票前会定期播报语音提醒.

打印了小票但没有切纸,不会触发未取纸报警,报警灯带不会闪烁,不会有语音提醒,也不会禁止打印.

打印了小票并切了纸,会触发未取纸报警.但打印机重新上电后,即使仍然未取纸,也不会触发未取纸报警.

默认字符集

设置打印机的默认字符集.

UTF-8模式中日韩编码代码页说明
N/AN/A按UTF-8编码对输入字符进行解析
GB18030N/A按GB18030编码进行解析
BIG5N/A按BIG5编码对输入字符进行解析
Shift JISN/A按Shift JIS编码对输入字符进行解析
JIS 0208N/A按JIS 0208编码对输入字符进行解析
KS C 5601N/A按KS C 5601编码对输入字符进行解析
关闭汉字模式某个选定的代码页对编码值为128~255的字符,按代码页进行解析

打印浓度与质量

打印浓度的单位为百分比,可以设置的数值范围是50~150.默认为100%,小于100%为变淡;大于100%为变深.

打印质量没有单位,可以设置的数值范围是0~100.0为最低质量,但打印速度最快;100为最高质量,但打印速度最慢.

更改设置后,需要单击”保存”按钮才能生效.可以单击”打印测试页”,查看打印效果.

数据云打印机对接说明

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 未经处理的文字小票上传消息

{
  "id": 123,     // 系统生成的小票ID
  "sn": "sn",    // 打印设备SN
  "text": "abc"  // 文字小票内容
}

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

{
  "id": 123,  // 系统生成的小票ID
  "sn": "sn", // 打印设备SN
  "base64_image": "avc"  // 图片小票的base64 encoded string
}

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

{
  "id": 123,  // 系统生成的小票ID
  "sn": "sn",  // 打印设备SN
  "order_id": "a123456", // 小票上的订单ID  
  "order_time": "2020-01-01", // 小票生成时间  
  "order_received_amount": 10.11  // 小票金额  
  "sales_detail_list": [{   //明细列表
    "amount": 10,          // 商品单价
    "item":   "商品",      // 商品名字
    "quantity": 1          // 商品数量
  },
  ...
  ]
}

数据云打印机对接说明

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训练,如果没能正确识别,请联系商米支持人员进行处理。