云打印机对接说明

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设备已绑定，请检查是否已在商米助手绑定过，需在商米助手中解绑后才能执行本渠道绑定

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打印票据张数（默认1张）
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不属于该渠道设备

身份证云识别服务

对接调试一共分为两部分，一部分为安卓应用对接的SDK，另一部分为应用服务器与商米服务器直接的云对接API。

应用软件集成身份证识别sdk，应用软件后端服务器集成云端api（集成云端api用于保护用户身份信息，保证整个数据链路中，只有应用软件可获取身份证明文信息）

1、终端发起身份证请求，并发送身份证卡片信息到应用软件后台服务器
2、服务器验证卡片真伪，如果为真，返回reqid
3、应用软件收到reqid后，把reqid发送给应用后台服务器
4、应用后台服务器通过openapi把数据发送给商米服务器
5、商米服务器向解码服务器请求解析身份证信息
6、身份证解码服务器返回身份证全部信息的加密数据
7、商米服务器将加密数据返回应用软件后台服务器
8、应用软件服务器解密加密数据后，得到身份证明文数据
9、将明文数据返回应用软件

注：身份证云识别依赖网络，要求每次网络交互过程不得超过200ms，数据交互延迟高于110ms会降低解码成功率（sdk返回9100X错误），高于200ms会造成读卡失败。使用前请确定网络环境满足要求，sdk提供了延迟检测接口，用户可使用延迟检测接口测试网络。不建议使用物联网卡。

1、APP设计和开发

APP设计

APP设计注意要点：android NFC或者读卡器识别到卡片后会有声音提示，身份证读卡操作是个耗时操作，当声音提示后，不能直接拿走卡片，需要等到读卡成功或者失败再拿开卡片。界面上需要提示用户在有明确反馈前不要拿走卡片，建议：loading+文字提示

APP开发

身份证云识别的Android SDK 的集成、初始化、使用流程、网络延迟检测等。

应用发布前，请确保现场网络环境已达要求，否则将影响识别成功率。

1.1、集成

  • 资源文件(AAR文件)
SunmiEID-SDK-release-v1.0.4.aar下载

1.2、导入AAR包

  • 打开项目后:File -> New -> New Module…
  • 在新的对话框:New Module -> Import .JAR/.AAR Package -> Next
  • 下一步:Import Module from Library -> 选择 aar 文件夹下的 SunmiEID-SDK_vX.X.X-release/tes.aar 文件 -> Finish
  • 完成:

1.3、app 模块引用

  • 点击-打开模块设置:
  • 设置对话框：选择“app” -> 点击“+”号 ->  选择“Module Dependency”
  • 显示：勾选上对应的模块（SunmiEID-SDK_vX.X.X-release/tes）-> 点击“OK”，相关SDK引用成功。

1.4、接口文档

1.4.1、初始化

  • 推荐在Application实现SDK初始化实现：
public class IApp extends Application implements EidCall {
    @Override
    public void onCreate() {
        super.onCreate();
        try {
            EidSDK.init(this, "appid", this);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onTerminate() {
        super.onTerminate();
        EidSDK.destroy();
    }

    @Override
    public void onCallData(int code, String msg) {
        Log.d("app", "onCallData: code:" + code + ", msg:" + msg);
    }
}

1.4.2、获取 EidReader 实例

private void initEidReader() {
    Log.d("Eid", String.format("商米SDK.Ver:%s, 读卡模块Ver:%s", EidSDK.getSunmiEidSDKVersion(), EidSDK.getEidSDKVersion()));
    EidPic.init(this, fileNameBase);
    eid = EidSDK.getEidReaderForNfc(1, this);
}

1.4.3、实现 EidCall 接口

@Override
public void onCallData(int code, String msg) {
    switch (code) {
        case EidConstants.READ_CARD_START:
            mState.setText("开始读卡，请勿移动");
            Log.i(TAG, "开始读卡，请勿移动");
            break;
        case EidConstants.READ_CARD_SUCCESS:
            closeNFCReader();//电子身份证需要关闭
            Log.e("TAG", String.format(Locale.getDefault(), "正在获取身份信息(%s)，请稍等.....", msg));
            mState.setText(String.format(Locale.getDefault(), "正在获取身份信息(%s)，请稍等.....", msg));
            File file = new File(fileNameBase, "zp.bmp");
            if (file.exists()) {
                file.deleteOnExit();
            }
            getIDCardInfo(msg); //通过card_id请求识读卡片的信息
            break;
        case EidConstants.READ_CARD_FAILED:
            closeNFCReader();//电子身份证需要关闭
            Log.i(TAG, String.format(Locale.getDefault(), "读卡错误,请重新贴卡：%s", msg));
            mState.setText(String.format(Locale.getDefault(), "读卡错误,请重新贴卡：%s", msg));
            break;
        case EidConstants.READ_CARD_DELAY:
            Log.e("TAG", String.format(Locale.getDefault(), "延迟 %sms", msg));
            mState.setText(String.format(Locale.getDefault(), "延迟 %sms", msg));
            break;
        default:
            break;
    }
}

1.4.4、调用NFC识读卡片

  • 识读身份证：
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    eid.nfcReadCard(intent);
 }
  • 识读电子身份证：
@Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        try {
           Tag tagFromIntent = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);
           try {
              isodep = IsoDep.get(tagFromIntent);
              isodep.connect();
              if (isodep.isConnected()) {
                  eid.readCard(IDCardType.ECCARD, new EidReadCardCallBack() {
                      @Override
                      public byte[] transceiveTypeB(byte[] data) {
                          return data;
                      }
                      @Override
                      public byte[] transceiveTypeA(byte[] data) {
                          byte[] outData = new byte[data.length];
                          try {
                              outData = isodep.transceive(data);
                          } catch (Exception e) {
                              e.printStackTrace();
                          }
                          return outData;
                      }
                  });
             } else {
                  closeNFCReader()
             }
        } catch (Exception e) {
             e.printStackTrace();
        }
    } catch (Exception e) {
        e.printStackTrace();
    }
 }

    private void closeNFCReader() {
        if (isodep != null) {
            try {
                isodep.close();
                isodep = null;
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }

1.5、NFC、金融设备读卡及动态授权相关

  • 直连商米 Open Api 接口：EidCardDemo-OpenApi （直连商米open api服务器，不推荐使用该方式，该用法可能会导致appid与appkey同时泄漏，造成损失将由应用商自己承担）

1.6、详细接口说明

  • 详细接口文档：
javadoc-v1.0.4下载

1.7、错误码ErrorCode

2、身份证服务 API 接口

2.1、公共参数说明

2.1.1、概要

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

应用服务器demo：

商米身份证服务的接口采用 HTTPS 协议，参数通过 form 方式传递，使用 POST 方式发送到请求地址。

  1. 商米身份证服务的接口采用 HTTPS 协议
  2. 参数通过 form 方式传递，返回结果为 JSON 格式
  3. 接口只支持 POST 方式请求
  4. HTTP header 设为 application/x-www-form-urlencoded;charset=utf-8

2.1.2、公共参数说明

  1. 每个接口请求参数包括公共参数和私有参数
  2. 返回结果均为 JSON 格式

请求公共参数

参数名 类型 说明
sign string 签名（32位大写），参考签名生成方式
app_id string 商米提供的 app_id

 

返回公共参数

参数名类型说明
codestring返回码，参见常用错误码表
dataobject正常返回，如有错误不返回
msgstring错误提示信息，如有错误此字段返回错误描述

2.1.3、签名生成说明

签名算法：MD5

签名生成方式：

  1. 参数名称 ASCII 字典顺序排序（sign 除外）
  2. 以键值对的方式拼接（即 key1=value1&key2=value2&key3=value3）
  3. 拼接 app_key 到字符串最后（即 key1=value1&key2=value2&key3=value3$appkey）
  4. 对字符串进行 MD5 加密得到最终的 sign 值（32位大写）

2.1.4、常见错误码

返回码说明
10000成功返回
20001授权失败
20002服务不可用
40001缺少必要参数
40002非法参数

2.2、身份证云识别接口

  • 接口地址：/v1/eid/decode
  • 请求方式：POST

2.2.1、请求参数

参数名类型说明
app_idstring商米提供的 app_id
signstring签名（32位大写），参考签名生成方式
request_idstringandroid端生成的 request_id
encrypt_factorstring加密因子（8 位大小写字母和数字组成的的随机字符串，建议每次访问随机生成）

2.2.2、返回参数

成功返回

参数名类型说明
codestring返回码，参见常用错误码表
dataobject返回身份证信息，参见下方 data 域内容
msgstring错误提示信息，如有错误此字段返回错误描述

成功返回 data 域内容

参数名类型说明
infostring身份证信息密文，解密方式参见解密说明

示例：

{
    "code": "10000",
    "data": {
        "info": "xxxxxxxxxxxxx"
    },
    "msg": ""
}

失败返回

参数名类型说明
codestring返回码，参见常用错误码表
dataobject错误返回时，包含业务错误信息，参见下方 data 域内容
msgstring错误提示信息，如有错误此字段返回错误描述

失败返回 data 域内容

参数名类型说明
sub_codestring业务错误码
sub_msgstring业务错误返回信息

示例：

{
    "code": "10000",
    "data": {
        "sub_code": "50001",
        "sub_msg": "xxxxxxxxxx"
    },
    "msg": ""
}

2.2.3、解密说明

  • 加密方式：DES_CBC_PKCS5Padding 加密
  • 加密因子：传入的 encrypt_factor

解密流程：

  1. 对 info 字符串 base64 解码（standard 标准解码），解码完为 stringA
  2. 对 stringA 字符串进行 des 解密，密钥 key 和向量 iv 均为 encrypt_factor 加密因子，解密完为 stringB
  3. stringB 即是身份证信息的 json 格式，内容参见下方身份证云解码信息

身份证云解码信息：

参数名类型说明
base_infoobject身份证基础信息，参见下方身份证基础信息说明
dnstring指纹信息
picturestring身份证头像照片
appeidcodestring应用网络身份标记，同一个身份有一个编码

身份证基础信息：

参数名类型说明
namestring姓名
nationstring民族（如：汉）
sexstring性别（如：男）
idnumstring身份证号码
idTypestring证件类型，见下方证件类型说明
birthDatestring出生年月日（如：20010305）
addressstring身份证住址
beginTimestring身份证有效期限开始时间（如：20180305）
endTimestring身份证有效期限结束时间（如：20180305）
signingOrganizationstring签发机关

示例：

 "base_info": {
      "address": "xx省xx市xxxx路xx号",
      "beginTime": "20180305",
      "endTime": "20180305",
      "birthDate": "20010305",
      "idType": "01",
      "idnum": "xxxxxxx",
      "name": "孙小红",
      "nation": "汉",
      "sex": "男",
      "signingOrganization": "xx市xx公安局"
    },
    "dn": "xxxxxxxxxx",
    "picture": "xxxxxxxxx",
    "appeidcode": "xxxxxxxxx",

 

身份证云识别介绍

产品与服务介绍

1、身份证云识别

身份证件在入住、出行、金融、医疗等各个领域被广泛用于用户身份核实。传统的证件识别方式是通过专用证件阅读器验证身份证件，以确保登记信息的真实性和准确性，但存在着成本较高；体积较大，不易于携带；专用证件阅读器直接识别出来的证件信息是明文信息，在传输过程中容易被盗取或篡改，不适合直接在互联网中传输等问题。电子身份证件云识读服务可以解决以上问题，现免费向出行、入住、政务民生、金融、医疗等行业的应用机构提供。

2、什么是电子身份证件云识读服务？

在支持NFC功能的手机中，APP应用系统中通过商米提供的SDK读取二代身份证的加密数据，并发送到公安部身份证云解码中心进行解码和身份认证，然后将解码结果（身份证号码和姓名等信息）返回给应用系统，完成对用户身份信息的认证。

3、电子身份证件云识读服务支持哪些证件？

第二代居民身份证、港澳台居民居住证、外国人永久居留证、护照、eID身份电子证照。

4、电子身份证件云识读服务支持哪些终端？

支持NFC的（支持ISO14443协议的）设备：L2、L2K、V2pro、T1mini、T2mini、带NFC的刷卡器

5、电子身份证件云识读服务的套餐类型？

1、按次数购买,有效期1年

2、包年购买：为账号购买包年的套餐，一个账号下只能有一个包年套餐。用户可以选择包年的时长以及需要服务的设备名额。购买后，用户可以为包年套餐续费、增加名额和导入设备号。导入设备号后，对应设备号就拥有了有效期内无限使用身份证识别的功能。

6、接入流程

1、注册为商米合作伙伴

2、购买身份证服务套餐

3、应用和应用服务器集成云识别sdk

4、在合作伙伴平台查看和管理服务

云打印机对接说明

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

  • LF 打印并走纸一行
内容说明
[格式]ASCII：LF
Hex：0A
Decimal：10
[描述]· 标准模式下打印缓冲区内数据并走纸一行
[注释]· 该指令将当前位置置于行首。
  • ESC ! n 选择打印模式
内容说明
[格式]ASCII：ESC ! n
Hex：1B 21 n
Decimal：27 33 n
[范围]0≤n≤255
[描述]设根据n的值设置字符打印模式
n=0字体标准大小
n=16字体倍高
n=32字体倍宽
n=48字体倍高宽
[注释]· 所有字符以底端对齐。
· 对英数字符和汉字同时有效。
[默认值]n=0
  • ESC a n 选择对齐方式
内容说明
[格式]ASCII：ESC a n
Hex：1B 61 n
Decimal：27 97 n
[范围]0≤n≤2 或 48≤n≤50
[描述]将一行数据按照指定的位置对齐如下n用以选择对齐方式：
0,48 左对齐
1,49 居中
2,50 右对齐
[注释]· 标准模式下仅在一行的开始处时，该命令才有效。
· 该命令在打印区域执行对齐。
[默认值]n=0
  • ESC p m t1 t2 打开钱箱驱动脉冲
内容说明
[格式]ASCII：ESC p m t1 t2
Hex：1B 70 m t1 t2
Decimal：27 112 m t1 t2
[范围]m = 0, 1, 48, 49
0 ≤ t1 ≤ 255
0 ≤ t2 ≤ 255
[描述]· m=0, 48 钱箱插座引脚2；m=1, 49 钱箱插座引脚5
· t1指定脉冲开启时间为[ t1 × 2 ms].
· t2指定脉冲关闭时间为[ t2 × 2 ms].
[注释]· 指定一个值(t1
  • GS V m 切刀裁纸
内容说明
[格式]ASCII：GS V m
Hex：1D 56 m
Decimal：29 86 m
[范围]m=1, 49
[描述]· 选择一种切刀裁纸操作
[注释]· 依据所装的自动裁纸器类型的不同，裁纸状态也不同。
· 仅在一行开头处理该命令时,该命令有效。
· 只有部分裁纸，没有完全裁纸。
  • GS H n 选择条码字符的打印位置
内容说明
[格式]ASCII：GS H n
Hex：1D 48 n
Decimal：29 72 n
[范围]0≤n≤3 或 48≤n≤51
[描述]打印条码时，为条码字符选择打印位置。
n指定条码字符打印位置：
0,48 不打印
1,49 在条码上方
2,50 在条码下方
3,51 在条码上方及下方
[默认值]n = 0
  • GS h n 选择条码高度
内容说明
[格式]ASCII：GS h n
Hex：1D 68 n
Decimal：29 104 n
[范围]1≤n≤255
[描述]· 设置条码的纵向高度。n设定垂直方向的点数（0.125mm/点）
[默认值]n= 162
  • GS w n 设置条形码宽度
内容说明
[格式]ASCII：GS w n
Hex：1D 77 n
Decimal：29 119 n
[范围]1≤n≤6
[描述]· 设置条形码水平尺寸
[默认值]n=3
  • GS k m n d1…dn 打印条码
内容说明
[格式]ASCII：GS k m n d1…dk
Hex：1D 6B m n d1…dk
Decima：29 107 m n d1…dk
[范围]65≤ m ≤89（d1…dn长度取决于使用的条形码系统）
[描述]· 选定条形码系统并打印。
[注释]· n用来指示条码数据的个数，打印机将其后边n字节数据作为条码数据处理。
· 如果n超出了指定范围，则打印机停止该命令的处理，并将后续数据作为普通数据处理。
· 如果条码数据d超出了规定的范围，该命令无效。
· 如果条码横向超出了打印区域，无效。
· 这条命令不管由ESC2或ESC3命令设置的行高是多少，走纸距离都与设置 的条码高度相等。
· 这条命令只有在打印缓冲区没有数据时才有效，如果打印缓冲区有数据，该命令被忽略。
· 打印条码后，将打印位置设置在行首。

m选定条形码系统如下：

m条形码系统数据长度字符个数字符范围
65UPC-A固定11≤n≤120~948≤d≤57
66UPC-E固定6≤n≤70~948≤d≤57
67JAN13(EAN13)固定12≤n≤130~948≤d≤57
68JAN8(EAN8)固定7≤n≤80~948≤d≤57
69CODE39可变1≤n≤640~9, A~Z, SP, $,
%, *, +, -, ., /		48≤d≤57, 65≤d≤90, 32,
36, 37, 43, 45, 46, 47
70Code 2 of 5 Interleaved可变2≤n≤64
(偶数）		0~948≤d≤57
71CODABAR可变1≤n0~9, A~D, a~d,
$, +, -, ., /, :		48≤d≤57, 65≤d≤68, 97≤d≤100,
36, 43, 45, 46, 47, 58,
65≤d1≤68, 97≤d1≤100,
65≤dk≤68, 97≤dk≤100
72CODE93可变1≤n≤64
73CODE128可变2≤n≤64
81Code 2 of 5 Matrix可变1≤n≤640~948≤d≤57
82Code 2 of 5 Industrial可变1≤n≤640~948≤d≤57
83Code 2 of 5 IATA可变1≤n≤640~948≤d≤57
84Code 2 of 5 Datalogic可变1≤n≤640~948≤d≤57
85CODE11可变1≤n≤640~9, –48≤d≤57，45
86CODE39 xtended可变1≤n≤64
87GS1 DataBar固定n=130~948≤d≤57
88GS1 DataBar Expanded可变
89MSI Plessey可变1≤n≤640~948≤d≤57
  • GS v 0 m xL xH yL yH d1….dk 打印光栅位图
内容说明
[格式]ASCII：GS v 0 m xL xH yL yH d1…dk
Hex：1D 76 30 m xL xH yL yH d1…dk
Decimal：29 118 48 m xL xH yL yH d1…dk
[范围]0 ≤ m ≤ 3, 48 ≤ m ≤ 51
0 ≤ xL ≤ 255
0 ≤ xH ≤ 255 ; 在此 1≤(xL+xH×256)≤128
0 ≤ yL ≤ 255
0 ≤ yH ≤ 8 ; 在此 1≤(xL+xH×256)≤4095
0 ≤ d ≤ 255
k = (xL+xH×256) × (yL+yH×256）;（k≠0）
[描述]• m,设定光栅位图模式
• xL, xH,设定位图水平方向数据字节数(xL+xH×256)
• yL, yH,设定位图垂直方向数据字节数 (yL+yH×256)
[注释]• 标准模式下，打印缓冲区中有无数据时该命令都有效。
• 对于光栅位图打印，该命令不受打印模式影响(字符大小、粗体、重 叠、颠倒打印下划线、反白打印模式等)。
• 打印区域宽度受限于打印机最小宽度，当打印区域大于最小宽度，则打印区域以外的数据会被读入且被逐点丢弃。
• ESC a (设定对齐方式)设置对于光栅位图也有效。
• d指明位图数据。将要打印的点设定为1，不打印点设定为0。

m 值设定模式如下：(dpi: 每25.4 毫米 {1英寸}打印点数)

m模式垂直点密度水平点密度
0, 48普通203.2dpi203.2dpi
1, 49倍宽203.2dpi101.6dpi
2, 50倍高101.6dpi203.2dpi
3, 51四倍大小101.6dpi101.6dpi

光栅位图指令示例：

• 假设一张水平方向32点、垂直方向32点的图，要求以4倍大小打印，那么就可以得到一张64点*64点图片：
此时需要：m=3，xL=4，xH=0，yL=32，yH=0，dk数据排列如下图

• 格式数据如下：
GS v 0 3D 4D 0D 32D 0D FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH LF LF LF LF
• 转换后十六进制数据如下：
1D76300304002000FF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FF0A0A0A0A

  • GS ( k pL pH cn fn n1 n2 (cn=49,fn=65) 选择QR CODE模式
内容说明
[格式]ASCII：GS ( k pL pH cn fn n1 n2
Hex：1D 28 6B pL pH cn fn n1 n2
Decima：29 40 107 pL pH cn fn n1 n2
[范围](pL+pH×256)=4,(pL=4,pH=0)
cn = 49
fn = 65
n1 = 49, 50
n2 = 0
[描述]• 选择 QR CODE 的模式。
[默认值]n1 = 50，n2 = 0

•  选择 QR CODE 的模式n1说明如下：

n1功能
49选择计算算法为模式 1
50选择计算算法为模式 2
  • GS ( k pL pH cn fn n (cn=49,fn=67) 设置QR CODE模块大小
内容说明
[格式]ASCII：GS ( k pL pH cn fn n
Hex：1D 28 6B pL pH cn fn n
Decima：29 40 107 pL pH cn fn n
[范围](pL+pH×256)=3 (pL=3,pH=0)
cn = 49
fn = 67
1 ≤n≤16
[描述]• 设置 QR CODE 的模块大小n点
[默认值]n = 0
  • GS ( k pL pH cn fn n ( cn=49,fn=69) 设置QR CODE纠错等级
内容说明
[格式]ASCII：GS ( k pL pH cn fn n
Hex：1D 28 6B pL pH cn fn n
Decima：29 40 107 pL pH cn fn n
[范围](pL+pH×256)=3(pL=3,pH=0)
cn = 49
fn = 69
48≤ n ≤ 51
[描述]• 设置 QR CODE 的纠错等级。
[默认值]n=48

•  设置 QR CODE 的纠错等级n如下：

n功能参考：可恢复字码比例
48选择纠错等级 L7%
49选择纠错等级 M15%
50选择纠错等级 Q25%
51选择纠错等级 R30%
  • GS ( k pL pH cn fn m d1..dk ( cn=49,fn=80) 存贮QR CODE数据到符号存贮区
内容说明
[格式]ASCII：GS ( k pL pH cn fn m d1..dk
Hex：1D 28 6B pL pH cn fn m d1..dk
Decima：29 40 107 pL pH cn fn m d1..dk
[范围]4 ≤(pL + pH ×256) ≤ 7092 (0 ≤pL≤255 , 0≤pH ≤27 )
cn = 49
fn = 80
m = 48
0 ≤ d ≤ 255
K = (pL + pH × 256) – 3
[描述]• 存贮 QR CODE 的符号数据（d1..dk）到符号存贮区。
  • GS ( k pL pH cn fn m ( cn=49,fn=81) 打印QR CODE在符号存贮区的符号数据
内容说明
[格式]ASCII：GS ( k pL pH cn fn m
Hex：1D 28 6B pL pH cn fn m
Decima：29 40 107 pL pH cn fn m
[范围](pL+pH×256)=3 (pL=3 ,pH=0)
cn = 49
fn = 81
m = 48
[描述]• 编码并打印用 GS ( k (fn=80) 存贮在符号存贮区的 QR CODE 符号数据。
[注释]• 使用者必须留出打印 QR CODE 的足够的安全空白区域（包括由 QR CODE 符号规范中定义的上下、左右边空）。

云打印机对接说明

7. 需要了解的其他FAQ

a) 对接流程逻辑上如何保证打印机一定能够接到订单？

答：商米云打印机有如下流程来保证：

1、打印机接入商米云MQTT服务器，该服务器采用集群架构，由商米运维团队进行维护，具有多年百万量级的商米设备接入经验打磨而成，保证了订单消息的触发和推送。

2、打印机接到订单以后，会发起HTTP订单列表请求，而且将订单限制在5条以内，有效避免了高峰时期大量订单拥挤到打印机端，从而导致丢单的问题。

3、打印机获取订单列表以后，会按列表顺序一张一张订单拉取详情进行打印，而且只有在上一张打印完毕以后，才会打印下一张订单。

4、订单打印完毕以后，打印机还会上报打印结果给服务器，让服务器实时了解订单是否已经打印完成。未上报打印完成状态的订单还可以被再次拉取打印。

5、打印中途，如果因为纸用完了，在重新装纸以后，订单会从头再打印一遍，避免了内容缺失。

6、打印中途，如果因为断电，在重新开机以后，会主动到服务器上重新拉取未打印的订单来打印。

7、打印中途，如果因为断网，只有拉取完整的订单才会打印出来，拉取一半的订单是不会打印出来的。

8、打印途中，如果因为卡纸等故障，导致打印不完整。商家可以通过按键重打最后一张订单，免去操作软件的过程。

9、如果确实由于网络因素，打印机请求多次也没有拉取到新订单数据，可以在接收到第二个新订单消息时，还是会将第一个订单拉取并打印出来。

10、打印机采用弱网切换，可以自动寻找连接顺畅的网络进行连接，网络切换时间只需20秒。

11、打印机是否断网，云指示灯会提示目前服务器是否正常连接。

12、商家怀疑网络不好时，可以通过按键自检网络状态，打印机会打印出一张检测报告，告诉你哪里出了问题。

13、打印机网络真的出现短时间无法修复问题时，还可以使用商家手机版接单，然后通过手机蓝牙向打印机发送订单，利用蓝牙将订单打印出来。

b) 打印过程缺纸，订单会不会丢失？

答：当出现打印过程缺纸时，只要重新装好纸卷，未完成的票据将会自动完整的重新打印出来；

c) 打印过程卡纸了，订单打印不完整怎么办？

答：打印机提供按键重打功能，只要双击键就可以重新打印最后一张订单；

d) 如何进行打印机wifi配网？

答：商米云打印机采用的是蓝牙配网方式，这种方式可以有效避免手机和打印机不在同一个Wifi路由器环境下的跨网段配网问题。商米已经为开发者准备了3套蓝牙配网SDK，一套是用于安卓下的配网SDK，一套是用于苹果手机的配网SDK，还有一套是用于微信小程序的配网SDK。使用这三套SDK的基础原理都是让开发者很方便的调用蓝牙进行通讯，避免各种因为通讯异常造成的重连机制开发难度。

e) 店铺WIFI网络不好导致丢单怎么办？

答：网络状态因为影响因素众多，目前还没有终极的解决方案，所以购买WIFI+GPRS版本的打印机将自动带有弱网切换功能。在平时打印机将使用WIFI联网进行通讯，如果WIFI网络通讯不稳定时，打印机就会自动切换的GPRS网络进行通讯，等待WIFI恢复正常时再切换回来，避免了因此造成的订单无法接收的问题。因为GPRS的速率受限，接单体验上没有WIFI那么快，但因为GPRS属于备用通道，保证订单不丢失才是首要考虑的。

f) 打印机网络异常了，但手机上还能收到单，怎么打印出来？

答：商米云打印机支持云、USB、蓝牙事务打印模式，允许在连接网络打印的情况下，仍然可以通过USB和BT接收来自收银机和手机的数据进行打印。所以如果手机上有订单，可以让手机蓝牙连接打印机，将票据内容通过蓝牙发送给打印机打印即可。

g) 网络异常了，如何快速查找问题点？

答：网络状态因为影响因素众多，目前还没有终极的解决方案，所以打印机带有网络自检功能，只要双击键，稍等几秒就会有一张网络自检票据打印出来，从票据中的FAIL项就可以分析网络目前处于何种故障，将故障信息提供给技术人员解决；

检测信息信息说明故障解决
Current Network目前正在业务通讯的是WIFI网络还是GPRS网络。如若未配置WIFI，请忽略此异常。如果一直处于GPRS网络，说明WIFI通路有问题，就需要检查一下打印机WIFI配置是否正确，或者路由器是否工作正常。如若未配置WIFI，请忽略此异常。
Link=>SSID:目前连接的WIFI路由器SSID名称是什么，并且连接是否正常。连接上PASS，断开中FAIL。没有SSID名称就说明打印机并没有配置WIFI，需要重新执行WIFI配网过程。如果有SSID名称，那就需要检查该SSID名称的WIFI路由器工作是否正常，或者打印机重新进行WIFI配网。
Link=>GPRS目前的GPRS通道连接是否正常。连接上PASS，断开中FAILGPRS信号差，请将设备远离金属和多层墙壁的位置后，再次尝试。另GPRS连接速度比较慢，打印机刚开机还未连接上基站也会导致测试失败，稍等几分钟再测试一遍即可。
Check=>DHCP Conflict检查网络环境中是否存在多个DHCP情况，多个DHCP或没有DHCP会导致网络连接异常。只有一个DHCP时PASS，有多个DHCP时Warn，没有DHCP为FAIL本项依赖Link测试项为PASS情况下，FAIL的故障分析才有意义，否则请忽略以下分析内容。如若Link=>SSID项未FAIL，请先确保其为Pass。
Warn表示网络中私搭的WIFI路由器导致DHCP冲突，请检查网络中是否存在多个路由器开启了DHCP模式。如果是请关闭多余的DHCP，只保留一个可以连接外网的即可。
FAIL表示网络中没有配置DHCP服务器，打印机无法获得IP地址。请检查网络中的DHCP服务器是否故障。
Check=>IP Conflict检查网络环境中是否存在IP地址重复，多个IP地址相同会导致网络通讯异常。没有重复IP时PASS，有多个重复IP时FAIL本项依赖Link测试项为PASS情况下，FAIL的故障分析才有意义，否则请忽略以下分析内容。如若Link=>SSID项未FAIL，请先确保其为Pass。
网络中的多个DHCP服务冲突或者手工给设备配置IP地址时，就会引起IP地址冲突。请关闭多余的DHCP服务，或者找到冲突的IP地址设备，修改IP地址为使用DHCP分配。
Ping=>GW检查设备与网关之间的链路，从而判断内网连接是否正常。返回值是延迟值，通过延迟值判断网络的速率是否达标，如果网关不通时FAIL本项依赖Check测试项为PASS情况下，FAIL的故障分析才有意义，否则请忽略以下分析内容。如若Check=>DHCP Confilict项FAIL，请先确保其为Pass。
网关一般都指向了WIFI路由器或者基站本身，Ping值太高或者FAIL就需要检查WIFI路由器是否工作正常，或者移动基站信号不好。
Ping=>DNS检查设备与公网根DNS之间的链路，从而判断是否已经连接上外网。返回值是延迟值，通过延迟值判断网络的速率是否达标，如果网关不通时FAIL本项依赖Ping=>GW测试项为PASS情况下，FAIL的故障分析才有意义，否则请忽略以下分析内容。如若Link=>GPRS、Ping=>GW项均为FAIL，请先确保其为Pass。
DNS根服务器是互联网上的主节点，能Ping通说明打印机已经连上了互联网。Ping值太高或者FAIL就需要检查WIFI路由器是否工作正常，或者移动基站信号不好。
Ping=>MQTT Server检查设备与MQTT服务器的链路，从而判断是否已经连接上业务服务器。返回值是延迟值，通过延迟值判断网络的速率是否达标，如果网关不通时FAIL本项依赖Ping=>GW、Ping=>DNS测试项为PASS情况下，FAIL的故障分析才有意义，否则请忽略以下分析内容。如若Link=>GPRS、Ping=>GW项均为FAIL，请先确保其为Pass。
MQTT是订单推送服务器，能Ping通说明订单推送服务器链路正常。Ping值太高或者FAIL就需要咨询设备厂商客服人员进行检查。
Ping=>HTTP Server检查设备与HTTP服务器的链路，从而判断是否已经连接上业务服务器。返回值是延迟值，通过延迟值判断网络的速率是否达标，如果网关不通时FAIL本项依赖Ping=>GW、Ping=>DNS测试项为PASS情况下，FAIL的故障分析才有意义，否则请忽略以下分析内容。如若Link=>GPRS、Ping=>GW项均为FAIL，请先确保其为Pass。
HTTP是订单内容服务器，能Ping通说明订单服务器链路正常。Ping值太高或者FAIL就需要咨询设备厂商客服人员进行检查。
MQTT=>Check Config打印机通讯主要靠MQTT，所以会自动检查服务器信息是否正确，是否可以接收来自云的订单消息。信息正确时PASS，信息错误时FAIL本项依赖Ping=>HTTP测试项为PASS情况下，FAIL的故障分析才有意义，否则请忽略以下分析内容。如若Ping=>HTTPServer项为FAIL，请先确保其为Pass。
如果接入MQTT服务器的信息出现错误，就需要咨询设备厂商客服人员进行检查。
MQTT=>Connect打印机通讯主要靠MQTT，检查MQTT目前是否连接着，是否可以接收来自云的订单消息。连接上PASS，断开中FAIL本项依赖MQTT=>MQTT config测试项为PASS情况下，FAIL的故障分析才有意义，否则请忽略以下分析内容。如若MQTT=>Check Config项为FAIL，请先确保其为Pass。
如果接入MQTT连接出现错误，就需要咨询设备厂商客服人员进行检查。
MQTT=>R&W打印机通讯主要靠MQTT，检查MQTT通讯数据是否正常，是否可以接收来自云的订单消息。可以通讯PASS，无法通讯FAIL本项依赖MQTT=>MQTT Link测试项为PASS情况下，FAIL的故障分析才有意义，否则请忽略以下分析内容。如若MQTT=>Connect项为FAIL，请先确保其为Pass。
如果接入MQTT服务器的信息出现错误，就需要咨询设备厂商客服人员进行检查。

h) 打印机自检页如何操作？

答：需要完整查看打印机硬件信息，可以通过自检页了解，只要按下键再按下键后同时松开就可以打印出来；

i) 打印出来的票据是乱码，怎么回事？

答：商米云打印机目前支持全球字库打印，所以采用UTF8编码格式，所以传输的文字都要转码成UTF8才能打印出来。采用UTF8编码后就可以实现票据内容多语种混打，满足一些行业服务特定外国人群时的双语种打印问题。

j) 播报语音内容是否可以修改？

答：商米云打印机采用TTS语音合成技术，无论你发什么文字，都可以转换成语音播报出来。也就是说只要场景需要，票据的菜品、联系方式、备注都可以按照你的想法读出来。但由于一些多音字的存在，某些特定的语句可能无法按照你的期望正确发音，所以可以将文字替换成相同发音的非多音字来播报。

k) 如何变更wifi配置？

答：设备wifi配对以后，如果需要变更接入wifi节点，只需要重新执行配网即可，不用解除授权重新绑定。

l) 云打印机和别的外卖平台是否可以同时接单？

答：外卖平台的接入数量是依据饿了么和美团的规则而定，不是由云打印机自行决定的。饿了么允许多台打印机接入相同的账号，并且同时接单打印。而美团只允许一台打印机接入一个账号，如果授权绑定了别的平台，那原有的就会被强制解除授权。

m) GPRS版本送SIM卡吗，每个月有多少流量？

答：商米云打印机是内置eSIM，不需要另外使用插卡，是直接连接到2G网络的，没有流量限制。

n) 设备通过商米助手APP绑定了，还能解绑吗？

答：可以解绑的，在商米助手中点击设备右上角的小点，其中有删除设备。删除后可以使用另一个手机重新连接绑定。已经被绑定的就无法被另一个账号绑定的。

o) 绑定打印机时，提示“设备蓝牙连接失败”？

答：云打印机绑定时是使用蓝牙进行通讯的，提示“蓝牙连接失败”，一般是由于安卓版本的APP定位权限授权没有打开。进入 设置-应用-商米助手-权限-定位 打开。

p) 指示灯的功能？

答：云打印机有三个指示灯，第一个是绿色电源灯，只要上电就常亮；第二个是蓝色网络灯，连接上服务器就常亮，灭就表示网络不通；第三个是红色异常灯，发生缺纸、过热、异常就亮，故障排除就灭。

云打印机对接说明

4. 开发对接API接口（方案一：回调方式）

特别声明：

为更好的保护合作伙伴的数据隐私，又能实现完整的订单打印过程，需要商米与合作伙伴共同努力一起实现。以下文档约定了云打印机通讯的两部分接口，一部分为商米云提供的API接口，提供给合作伙伴调用，以完成设备绑定相关和消息推送相关功能；一部分为合作伙伴需要开放给商米云打印机调用的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×tamp=1589277365”;

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

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

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

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

常见错误码说明：

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

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

4.1 商米云API接口

基于合作伙伴数据隐私考虑，商米云不会直接获取打印数据，而是采用消息传递方式，由打印机直连合作伙伴云拉取所需数据进行打印。以下规范由商米云实现了几个基本功能接口，以完成设备绑定、订单消息通知、语音传递等相关功能。

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

API接口开发DEMO文档下载（PHP）

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设备已绑定，请检查是否已在商米助手绑定过，需在商米助手中解绑后才能执行本渠道绑定

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/newOrderNotice

请求方式：

  • POST

公共参数：

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

私有参数：

参数名类型说明
hasOrderint1-有新的订单
orderIdint订单Id （必填），用于按键重打订单时使用

成功返回示例：

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

成功返回参数说明：

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

失败返回示例：

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

失败错误码说明：

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

5)语音内容推送

接口名：

  • /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系统时间戳
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不属于该渠道设备

4.2 合作伙伴云API接口

基于合作伙伴数据隐私考虑，商米云不会直接获取打印数据，而是采用消息传递方式，由打印机直连合作伙伴云拉取所需数据进行打印。以下规范由合作伙伴云实现几个基本功能接口，以完成打印机设备获取订单数据进行打印。

请求URL地址：为了让打印机设备能够直连合作伙伴云API接口实现订单打印功能，需要事先提供可以正常调用的URL地址给到商米云。

API接口开发DEMO文档下载（GO语言）

1)获取订单列表

接口名：

  • printTicket/getPrintTicketOrderId

请求方式：

  • GET

参数：

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

返回示例（json）：

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

返回参数：

参数名说明
code1代表请求成功，-1代表请求失败
data返回数据库中五条订单id集合，若请求失败data为null
msg若请求失败，msg返回error信息，请求成功则msg为””

备注：为保证打印不漏单，订单id列表依照时间顺序每次最多返回5条订单id集合列表。打印机会将所有订单id内容依次打印完成后，再请求该接口获取需打印订单id列表，直至该接口返回为空停止。

2)获取订单详情

接口名：

  • printTicket/getPrintTicketInfo

请求方式：

  • GET

参数：

参数名类型说明
signstring签名，参考上面签名生成方式。注意：签名sign必须全部32位大写MD5
app_idstring商米提供的app_id
msnstring设备SN号
timeStampstringUnix时间戳（秒）
orderIdstring订单id

返回示例（json）：

{
    "code":1,
    "data":{
      "voiceCnt":1,  //语音播报次数
      "voice":"语音内容",  //语音播报内容，voice与voiceUrl内容只能使用一个，无数据时传""
      "voiceUrl":"http://xxx.xxx.xxx/playaudio.MP3",  //语音播报文件下载地址，voice与voiceUrl内容只能使用一个，无数据时传""。voice是内置语音播报的内容文本。voiceUrl为需要设备播放的语音文件，文件格式只能为MP3或WAV格式（MP3要求16bit单声道8000Hz采样率。WAV要求16bit单声道8000Hz采样率）
      "orderCnt":2,  //打印票据张数
      "data":"1B21306D4B8BD5310A",//使用ESCPOS指令字体倍高宽模式打印“测试1”内容，末尾还有一个回车指令
    },
    "msg":""
}

data说明：打印内容采用十六进制格式传输，所有文本内容采用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是换行

$data = bin2hex（strToUtf8（$str））;  //$data为：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）;
    }
}
```

返回参数：

参数名说明
code1 代表请求成功，-1代表请求失败
data 返回订单内容，若请求失败data为null；请求成功则返回：voiceCnt为语音播报次数，voice为语音播报内容，orderCnt为打印票据张数，data为订单打印数据
msg若请求失败，msg返回error信息，请求成功则msg为””

云打印机因为具有重打订单功能，该接口需要允许状态已经标记为打印成功的订单，仍然允许打印机根据订单ID请求订单详情，以完成重打动作。

3)更新订单状态

接口名：

  • printTicket/updatePrintTicketStatus

请求方式：

  • GET

参数：

参数名类型说明
signstring签名，参考上面签名生成方式。注意：签名sign必须全部32位大写MD5
app_idstring商米提供的app_id
msnstring设备SN号
timeStampstringUnix时间戳（秒）
orderIdstring订单id
statusint状态 1:订单打印成功、0:订单打印失败、-1:订单json格式错误、-2:data字段内容为空

返回示例（json）：

{
    "code":1,
    "data":"success",
    "msg":""
}

返回参数：

参数名说明
code1 代表请求成功，-1代表请求失败
data成功返回“success”，失败返回“fail”
msg若请求失败，msg返回error信息，请求成功则msg为””

云打印机对接说明

3. 下载配网SDK

安卓SDK DEMO下载链接：安卓配网SDK
微信小程序SDK下载链接：微信小程序配网SDK
IOS SDK DEMO下载链接： 苹果配网SDK

说明：云打印机配网、云绑定过程是通过蓝牙实现的，所以需要利用手机的蓝牙来进行指令的通讯。SDK里的SunmiPrinterClient类对蓝牙配网过程进行了封装，便于APP简单开发实现打印机配对。使用该功能时必须保证蓝牙打开且允许应用获取位置权限。下面是SDK接口的使用说明，具体使用可以参考DEMO。

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

3.1安卓配网SDK类说明

Android配网SDK包名：BluetoothBinding.aar

1)类声明

接口名：

  • SunmiPrinterClient

接口声明：

   SunmiPrinterClient sunmiPrinterClicent = SunmiPrinterClient(Context context, IPrinterClient iPrinterClient);

传入参数：

参数名类型说明
contextContext
iPrinterClientIPrinterClient云打印机蓝牙接口的回调类

2)统一处理回调接口

配置蓝牙打印机的过程中需要通过BLE给蓝牙打印机发送消息，这里采用统一的回调处理蓝牙数据发送情况。

接口名：

  • sendDataFail

回调方法：

   public void sendDataFail(int code, String msg) {

    }

回调参数：

参数名类型说明
codeint错误信息码 0-蓝牙连接失败 1-蓝牙Notify失败
msgString错误信息

3.2安卓配网SDK接口说明

1)开始扫描打印机

接口名：

  • startScan

接口声明：

   sunmiPrinterClient.startScan();

回调方法：

    public void onPrinterFount(PrinterDevice printerDevice) {

    }

回调参数：

参数名类型说明
printerDevicePrinterDevice蓝牙打印机类 扫描到的打印机数据中只有默认的名称和蓝牙mac地址

2) 停止扫描打印机

接口没有回调，建议在当前页面销毁或者开始配置打印机前停止扫描

接口名：

  • stopScan

接口声明：

   sunmiPrinterClient.stopScan();

3) 获取蓝牙打印机SN

接口名：

  • getPrinterSn

接口声明：

   sunmiPrinterClient.getPrinterSn(btAddress);

传入参数：

参数名类型说明
btAddressString打印机的蓝牙MAC地址

回调方法：

  • 方法一：
   public void getSnRequestSuccess() {

    }

说明：该方法表示发送获取SN的命令成功，等待获取SN，该方法内可以加入超时机制

  • 方法二：
   public void onSnReceived(String sn) {

    }

回调参数：

参数名类型说明
snString打印机的sn

4)获取打印机搜索到的WIFI列表

接口名：

  • getPrinterWifiList

接口声明：

   sunmiPrinterClient.getPrinterWifiList(btAddress);

传入参数：

参数名类型说明
btAddressString打印机的蓝牙MAC地址

回调方法：

  • 方法一：
   public void routerFound(Router router) {

    }

回调参数：

参数名类型说明
routerRouter打印机搜索到的WIFI类
Router类参数说明
参数名类型说明
———
nameStringWIFI的名字
hasPwdbooleanWIFI是否有密码
pwdStringWIFI的密码，此时获取到的WIFI没有该数据
rssiintWIFI的信号强度范围0到4，越大信号越强
essidbyte[]WIFI的essid，配网时需要该参数
  • 方法二：
public void onGetWifiListFinish() {

    }

说明：蓝牙打印机搜索WIFI结束

  • 方法三：
public void onGetWifiListFail() {

    }

说明：蓝牙打印机搜索wifi失败

5)给打印机配置wifi

接口名：

  • setPrinterWifi

接口声明：

   sunmiPrinterClient.setPrinterWifi(btAddress, ssid, psw);

传入参数：

参数名类型说明
btAddressString打印机的蓝牙MAC地址
ssidbyte[]WIFI的essid
pwdStringWIFI的密码

回调方法：

  • 方法一：
   public void onSetWifiSuccess() {

    }

说明：打印机收到需要配置的WIFI信息，开始尝试连接WIFI，这里建议添加超时机制

  • 方法二：
   public void wifiConfigSuccess() {

    }

说明：打印机设置WIFI成功

  • 方法三：
   public void onWifiConfigFail() {

    }

说明：打印机设置WIFI失败，一般是输入的WIFI密码不正确导致

6)退出配网过程

说明：该方法只有统一的发送蓝牙信息失败的回调，该方法建议在onBackPressed方法中调用

接口名：

  • quitConfig

接口声明：

   sunmiPrinterClient.quitConfig(btAddress);

传入参数：

参数名类型说明
btAddressString打印机的蓝牙MAC地址

7)请求删除wifi 配置，并使用2G网络

说明：该方法只有统一的发送蓝牙信息失败的回调，如果打印机使用2G网络，不采用WIFI就可以调用该方法。

接口名：

  • deleteWifiInfo

接口声明：

   sunmiPrinterClient.deleteWifiInfo(btAddress);

传入参数：

参数名类型说明
btAddressString打印机的蓝牙MAC地址

8)断开和蓝牙打印机的蓝牙连接

说明：该方法需要在页面销毁的时候进行调用

接口名：

  • disconnect

接口声明：

   sunmiPrinterClient.disconnect(btAddress);

传入参数：

参数名类型说明
btAddressString打印机的蓝牙MAC地址

3.3微信小程序配网SDK引入

说明：使用该功能必须保证已经打开了手机蓝牙

把sdk.js文件放入需要引入接口的文件夹里

	const sdk = require('../blueConnect/sdk.js');

3.4微信小程序配网SDK接口说明

1)初始化蓝牙模块，开始扫描周围的设备

接口名：

  • openBluetoothAdapter

接口声明：

  //接口的参数是一个回调函数status
  sdk.openBluetoothAdapter((res) =› {
      console.log('蓝牙打开结果', res);
    });

回调参数：

参数名参数值说明
status0蓝牙模块初始化成功
status10001蓝牙模块初始化失败，用户没有打开手机蓝牙

2)获取周围的蓝牙设备列表

接口名：

  • onBluetoothDeviceFound

接口声明：

  //接口的参数是一个回调函数devicesList
  sdk.onBluetoothDeviceFound((devicesList) =› {
      console.log('devicesList', devicesList);
    })

回调参数：

参数名参数值说明
devicesList[ ]数组

3)停止扫描周围的蓝牙设备

接口名：

  • stopScanDevices

接口声明：

	sdk.startScanDevices();

4)关闭蓝牙模块，调用该方法将断开所有已建立的连接并释放系统资源

接口名：

  • closeBluetoothAdapter

接口声明：

	sdk.startScanDevices();

5)连接蓝牙设备

接口名：

  • createBLEConnection

接口声明：

	sdk.createBLEConnection(deviceId, (res) =› {
      this.setData({
        canWrite: res.canWrite,
        deviceId: res.deviceId,
        characteristicId: res.characteristicId,
        connected: res.connected,
      })
      console.log('设备连接成功', res)
    });

接口参数：

参数名参数值说明
deviceIdstring可以通过onBluetoothDeviceFound 接口获得设备列表，每个设备信息里面有deviceId

回调参数：

参数名参数值说明
status0连接成功特征值获取成功，并且有下面的参数
10001连接失败
10002连接成功，获取特征值失败（设备不支持特征值读写）
characteristicIdstring特征值ID
deviceIdstring设备ID
serviceIdstring服务ID

6)获取云打印机SN号

接口名：

  • getSN

接口声明：

  //接口的参数是一个回调函数
  sdk.getSN((data) =› {
      console.log('sn', data);
      this.setData({
        sn: data
      });
    });

回调参数：

参数名参数值说明
datastringSN号字符串

7)获取云打印机设备搜索到的Wi-Fi列表

接口名：

  • getWifiList

接口声明：

  //接口的参数是一个回调函数
	sdk.getWifiList((data) =› {
      this.setData({
        wifiList: data
      })
      console.log('wifiList', data);
    });

回调参数：

参数名参数值说明
data[ ]数组，每个元素都是Wi-Fi信息，含有ssid(Wi-Fi名称)、mode（Wi-Fi模式）、rssi（Wi-Fi强度）、complete（完整的回复指令信息）

8)连接指定Wi-Fi

接口名：

  • connectWifi

接口声明：

	sdk.connectWifi(essid, password, (res) =› {
      console.log('Wi-Fi连接结果打印', res);
    });

接口参数：

参数名参数值说明
essidstringWi-Fi名称
passwordstringWi-Fi密码

回调参数：

参数名参数值说明
status0Wi-Fi连接成功
10001Wi-Fi连接出错,请检查Wi-Fi账号、密码

9)退出配网设置

接口名：

  • cancelConnect

接口声明：

	sdk.cancelConnect();

10)删除Wi-Fi配置

接口名：

  • deleteWifi

接口声明：

	sdk.cancelConnect();

11)断开蓝牙连接

接口名：

  • closeBLEConnection

接口声明：

	sdk.closeBLEConnection();

3.5 IOS配网SDK接口说明

说明：此SDK在真机或模拟器环境中均可使用；建议使用与iOS12或以上系统版本中

1)SDK集成

  • 1、目前SDK只支持手动集成。
  • 2、将SDK中包含的 libSunmiPrinterManager.a、SunmiPrinterDeviceModel.h、 SunmiPrinterManager.h 三个文件导入到Xcode工程目录下。
  • 3、在需要使用API的类中 importSunmiPrinterManager.h头文件，并增加 PrinterManagerDelegate协议。
   #import "PrinterSettingController.h"
   #import "SunmiPrinterManager.h"
   @interface PrinterSettingController ()‹PrinterManagerDelegate›
   @property (nonatomic, strong) SunmiPrinterManager *printerSettingManager;
   @end

2)SDK内属性以及主要方法使用方法说明

为理解SDK各个方法的使用，大致梳理蓝牙打印机正常配置流程的步骤，如下：

  • 1）打开手机蓝牙开关
  • 2）搜索蓝牙打印机
  • 3）连接蓝牙打印机
  • 4）向蓝牙打印机获取设备SN（绑定设备时使用）
  • 5）向蓝牙打印机获取Wi-Fi列表
  • 6）向蓝牙打印机发送ssid和password，为设备配置Wi-Fi网络
  • 7）配网步骤完成

3)搜索蓝牙打印机设备

说明：SDK在手机打开蓝牙后会自动搜寻蓝牙打印机设备。用户可以通过SunmiPrinterManager类的connectState属性来获取当前手机的蓝牙状态。当检测到手机蓝牙是开启状态时，用户可通过 shouldSearchDevice属性，来控制是否自动搜索蓝牙打印机，默认false，不会开始自动搜索。

方法一：开始扫描

实例方法说明
-(void)scanPeripheral;扫描蓝牙打印机设备

当搜索到设备时，会执行代理方法：

协议方法说明
-(void)discoveredDevice : (SunmiPrinterDeviceModel*_Nonnull) device;扫描到打印机设备，可以在此协议方法中获取扫描到的设备

方法二：取消扫描

实例方法说明
-(void)cancelScan;取消扫描蓝牙打印机设备

取消搜索之后，执行代理方法：

协议方法说明
– (void)didCancelSearching;取消了扫描打印机设备的操作，在此代理方法中做其他逻辑处理

4)连接蓝牙打印机设备

方法一：连接设备

实例方法说明
– (void)connectPeripheral:(CBPeripheral*_Nonnull)peripheral;建立蓝牙打印机设备的连接

连接设备成功时，执行代理方法

协议方法说明
– (void)didConectPrinter;连接上了蓝牙打印机设备

方法二：断开连接设备

实例方法说明
-(void)disConnectPeripheral;断开和蓝牙打印机设备的连接

要断开和蓝牙打印机的连接时，会执行代理方法

协议方法说明
– (void)willDisconnectPrinter;将要断开和蓝牙打印机设备的连接

5)获取蓝牙打印机的SN

方法：

实例方法说明
-(void)getPrinterSN;向蓝牙打印机发送获取设备SN的指令，此方法获取的SN，将会在蓝牙打印机的绑定操作中使用

协议方法一：

协议方法说明
– (void)willStartReceiveDeviceSn;表明已经开始发送获取SN的指令，可以利用此方法建立超时机制

协议方法二：

协议方法说明
– (void)receiveDeviceSn:(NSString*_Nullable)sn;获取接收到的SN

6)获取打印机搜索到的WIFI列表

方法一：

实例方法说明
-(void)getWifiList;向蓝牙打印机发送获取Wi-Fi列表的指令

协议方法一：

协议方法说明
– (void)receiveAPInfo:(NSDictionary*_Nullable)apInfo;重写此代理方法，接收获取到的Wi-Fi网络信息。demo中会将接收到的Wi-Fi网络以列表形式展示出来

协议方法二：

协议方法说明
– (void)didReceiveAllApInfo;在接收到蓝牙打印机发送的全部Wi-Fi网络信息时，会执行此代理方法

协议方法三：

协议方法说明
– (void)didFailReceiveApInfo;若过程中接收失败，会触发此代理方法，在此方法内可做其他的自定义处理

7)选择某一个Wi-Fi网络为蓝牙打印机配置网络

方法一：

实例方法说明
-(void)connectAP:(NSString*_Nonnull)ssid password:(NSString*_Nullable)password;发送Wi-Fi的网络的ssid和password给蓝牙打印机，为蓝牙打印机配置网络

协议方法一：

协议方法说明
– (void)willStartConfigPrinter;表示配置网络的命令已经发给蓝牙打印机，可以在该法内加入超时机制

协议方法二：

协议方法说明
– (void)configPrinterSuccess;配网成功的代理方法，可以在此方法内做后续操作

协议方法三：

协议方法说明
– (void)configPrinterFail;配网失败的代理方法，可以在此方法内做后续其他操作

方法二：

协议方法说明
– (void)quitConnectAP;使用此方法，退出配网流程

8)删除网络配置

方法：

协议方法说明
– (void)deleteWifiSetting;使用此方法，删除Wi-Fi网络配置

云打印机对接说明

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

  • a) 合作伙伴业务需基于商米云提供的安全保障前提下，所以要求合作伙伴需要拥有一个商米合作伙伴平台账户。

关于注册合作伙伴流程请参考：https://docs.sunmi.com/developers/registration-for-partners/

  • b) 要求打印机设备在商米公司出库时渠道一定要选择该账户下，否则打印机会因归属权问题无法进行下一步绑定业务。

云打印机对接说明

特别声明：

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

1. 了解一下对接流程

1.1 方案一：回调方式

  • ①在 https://partner.sunmi.com/ 注册一个合作伙伴平台账户，并获得账户；开通商米云打印机通道服务，并获得服务APP_ID、APP_KEY，用于接口API调用时使用；待合作伙伴接口开发上线后，还需要提供一个合作伙伴云URL给到商米云服务，用于让打印机回调合作伙伴API接口完成打印业务；
  • ②合作伙伴业务APP中，“商米配网SDK”提供了一个简单易用的蓝牙配置WIFI联网开发过程，简单调用就可以让打印机连接上云端；
  • ③SDK配网过程会自动获得打印机设备SN号，这个SN是设备的唯一标识符，利用它就可以绑定对应的商家账号完成业务通讯；
  • ④合作伙伴业务APP中，使用SN号去合作伙伴云建立设备与商家店铺的关联关系；
  • ⑤合作伙伴业务APP中，使用SN号调用商米云API绑定接口，建立设备SN与合作伙伴ID、商铺ID的关联关系；
  • ⑥合作伙伴云对接商米订单推送、声音推送等API接口，建立起消息通讯通道；
  • ⑦商米云在接收到推送消息以后，会自动向打印机下发业务消息；
  • ⑧打印机在收到触发消息以后，使用之前提供的合作伙伴云URL去回调API接口获取订单的打印内容，并打印出来；
  • ⑨打印业务对接完成以后，如果还需要进一步管理设备时，可以在合作伙伴业务APP中直接调用商米“设备管理页面”进行打印管理。更多的打印机设置内容将不断的完善，让商家可以获得更好的体验。

1.2 方案二：直推方式

  • ①在 https://partner.sunmi.com/ 注册一个合作伙伴平台账户，并获得账户；开通商米云打印机通道服务，并获得服务APP_ID、APP_KEY，用于接口API调用时使用；
  • ②合作伙伴业务APP中，“商米配网SDK”提供了一个简单易用的蓝牙配置WIFI联网开发过程，简单调用就可以让打印机连接上云端；
  • ③SDK配网过程会自动获得打印机设备SN号，这个SN是设备的唯一标识符，利用它就可以绑定对应的商家账号完成业务通讯；
  • ④合作伙伴业务APP中，使用SN号去合作伙伴云建立设备与商家店铺的关联关系；
  • ⑤合作伙伴业务APP中，使用SN号调用商米云API绑定接口，建立设备SN与合作伙伴ID、商铺ID的关联关系；
  • ⑥合作伙伴云对接商米订单推送、声音推送等API接口，建立起消息通讯通道，推送打印、语音数据；
  • ⑦商米云在接收到推送消息以后，会自动向打印机下发业务消息；
  • ⑧打印业务对接完成以后，如果还需要进一步管理设备时，可以在合作伙伴业务APP中直接调用商米“设备管理页面”进行打印管理。更多的打印机设置内容将不断的完善，让商家可以获得更好的体验。

特殊代码说明

一、获取商米设备标识

商米建议通过获取到以下内容来判断是否商米设备：

1.设备的品牌名 brand（如：SUNMI）

    商米的品牌名统一为 SUNMI

2.设备的系统型号 model（如：V1-B18）

    系统型号组成为 产品型号+硬件特性+‘-’+软件特性

    其中以V、M、P、L开头为手持设备，以T、D、S开头为横屏设备（截至2017年12月） 

3.设备的ROM版本号（如：1.1.0）。

4.设备的ROM顺序号（如：128）。

可以下载Demo，仿照Demo在自己项目src下面新建android.os包(固定写法)，将SystemProperties.java放入该包下，按以下方法获取指定的值：

获取brand的代码为:

    String brand = SystemProperties.get("ro.product.brand");

获取model的方法为:

    String model = SystemProperties.get("ro.product.model");

获取ROM版本号的代码为:

    String versionname = SystemProperties.get("ro.version.sunmi_versionname");

获取ROM顺序号的方法为:

    String versioncode = SystemProperties.get("ro.version.sunmi_versioncode");

 

二、获取设备的SN号

1.在AndroidManifest.xml中添加如下权限。

2.在需要的地方用以下代码获取商米SN号。

public static String getSN() {
        if (Build.VERSION.SDK_INT ›= Build.VERSION_CODES.O) {
            return Build.getSerial();
        } else
            return Build.SERIAL;
    }

三、隐藏及恢复底部导航栏

（注：商米新开发了Kiosk霸屏模式，APP不用做任何修改，仅通过云端设置即可实现隐藏状态栏、导航栏并无法通过手势唤出。   该功能在T2、K1设备上已实现，其他设备上线进展请联系技术支持400-902-1168（9:00-21:00）。   建议合作伙伴使用商米Kiosk霸屏模式，已获得更好的体验）

Android系统默认提供了隐藏系统的导航栏的方法，但对于Dialog的支持较差，导致全屏对话框打开时先弹出导航栏再隐藏（闪屏），SunmiOS针对此问题进行了修复（V1系统固件版本252后支持，T1系统固件版本132后支持）

1.Activity的全屏化

——安卓默认支持

public class MainActivity extends AppCompatActivity {
    @Override
    public void onWindowFocusChanged(boolean hasFocus) {
        super.onWindowFocusChanged(hasFocus);
        SystemUIUtils.setStickFullScreen(getWindow().getDecorView());
    }
}
public class SystemUIUtils {

    public static void setStickFullScreen(View view) {
        int systemUiVisibility = view.getSystemUiVisibility();
        int flags = View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
                | View.SYSTEM_UI_FLAG_LAYOUT_STABLE
                | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
                | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION // hide nav bar
                | View.SYSTEM_UI_FLAG_FULLSCREEN // hide status bar
                | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY;
        systemUiVisibility |= flags;
        view.setSystemUiVisibility(systemUiVisibility);
    }

}

2.Dialog的全屏化

——原生系统下 AOSP 的Bug会导致全屏对话框打开时先弹出导航栏然后再隐藏导航栏（闪屏）。

public AlertDialog create(boolean fullscreen) {
    LayoutInflater inflater = LayoutInflater.from(context);

    final AlertDialog dialog = new AlertDialog(context,
            R.style.DialogStyle);

    if(fullscreen){
        SystemUIUtils.setStickFullScreen(dialog.getWindow().getDecorView());
    }
}

3.设置隐藏后显示导航栏

3.1.全局底部上划

——上划后底部导航栏显示4s，4s后底部导航栏隐藏

3.2.切换应用至其他APP（如APP内跳转至第三方应用、第三方APP弹窗等）

——切换至其他APP是否显示底部导航栏以第三方应用要求为准，切换至自己APP时底部导航栏消失

四、避免重复申请外设权限

当APP需要通过USB关联外设来实现业务时（比如连接USB打印机打印小票），安卓要求用户手动确认设备使用权限，来保障用户信息安全，防止木马非法入侵USB设备。

1.如何避免USB设备重新插拔同一个外设时，APP反复申请该外设权限

需要用户手动确认时，勾选“默认情况下用于该USB设备”，无法通过代码绕过该安全机制

验证DEMO

2.如何避免设备重启后，已勾选“默认情况下用于该USB设备”的APP仍反复申请同一个外设的使用权限

2.1.在APP的AndroidManifest中指定某个Activity部分中，添加如下代码

2.2.在该目录下创建xml文档

其中，class的值需要和要连接的外设类型一致，外设class参照表如下


    /**
     * USB class indicating that the class is determined on a per-interface basis.
     */
    public static final int USB_CLASS_PER_INTERFACE = 0;
    /**
     * USB class for audio devices.
     */
    public static final int USB_CLASS_AUDIO = 1;
    /**
     * USB class for communication devices.
     */
    public static final int USB_CLASS_COMM = 2;
    /**
     * USB class for human interface devices (for example, mice and keyboards).
     */
    public static final int USB_CLASS_HID = 3;
    /**
     * USB class for physical devices.
     */
    public static final int USB_CLASS_PHYSICA = 5;
    /**
     * USB class for still image devices (digital cameras).
     */
    public static final int USB_CLASS_STILL_IMAGE = 6;
    /**
     * USB class for printers.
     */
    public static final int USB_CLASS_PRINTER = 7;
    /**
     * USB class for mass storage devices.
     */
    public static final int USB_CLASS_MASS_STORAGE = 8;
    /**
     * USB class for USB hubs.
     */
    public static final int USB_CLASS_HUB = 9;
    /**
     * USB class for CDC devices (communications device class).
     */
    public static final int USB_CLASS_CDC_DATA = 0x0a;
    /**
     * USB class for content smart card devices.
     */
    public static final int USB_CLASS_CSCID = 0x0b;
    /**
     * USB class for content security devices.
     */
    public static final int USB_CLASS_CONTENT_SEC = 0x0d;
    /**
     * USB class for video devices.
     */
    public static final int USB_CLASS_VIDEO = 0x0e;
    /**
     * USB class for wireless controller devices.
     */
    public static final int USB_CLASS_WIRELESS_CONTROLLER = 0xe0;
    /**
     * USB class for wireless miscellaneous devices.
     */
    public static final int USB_CLASS_MISC = 0xef;
    /**
     * Application specific USB class.
     */
    public static final int USB_CLASS_APP_SPEC = 0xfe;
    /**
     * Vendor specific USB class.
     */
    public static final int USB_CLASS_VENDOR_SPEC = 0xff;

3.如何避免前两步后设置后，业务页面会因USB设备插入而刷新

安卓原生逻辑导致用户选择“默认情况下用于该USB设备”会导致USB设备插入时打开某个指定activity。如果要避免页面刷新导致业务中断，可以增加如下代码防止页面刷新。

 

五、如何避免自己的应用数据被清除

应用数据默认是可以通过系统设置删除的，删除后应用将恢复刚安装的状态。但是可以通过配置APP来精细管理应用数据（比如按照业务分类或时间删除数据），也可以避免重要的应用数据被删除。

Screenshot-3.png
Screenshot-2.png

在程序的manifest文件的application中加上manageSpaceActivity属性，并且指定一个Activity，这个Activity就是点击管理空间之后会跳转的那个Activity了。

PS 如果要避免数据被删除，可以创建一个自动关闭的Activity。

public class ManageSpaceActivity extends Activity {  
  
    @Override  
    protected void onCreate(Bundle savedInstanceState) {  
        super.onCreate(savedInstanceState);  
  
        finish();  
  
    }// onCreate  
}

七、如何避免插入usb外设导致app界面闪烁

在APP的AndroidManifest中，添加如下代码

android:configChanges="navigation|keyboardHidden|keyboard"

八、如何避免扫描枪扫出内容与实际不一致

一般情况下，文本框输入的所有内容会提交给输入法进行转换（如拼音、联想等），有的输入法经过转换后会转义部分字词导致输入内容不一致。

除了更换系统输入法为合适的输入法外，还可以利用输入法通常不对密码框进行处理的规则，调整文本框类型为“可见密码”（inputType），并且约定好可输入规范（digits）也可以避免该问题