文字识别离线SDK

商米文字识别离线SDK获取方式:发送邮件至AI部门(meijuan@sunmi.com)获取,可附带试用授权申请,邮件可参考如下示例:

需要商米文字识别离线SDK 
使用场景描述:XXX
设备SN:XXX
授权申请:通用OCR能力试用授权 

1. 概述

商米文字识别离线SDK是一种面向安卓设备的技术开发包,主要功能为印刷文字识别,可以识别票据、卡证、关键字符串、各类文件等文本信息。本文档介绍了SDK的使用说明以及数据结构和接口的定义,便于开发者在调用SDK接口时参考。

1.1 功能介绍

商米文字识别离线SDK主要提供文本识别模块,能够精准识别文本内容进行文字检测和识别提取,将其转化成计算机可编码文本。SDK提供简单易用,功能完善的接口,满足各类场景不同需求。

1.2 开发SDK的说明

文件/文件夹名说明
models/模型的配置文件
libocr-release.aarSDK lib库相关代码的aar

2. 环境信息

系统环境平台编译环境
Android7及以上arm64, arm32Android studio

3. Java SDK使用说明

3.1 获取授权文件

商米文字识别离线SDK的授权需要绑定Android系统信息。在第一次使用前,开发者需要获取OCR识别SDK的license授权文件,请参考文档试用&购买授权

3.2 导入SDK包

在Android Studio项目中导入SDK aar包即可。

3.3 存放模型文件

模型文件可以存放在SD卡某个路径下,也可以存放在APP文件路径下。请务必保证模型所在路径可以被访问。

3.4 配置config.json文件

使用模型包中config.json文件作为模板,或者自行创建一个config.json文件,拷贝如下代码,并根据模型存放的实际路径进行修改。SDK需通过读取此config.json配置文件进行初始化。

注:需要修改为绝对路径。

{
  "det_model_path": "mobile_v1.1_det_opt.nb",    //文字检测模型路径
  "rec_model_path": "mobile_v1.1_rec_opt.nb",    //文字识别模型路径
  "cls_model_path": "mobile_v1.1_cls_opt.nb",    //文字方向模型路径
  "char_list_file": "keys_v1.txt",               //识别字典
  "thread_num": 4                                //执行识别的线程数
  "application": 1                               //应用代号
}

3.5 创建SDK Handle

在配置和使用SDK前,需要创建Handle。以下为代码示例。

SunmiOCRSDK.createHandle();

3.6 初始化SDK

以下为SDK调用init接口执行初始化的示例。init接口参数为3.4中的config.json文件的路径。

int ret = SunmiOCRSDK.init(confPath);

3.7 验证授权文件

使用类似如下代码读取授权文件内容到Java String中,再通过verifyLicense接口验证。若验证通过,可正常调用SDK其他接口。若验证失败,调用SDK其他接口将返回授权错误代码。错误代码为“6”,则表示授权文件无效;错误代码为“7”,则表示授权文件过期。如有授权问题,请联系商米解决。

注:通过无线网连接获取的license,需保证wifi开关为打开状态。

String licence = readToString(licencePath);
int ret = SunmiOCRSDK.verifyLicense(context, licence); // context为Android Context

3.8 配置SDK

商米文字识别离线SDK参数都可动态配置,建议先通过getConfig得到当前参数,根据需要将参数修改完成后,再用setConfig接口进行设置。示例代码如下:

SunmiOCRConfigParam param = new SunmiOCRConfigParam();
SunmiOCRSDK.getConfig(param);param.setDetMaxSideLen(960);
int ret = SunmiOCRSDK.setConfig(param);

3.9 释放内存

在SDK调用过程中,通过调用SunmiOCRTextArrayGetItem方法得到的对象,都需要调用delete方法释放内存,否则会造成内存泄漏 。示例代码如下:

SunmiOCRText text = SunmiOCRLib.SunmiOCRTextArrayGetItem(text_ary, 0);
text.delete();

3.10 执行OCR

OCR步骤:

  1. 获取的Bitmap图片:用户根据需求,从摄像头获取bitmap转换为BGR像素buffer传给SDK。(灰度图需要扩展为BGR后再输入到SDK)
  2. 获取text文本数据:根据图片,使用getImageTexts获取文本信息。
  3. 获取text文本内容和对应的置信度:根据text.getText()获取文本,再根据text.getScore()获取对应的置信度。

示例代码:

// 将bitmap转为 BGR byte数组
byte[] srcData = OCRUtils.getPixelsBGR(bitmap);
// 构造OCR输入
SunmiOCRImage image = new SunmiOCRImage(srcData, bitmap.getHeight(), bitmap.getWidth(), 0);
// 设置OCR功能
image.setPredictMode(SunmiOCRMode.PredictMode_Det+SunmiOCRMode.PredictMode_Rec);
// 设置ROI [可选]
SunmiOCRDetRoi detRoi = image.getDetRoiBox();
detRoi.setX1(120);
detRoi.setY1(240);
detRoi.setX2(640);
detRoi.setY2(960);
image.setDetRoiBox(detRoi);
// 构造OCR输出
SunmiOCRImageTexts texts = new SunmiOCRImageTexts();
// 执行OCR
int ret = SunmiOCRSDK.getImageTexts(image, texts);
// 判断OCR是否正常运行
if (ret ! = SunmiOCRStatusCode.OCR_CODE_OK) {
    Log.d(TAG, "SunmiOCRSDK.getImageTexts error code " + ret);
    return;
}
// 获取识别出的文本
SunmiOCRText text_ary = texts.getTexts();
for (int i = 0; i ‹ texts.getTextsCount(); i++) {
    SunmiOCRText text = SunmiOCRLib.SunmiOCRTextArrayGetItem(text_ary, i);
    Log.d(TAG, text.getText() + " " + text.getScore());
    text.delete();
}

4. Java接口定义

4.1 类接口定义

4.1.1 SunmiOCRStatusCode 商米OCR识别状态码

成员变量说明
OCR_CODE_OK0正确
OCR_CODE_UNINIT1SDK没有初始化
OCR_CODE_EMPTY_IMAGE2图片为空
OCR_CODE_NO_MODEL3无加载模型
OCR_CODE_CONFIG_ERROR4配置错误
OCR_CODE_LOW_IMAGE_QUALITY5OCR图像模糊
OCR_CODE_LICENSE_ERROR6授权文件无效
OCR_CODE_LICENSE_EXPIRED7授权文件过期
OCR_CODE_IMAGE_BUFFER_ERROR8输入图像尺寸或通道数错误
OCR_CODE_CONFIG_APPLICATION_NOT_SUPPORT9config.json文件中,application设置错误
OCR_CODE_LICENSE_APPLICATION_NOT_AUTHORIZED10config.json文件中,application无权限使用
OCR_CODE_IMAGE_ROI_ERROR11ROI设置错误
OCR_CODE_IMAGE_PREDICT_MODE_ERROR12Predict Mode设置错误
OCR_CODE_OTHER_ERROR1000其他错误

4.1.2 SunmiOCRMode 执行功能选择

成员变量说明
PredictMode_None0不执行任何功能
PredictMode_Det1 << 0对传入图片进行ocr文字检测
PredictMode_Rec(1 << 1) 对传入图片进行ocr文字识别
PredictMode_DetRecPredictMode_Det + PredictMode_Rec对传入图片先进行ocr文字检测,再对检测出的文本框执行ocr文字识别

4.1.3 SunmiOCRRecRoi OCR Rec指定区域

成员类型说明
x1_, y1_floatOCR框左上角坐标点的横纵坐标
x2_, y2_floatOCR框右上角坐标点的横纵坐标
x3_, y3_floatOCR框右下角坐标点的横纵坐标
x4_, y4_floatOCR框左下角坐标点的横纵坐标

4.1.4 SunmiOCRDetRoi OCR Det指定区域

成员类型说明
x1_, y1_floatOCR框左上角坐标点的横纵坐标
x2_, y2_floatOCR框右下角坐标点的横纵坐标

4.1.5 SunmiOCRDirection OCR文本方向

成员类型说明
label_int0: 0度; 1: 180 度
score_float置信度

4.1.6 SunmiOCRImage OCR输入图像

成员类型说明
buf_unsigned char *图片像素字节地址
buf_len_int字节缓冲区长度
img_w_int图像宽度
img_h_int图像高度
max_text_count_int单图文本数最大返回值
predict_mode_int需要执行的功能选择
rec_roi_box_SunmiOCRRecRoi用于指定图像中需要识别的区域,仅在Mode为PredictMode_Rec或PredictMode_Rec+PredictMode_Cls时有效
det_roi_box_SunmiOCRDetRoi用于指定图像中需要检测的区域,仅在Mode=PrecideMode_Det+n有效,n为其他Mode。

4.1.7 SunmiOCRDirectionType 文本方向类型

成员变量说明
OCR_DIRECTION_00角度为0度
OCR_DIRECTION_1801角度为180度

4.1.8 SunmiOCRTextBox 文本框位置坐标

成员类型说明
x1_, y1_floatOCR框左上角坐标点的横纵坐标
x2_, y2_floatOCR框右上角坐标点的横纵坐标
x3_, y3_floatOCR框右下角坐标点的横纵坐标
x4_, y4_floatOCR框左下角坐标点的横纵坐标
score_float置信度

4.1.9 SunmiOCRText 单个文本框OCR结果

成员类型说明
box_SunmiOCRTextBoxOCR矩形框
text_[SunmiOCR_TEXT_MAX_LEN]char文字识别结果
char_scores_[SunmiOCR_TEXT_MAX_LEN]float单个字符的识别置信度数组
char_count_int字符个数
score_float置信度
direction_SunmiOCRDirectionOCR文字方向

4.1.10 SunmiOCRImageTexts 图片中所有OCR结果

成员类型说明
texts_SunmiOCRText *OCR文字
texts_count_intOCR文字个数

4.1.11 SunmiOCRConfigParam OCR配置参数

成员类型说明
det_max_side_len_int文本检测时图片长边的最大长度
rec_max_side_len_int文本识别时图片长边的最大长度
det_db_thresh_float文本检测阈值
det_db_box_thresh_float文本框筛选阈值
det_db_unclip_ratio_float文本检测框扩大比例
cls_thresh_float方向分类阈值
image_quality_threshold_float图像质量阈值

4.2 函数接口定义

4.2.1 getVersion

函数定义:public static String getVersion()

函数功能:获取Sunmi OCR SDK版本号

返回值:SDK版本字符串

4.2.2 getDeviceFingerprint

函数定义:public static String getDeviceFingerprint(Context context)

函数功能:获取Android设备指纹

函数输入:

变量类型说明
contextContext android context

返回值:设备指纹字符串

4.2.3 createHandle

函数定义:public static void createHandle()

函数功能:创建句柄

4.2.4 releaseHandle

函数定义:public static int release()

函数功能:释放句柄

返回值:status code

4.2.5 init

函数定义:public static int init(String configPath)

函数功能:初始化SDK

函数输入:

变量类型说明
configPathString 配置文件路径

返回值:status code

4.2.6 verifyLicense

函数定义:public static int verifyLicense(Context context, String license)

函数功能:验证许可证

函数输入:

变量类型说明
contextContext Android context
licenseString 许可证字符串

返回值:status

4.2.7 getErrorString

函数定义:public static String getErrorString(int code)

函数功能:获得错误字符串

函数输入:

变量类型说明
codeint 错误代码

返回值:错误描述字符串

4.2.8 getConfig

函数定义:public static int getConfig(SunmiOCRConfigParam config)

函数功能:获取当前SDK配置

函数输入:

变量类型说明
configSunmiOCRConfigParam SDK配置参数

返回值:status code

4.2.9 setConfig

函数定义:public static int setConfig(SunmiOCRConfigParam config)

函数功能:Set configuration

函数输入:

变量类型说明
configSunmiOCRConfigParam SDK配置参数

返回值:status code

4.2.10 getImageTexts

函数定义:public static int getImageTexts(SunmiOCRImage image, SunmiOCRImageTexts texts)

函数功能:进行文本检测和识别

函数输入:

变量类型说明
imageSunmiOCRImage 输入图像
textsSunmiOCRImageTexts OCR文本

返回值:status code

4.2.11 releaseImageTexts

函数定义:public static int releaseImageTexts(SunmiOCRImageTexts texts)

函数功能:释放SunmiOCRImageTexts

函数输入:

变量类型说明
textsSunmiOCRImageTexts OCR文本

返回值:status code

自动草稿

应用公钥生成方法

推荐使用 OpenSSL 工具生成密钥,以下是使用 OpenSSL 工具生成 RSA 公私钥对的方法:

Windows

打开命令行终端(推荐使用 Git Bash,Git官方客户端默认集成了 OpenSSL 工具),分别执行如下命令生成 RSA 公私钥对。

//生成私钥
# openssl.exe genrsa -out /your/path/app_private_key.pem 2048  
//生成对应公钥
# openssl.exe rsa -in /your/path/app_private_key.pem -pubout -out /your/path/app_public_key.pem

Linux和Mac

打开命令行终端,分别执行如下命令生成 RSA 公私钥对。

//生成私钥
$ openssl genrsa -out /your/path/app_private_key.pem 2048  
//生成对应公钥
$ openssl rsa -in /your/path/app_private_key.pem -pubout -out /your/path/app_public_key.pem

在 /your/path/ 文件夹下面可以看到 app_private_key.pem(RSA私钥)和 app_public_key.pem(RSA 公钥)2个文件。将RSA私钥保留,将RSA公钥配置到商米开放平台用于验证签名。以下为私钥文件和公钥文件示例。

RSA 私钥文件示例

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAtI2kf6XdO09so4Wt+IlZwy4OVpPwYJn4DXtb0bs+Q0WoLi+o
xTwDV9l3fNekUWv5Ux/XOd4D1mNzRb/uBXNWjSckAK0c5n3P3yX2XAfQmHfNdg5F
Cjb78bHQYhm59WiyDXFBXOpfiGejjQCK5yptMzuVOAOGC89kSOVgLKddSxOa+ZSN
bD6g5gexxYY4zpHkyVJwzX2jOVEt+FciMAtxMVxY4HkkVWC19YhMJTBVJRBeHSeH
pdt5xwtvKynOlTgpZSDm+Nx4ifhNVSmuMU7R0pCJFtO9UQx9WKnERCOxRsY/QEHZ
rYBmGTSByzaKsKnk6puG3wEsFFqyBOE8MO29JwIDAQABAoIBAAd2l2cjXwq1lMMJ
opBUdR5pR/RyNwx3MNa106zOtZsoRPRryeklOuolthe1/jfTY8H43fepYrU49Snb
7iXRh7Fb/dP9U+V/K9mIgy94rzmuMhMAMgBjF3T9KaT0dUhcpIeDt/T0RzCnQA5z
CErX6R2mB9wB4UeZsgaFXL1bybJxsjpd55FKdLTUPtuI9mnf85j07e+Ov0MNP5+R
3orFzK/zn4hBdEGZ2j5Yw4kUq3iJ8vfQgWO2bgOXLQV76i03kMpZKdmMZbt0sj/J
JVVjgRkhPcYa2a3KB0z8VoZzEw+g9oidZdbEQ8paVC2Zr50fXxxWw7iYEgld/7+R
bppMYPECgYEA4RLLI2bWjg9HUSPDuwxKF47NV2hxxQhC9YKfSQHdJ7+ugtvOZ++T
WCA+nWKiI0DwgU0BP0fKVKw/56w+4qJdZNKe3YCa4jNheoWt8LT+FMXuM1/AXvPC
oUWH5Hs2bW3LHdL4pqk8DBACQeq/UG62Wx1NDDEyd2le17Rkg39vQakCgYEAzVzN
9NKobaBS+e5qhEt1rxeBVFEK2HI2UbVdTpU/cUCCgmW4M3ZUU7PtvtbysMjea7ga
EqvDTYx12shBa8tgxJSXYA8N9r3uc+MaHFAa09u+4gPAInxP5i9T0PfuWcyxmCiX
Tsi46W2jaP2t1Abj7Hy1wwgrQYaZFu4AV/N06k8CgYBjLdPj6roa6XKkt5zVfMnd
bajgnn6bs1NGOmQUWMTqchXlRhTDShfkmnjdA4ys+j3AzH0DNJBdFXYnkYg4eBGt
jv5AXx5hFQEca3HFgwv/fWTEsKnlbYbTZ/9E2GKYf+wkXUYCsspqClfkUhwxxkeH
CPddqwQxCHapmK0+INaW2QKBgQCFDmIrA+o4zS213bGJ8dJYFaSn2rJqNuXW3umL
psuqNx/YGMvWHA7bBLM/eMlZnWvu4yORgVRTBHS/wgwRKX6TH6tMg7SKb9j1oOkj
+wrGxZPRoJh2P5ENFRD7TghSintumK4gT5DvPSgpOGPOAoDekpa5vKs6E1lRL/dt
BMJ1pQKBgHQoD8slchB6unKjpgw2et2hVdv31ns/kYUkUEoBht1uY+QN280E3gBD
X51509HcaWP7d1pW7xGA1aVt25STlTUwg8Lttp11bSxWHCesbVIGK/hY8LApVkMr
m4WHMurr+uZ9g34kjyfgCMaeT0arFU+NO6U3tYPZk03H3JDd/uY+
-----END RSA PRIVATE KEY-----

RSA 公钥文件示例

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtI2kf6XdO09so4Wt+IlZ
wy4OVpPwYJn4DXtb0bs+Q0WoLi+oxTwDV9l3fNekUWv5Ux/XOd4D1mNzRb/uBXNW
jSckAK0c5n3P3yX2XAfQmHfNdg5FCjb78bHQYhm59WiyDXFBXOpfiGejjQCK5ypt
MzuVOAOGC89kSOVgLKddSxOa+ZSNbD6g5gexxYY4zpHkyVJwzX2jOVEt+FciMAtx
MVxY4HkkVWC19YhMJTBVJRBeHSeHpdt5xwtvKynOlTgpZSDm+Nx4ifhNVSmuMU7R
0pCJFtO9UQx9WKnERCOxRsY/QEHZrYBmGTSByzaKsKnk6puG3wEsFFqyBOE8MO29
JwIDAQAB
-----END PUBLIC KEY-----

自动草稿

Basic Configuration Interfaces

  1. Set Wireless Network Parameters
  2. 设置无线参数(无需签名校验)
  3. 获取无线参数
  4. 获取无线扫描AP列表
  5. 获取无线扫描AP列表 (无需签名校验)
  6. 获取IP参数
  7. 设置IP参数
  8. 调焦
  9. 手动聚焦
  10. 自动聚焦
  11. 调焦聚焦复位
  12. 获取调焦和聚焦参数
  13. 设置夜视模式
  14. 获取夜视模式
  15. 设置动态侦测
  16. 获取动态侦测参数
  17. 设置IPC名称
  18. 获取IPC名称
  19. 设置指示灯开关
  20. 获取指示灯开关
  21. 设置画面旋转角度
  22. 获取画面旋转角度
  23. 获取支持的画面旋转角度
  24. 格式化存储卡
  25. 获取存储卡状态
  26. 获取人脸算法参数
  27. 设置人脸算法参数
  28. 获取人流统计参数
  29. 设置人流统计参数

1. Set Wireless Network Parameters

Description

This interface is used to configure the SSID and the password used to connect an IPC and its AP.

Interface

public void setWifiConf(String deviceId, String ssid, String password, RpcCallback‹RpcResponse› callback);

Parameters

Parameter Description Example
deviceIdIPC SNC201D98T00094
ssid The name of the wireless AP to be connected (SSID), which shall not exceed 32 characters. WeWork
password The password of the AP to be connected. If there is no password, leave it empty (shall not exceed 64 characters, and it does not support WEP). 12345678
callback The calling result.

Response Parameter

Field Type Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 100, 101. Please refer to RPCErrorCode Class for details.

2. Set Wireless Network Parameters (No Signature Authentication Required)

Description

After using this interface, you don’t have to verify (through signature authentication) the SSID and password used to connect an IPC and its AP before activation; an activation will invalidate this interface.

Interface

public void setWifiConfWithoutAuth(String deviceId, String ssid, String password, RpcCallback‹RpcResponse› callback);

Parameters

Parameter Description Example
deviceIdIPC SNC201D98T00094
ssidThe name of the wireless AP to be connected (SSID), which shall not exceed 32 characters. WeWork
passwordThe password of the AP to be connected. If there is no password, leave it empty (shall not exceed 64 characters, and it does not support WEPs). 12345678
callbackThe calling result.

Response Parameter

FieldType Description
codeintThe return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 100, 101. Please refer to RPCErrorCode Class for details.

3. Get Wireless Network Parameters

Description

This interface is used to get the wireless network parameters of the IPC.

Interface

public void getWifiConf(String deviceId, RpcCallback‹RpcResponse‹WifiConfiguration›› callback);

Parameters

Parameter Description Example
deviceId IPC SN C201D98T00094
callback The calling result.

Response Parameters

Field Type Description
codeintThe return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 100, 101. Please refer to RPCErrorCode Class for details.
dataWifiConfiguration This field shows only when the return code indicates a successful operation. Please refer to RPCResponse.WifiConfBean for details.

Sample Callback

The implementations of subsequent interface callbacks are similar to this one.

new RpcCallback‹RpcResponse‹WifiConfiguration››() {
    @Override
    public void onComplete(RpcResponse‹WifiConfiguration› result) {
        if (result.code() == RpcErrorCode.SUCCESS) {
            WifiConfiguration wifiConf = result.data();
        } else {
            shotToast("response.code: " + result.code());
        }
    }

    @Override
    public void onError(Throwable t) {
        shotToast("Exception: " + t.getMessage());
    }
});

4. Get the List of APs

Description

This interface is used to get the list of APs wirelessly scanned by the IPC.

Interface

public void getApList(String deviceId, RpcCallback‹RpcResponse‹ScanResultCollection›› callback);

Parameters

ParameterDescription Example
deviceIdIPC SNC201D98T00094
callbackThe calling result.

Response Parameters

Field Type Description
codeint The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 100, 101. Please refer to RPCErrorCode Class for details.
dataScanResultCollectionThis field shows only when the return code indicates a successful operation. Please refer to RpcResponse.ScanResultCollection for details.

5. Get the List of APs (No Signature Authentication Required)

Description

This interface is used to get the list of APs wirelessly scanned by the IPC without any signature authentication. An activation will invalidate this interface.

Interface

public void getApListWithoutAuth(String deviceId, RpcCallback‹RpcResponse‹ScanResultCollection›› callback);

Parameters

ParameterDescription Example
deviceIdIPC SNC201D98T00094
callbackThe calling result.

Response Parameters

FieldType Description
codeint The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 100, 101. Please refer to RPCErrorCode Class for details.
dataScanResultCollectionThis field shows only when the return code indicates a successful operation. Please refer to RpcResponse.ScanResultCollection for details

6. Get IP Parameters of IPC

Description

This interface is used to get the IP parameters of IPC

Interface

public void getIpConfiguration(String deviceId, RpcCallback‹RpcResponse‹IpConfiguration›› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
callbackThe calling result.

Response Parameters

Field Type Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7. Please refer to RPCErrorCode Class for details.
dataIpConfiguration This field shows only when the return code indicates a successful operation. Please refer to RpcResponse.IpConfiguration for details

7. Set IP Parameters of IPC

Description

This interface is used to set the IP parameters of IPC

Interface

public void setIpConfiguration(String deviceId, Map‹String, String› options, RpcCallback‹RpcResponse› callback);

参数说明

ParameterDescription Example
deviceIdIPC SNC201D98T00094
optionsConfigurable parameter set for dynamic detectionSee option description in the table below
callbackThe calling result.

option description

Name TypeDescriptionRequiredExample
protoStringDHCP or static Y static
ipaddrString IP address N192.168.1.102
netmaskString Subnet Mask N 255.255.255.0
gatewayString Gateway N 192.168.1.1
dns1 String dns1 server ip N 202.96.128.86
dns2String dns2 server ip N202.96.134.166

Response Parameter

FieldType Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7. Please refer to RPCErrorCode Class for details.

8. Adjust Focal Length

Description

This interface is used to adjust the focal length according to the actual environment, in order to zoom in or zoom out. All interfaces such as focusing and focusing are only supported by zoom lens. At present, only SUNMI AI camera supports zoom lens.

Interface

public void setZoom(String deviceId, int zoom, RpcCallback‹RpcResponse› callback);

Parameters

Parameter DescriptionExample
deviceIdIPC SNC201D98T00094
zoomThe focal length. An appropriate one ranges [0, 500]. 200
callbackThe calling result.

Response Parameter

FieldTypeDescription
codeintThe return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 110. Please refer to RPCErrorCode Class for details.

9. Manual Focus

Description

The lens will automatically focus after the focal length has been adjusted. However, you can adjust the focus manually with this interface when a slight modification is needed.

Interface

public void manualFocus(String deviceId, int focus, RpcCallback‹RpcResponse› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
focusThe focus parameter (the value of manual adjustment). An appropriate one ranges [0, 780]. 200
callbackThe calling result.

Response Parameter

Field Type Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 110. Please refer to RPCErrorCode Class for details.

10. Auto Focus

Description

IPC will automatically focus after the focal length has been set. This interface is used to set the autofocus point.

Interface

public void autoFocus(String deviceId, int focus_x, int focus_y, RpcCallback‹RpcResponse› callback);

Parameters

Parameter Description Example
deviceIdIPC SNC201D98T00094
focus_x The percentage indicating the pixel of the focus point in x axis. An appropriate one ranges [0, 100]. 50
focus_y The percentage indicating the pixel of the focus point in y axis. An appropriate one ranges [0, 100]. 50
callbackThe calling result.

Response Parameter

Field Type Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 112. Please refer to RPCErrorCode Class for details.

11. 调焦聚焦复位

描述

用户可以通过此接口直接复位焦距和聚焦的参数。

接口

public void resetZoomFocus(String deviceId, RpcCallback‹RpcResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

字段名称 类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7,见错误码的描述

12. 获取调焦和聚焦参数

描述

获取当前IPC镜头的调焦聚焦参数。

接口

public void getZoomFocusConf(String deviceId, RpcCallback‹RpcResponse‹LensConfiguration›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

参数名称类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7,见错误码的描述
dataLensConfiguration返回码成功才会有此字段,详见RpcResponse.LensConfiguration

13. 设置夜视模式

描述

配置镜头的夜视模式。

接口

public void setIrMode(String deviceId, int irmode, RpcCallback‹RpcResponse› callback);

参数说明

参数名称描述 示例
deviceIdIPC序列号C201D98T00094
irmode 0表示关闭,1表示开启,2表示自动。一般选2。 2
callback调用结果

响应参数

字段名称 类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7、113,见错误码的描述

14. 获取夜视模式

描述

获取当前IPC的夜视模式。

接口

public void getIrMode(String deviceId, RpcCallback‹RpcResponse‹IrConfiguration›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

参数名称类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7,见错误码的描述
dataIrConfiguration返回码成功才会有此字段,详见RpcResponse.IrConfiguration

15. 设置动态侦测

描述

IPC的动态侦测支持根据画面变化和声音变化灵敏度来检测和报警,通过本API可以设置相关灵敏度和动态侦测的时间。

接口

public void setMotionDetectConfig(String deviceId, Map‹String, String› options, RpcCallback‹RpcResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
options可设置的动态侦测的参数集合,option说明中的所有参数都需要转换成String类型传入。见下表option说明
callback调用结果

option说明

参数名称 类型 描述 是否必须 示例
motion_level int范围[0, 3],0表示关闭,数值越大,越灵敏。 Y 2
audio_level int 范围[0, 3],0表示关闭,数值越大,越灵敏。 Y 2
weekday int 以周为一个循环,用0xYY来表示选择哪一天,具体是0x80直接表示7×24小时,其余的,
以7bit来表示哪一天被选上,0x01表示选择周一,0x02表示选择周二,0x40表示选择
周天,0x7f表示选择一个礼拜的7天,与0x80的区别只是0x80直接默认724小时,而
0x7f选了7天后,还可以设置具体的开始时间和结束时间。
Y 128(0x80 的十进制)
start_time long用分钟来表示,以一天24小时为例,以分钟为最小粒度,总共24*60这样的时间数值,
60表示01:00,121表示02:01,依次类推。范围[0,1440]
Y 200
stop_time long 用分钟来表示,以一天24小时为例,以分钟为最小粒度,总共24*60这样的时间数值,
60表示01:00,121表示02:01,依次类推。范围[0,1440]
Y 400

响应参数

字段名称 类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7,见错误码的描述

16. 获取动态侦测参数

描述

获取当前IPC镜头的动态侦测参数。

接口

public void getMotionDetectConfig(String deviceId, RpcCallback‹RpcResponse‹MotionDetectConfig›› callback);

参数说明

本接口没有私有参数,公共参数见HTTP接口调用

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

参数名称类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7,见错误码的描述
dataMotionDetectConfig返回码成功才会有此字段,详见RpcResponse.MotionDetectConfig

17. 设置IPC名称

描述

用户可以设置IPC的名称,以便区分不同的IPC设备。

接口

public void updateName(String deviceId, String name, RpcCallback‹RpcResponse› callback);

参数说明

参数名称描述 示例
deviceIdIPC序列号C201D98T00094
name 36个字符以内,12汉字以内 示例名称
callback调用结果

响应参数

字段名称 类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7、118,见错误码的描述

18. 获取IPC名称

描述

获取当前IPC的名称。

接口

public void getName(String deviceId, RpcCallback‹RpcResponse‹IpcName›› callback);

参数说明

本接口没有私有参数,公共参数见HTTP接口调用

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

参数名称类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7,见错误码的描述
dataIpcName 返回码成功才会有此字段,详见RpcResponse.IpcName

19. 设置指示灯开关

描述

设置指示灯是否需要关闭。

接口

public void setLedSwitch(String deviceId, int ledSwitch, RpcCallback‹RpcResponse› callback);

参数说明

参数名称描述 示例
deviceIdIPC序列号C201D98T00094
led_switch 0表示关闭指示灯,1表示开启指示灯,即可以亮 1
callback调用结果

响应参数

字段名称 类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7、119, 见错误码的描述

20. 获取指示灯开关

描述

获取当前IPC的指示灯状态。

接口

public void getLedSwitch(String deviceId, RpcCallback‹RpcResponse‹LedConfiguration›› callback);

参数说明

本接口没有私有参数,公共参数见HTTP接口调用

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

参数名称类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7, 见错误码的描述
dataLedConfiguration返回码成功才会有此字段,详见RpcResponse.LedConfiguration

21. 设置画面旋转角度

描述

设置拍摄的画面是否需要旋转一定角度,可用的旋转角度可通过获取支持的画面旋转角度获取到。

接口

public void setRotation(String deviceId, int rotation, RpcCallback‹RpcResponse› callback);

参数说明

这里只列出接口的私有参数,公共参数见HTTP接口调用

参数名称描述 示例
deviceIdIPC序列号C201D98T00094
rotation 画面旋转角度
对于FM010,支持的参数有0,90,180,270;
对于FM020,支持的参数有0,180
180
callback调用结果

响应参数

字段名称 类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7、120, 见错误码的描述

22. 获取画面旋转角度

描述

获取当前IPC当前的画面旋转角度。

接口

public void getRotation(String deviceId, RpcCallback‹RpcResponse‹Rotation›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

参数名称类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7, 见错误码的描述
dataRotation返回码成功才会有此字段,详见RpcResponse.Rotation
对于FM010,支持的参数有0,90,180,270;
对于FM020,支持的参数有0,180

23. 获取支持的画面旋转角度

描述

获取当前IPC设备支持的画面旋转角度。

接口

public void getSupportRotationAngles(String deviceId, RpcCallback‹RpcResponse‹SupportRotations›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

参数名称类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7, 见错误码的描述
dataSupportRotations返回码成功才会有此字段,详见RpcResponse.SupportRotations
对于FM010,支持的参数有0,90,180,270;
对于FM020,支持的参数有0,180

24. 格式化存储卡

描述

格式化插入IPC里面的存储卡。

接口

public void formatMemoryCard(String deviceId, RpcCallback‹RpcResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

参数名称类型 描述
code int 返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7、220、221, 见错误码的描述

25. 获取存储卡状态

描述

获取IPC上存储卡状态

接口

public void getMemoryCardStatus(String deviceId, RpcCallback‹RpcResponse‹ExternalStorage›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

类型 描述
int返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7, 见错误码的描述
ExternalStorage返回码成功才会有此字段,详见RpcResponse.ExternalStorage

26. 获取人脸算法参数

描述

获取人脸算法参数,目前仅支持人脸图像优选时间参数。

接口

public void getAiFaceConfig(String deviceId, RpcCallback‹RpcResponse‹AiFaceConfig›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

类型 描述
int返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7, 见错误码的描述
AiFaceConfig返回码成功才会有此字段,详见RpcResponse.AiFaceConfig

27. 设置人脸算法参数

描述

设置人脸算法参数,目前仅支持人脸图像优选时间参数。

接口

public void setAiFaceConfig(String deviceId, Map‹String, String› options, RpcCallback‹RpcResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
options人脸算法相关参数,option说明中的所有参数都需要转换成String类型传入。见下表option说明。
callback调用结果

option说明

参数名称类型描述是否必须示例
optimize_secondsint人脸图像优选时间,人脸算法从人脸出现后在指定的时间范围内选取人脸图像质量较好的进行识别,单位:秒,取值范围[1,6]。Y6

响应参数

类型 描述
int返回码,表示操作的结果;
本接口返回码有:0、1、3、5、7, 见错误码的描述

28. 获取人流统计参数

描述

获取IPC的人流统计参数,目前包含人脸识别去重间隔和人脸识别模式两个参数。

接口

public void getPeopleFlowStatConfig(String deviceId, RpcCallback‹RpcResponse‹PeopleFlowStatConfig›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

字段名称类型描述
codeint返回码,表示操作的结果;
本接口返回码有:0、1、2、3、5、7,见错误码的描述
dataPeopleFlowStatConfig返回码成功才会有此字段,详见RpcResponse.PeopleFlowStatConfig

29. 设置人流统计参数

描述

设置IPC的人流统计参数,目前包含人脸识别去重间隔和人脸识别模式两个参数。

接口

public void setPeopleFlowStatConfig(String deviceId, Map‹String, String› options, RpcCallback‹RpcResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
options人流统计参数,option说明中的所有参数都需要转换成String类型传入。见下表option说明
callback调用结果

option说明

名称类型描述是否必须示例
facerecog_intervalint人脸识别去重间隔,取值[0,86400]。N60
customer_judgemodeint人脸识别模式,0-抓拍模式,1-正常模式,2-未划线。N0

响应参数

字段名称类型描述
codeint返回码,表示操作的结果;
本接口返回码有:0、1、2、3、5、7,见错误码的描述

增值服务-巡店服务 接口

1 概述

为了方便Saas合作伙伴可以直接在其平台上使用商米提供的巡店服务业务数据,平台提供了巡店统计数据接口。Saas合作伙伴可以通过接口调用获取巡店业务的统计数据。

2 接口规范

2.1 协议说明

对接的openAPI接口目前只开放HTTPS方式,所有的消息一律采用POST方式。

注:消息体大小不得超过1M,超过1M的请求,直接拒绝!

Content-Typeapplication/x-www-form-urlencoded
数据格式返回为JSON格式
字符编码UTF-8字符编码
签名算法MD5
签名规则参考2.2 签名规则

2.2 签名规则

参考《鉴权认证》文档。

2.3 公共参数

参数名必填类型说明
app_idstring唯一标识接入身份,联系商米数字店铺提供
randomstring随机字符串,由数字和字母组成,长度范围为6-10位
timestampint当前的unix timestamp,精度到秒级,10位数字
signstring签名信息,详见2.2

3 巡店数据统计接口

3.1 接口描述

巡店数据统计接口用于Saas合作方获取巡店服务的各种数据统计。

3.2 接口列表

接口名称接口描述
/service/patrol/stat/groupByInspector获取巡检人巡查工作情况统计
/service/patrol/stat/groupByShop 获取门店下巡查工作数据统计
/service/patrol/stat/groupByTemplate获取模板使用情况数据统计
/service/patrol/stat/groupByCheckItem获取模板-检查项使用情况数据统计

3.3 接口详情

3.3.1 获取巡检人巡查工作数据统计

接口描述:通过本接口调用,可以获取到指定门店下基于巡检人统计的巡检人工作数据统计

接口链接:/service/patrol/stat/groupByInspector

接口版本:v2.0

接口参数:

参数名称是否必须类型说明示例
sunmi_shop_no string商米数字店铺平台的门店组织编号560279010307
periodint统计周期1

period参数说明:

参数取值说明
1近7天数据统计
2近30天数据统计
3近90天数据统计
4近180天数据统计
5近365天数据统计

请求示例:

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/service/patrol/stat/groupByInspector",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值:

{
    "data": {
        "patrol_inspector_summary_list": [
            {
                "inspection_user_name": "小明",
                "plan_task_undone_count": 0,
                "plan_task_done_count": 7,
                "plan_task_doing_count": 0,
                "plan_task_total_count": 28,
                "check_total_count": 349,
                "check_done_count": 2,
                "total_time_duration": 295645,
                "task_normal_count": 7,
                "task_non_count": 1602,
                "task_total_count": 1609,
                "task_realtime_count": 699,
                "task_snapshot_count": 523,
                "task_evaluate_count": 40,
                "last_inspection_time": 1600867095
            },
            {
                "inspection_user_name": "xiaohong",
                "plan_task_undone_count": 0,
                "plan_task_done_count": 3,
                "plan_task_doing_count": 0,
                "plan_task_total_count": 12,
                "check_total_count": 9,
                "check_done_count": 4,
                "total_time_duration": 2101,
                "task_normal_count": 3,
                "task_non_count": 81,
                "task_total_count": 84,
                "task_realtime_count": 26,
                "task_snapshot_count": 42,
                "task_evaluate_count": 7,
                "last_inspection_time": 1599535469
            },
            {
                "inspection_user_name": "kunkun",
                "plan_task_undone_count": 0,
                "plan_task_done_count": 0,
                "plan_task_doing_count": 0,
                "plan_task_total_count": 0,
                "check_total_count": 0,
                "check_done_count": 0,
                "total_time_duration": 21,
                "task_normal_count": 0,
                "task_non_count": 2,
                "task_total_count": 2,
                "task_realtime_count": 0,
                "task_snapshot_count": 0,
                "task_evaluate_count": 2,
                "last_inspection_time": 1597661382
            },
            {
                "inspection_user_name": "小白",
                "plan_task_undone_count": 0,
                "plan_task_done_count": 0,
                "plan_task_doing_count": 0,
                "plan_task_total_count": 0,
                "check_total_count": 14,
                "check_done_count": 0,
                "total_time_duration": 13994,
                "task_normal_count": 0,
                "task_non_count": 48,
                "task_total_count": 48,
                "task_realtime_count": 0,
                "task_snapshot_count": 0,
                "task_evaluate_count": 48,
                "last_inspection_time": 1599542974
            }
        ]
    },
    "code": 0,
    "msg": "succeed"
}

返回参数说明:

参数名类型说明
inspection_user_namestring巡检人姓名
plan_task_undone_countint计划任务过期未执行数
plan_task_done_countint计划任务已完成数
plan_task_doing_count int计划任务待执行数
plan_task_total_count int计划任务总数
check_total_countint应审核问题总数
check_done_countint 审核完成数
total_time_durationint 巡检时长(秒)
task_normal_countint任务巡店次数
task_non_countint非任务巡店次数
task_total_countint巡店总次数
task_realtime_countint实时巡店次数
task_snapshot_countint抓拍巡店次数
task_evaluate_countint门店考评次数
last_inspection_timeint最后一次巡检时间(秒)

错误码:

错误码说明

3.3.2 获取门店下巡查工作数据统计

接口描述:通过本接口调用,可以获取到指定门店下基于门店统计的巡检工作数据统计

接口链接: /service/patrol/stat/groupByShop

接口版本:v2.0

接口参数:

参数名称是否必须类型说明示例
sunmi_shop_no string商米数字店铺平台的门店组织编号列表560279010307
periodint统计周期1

period参数:

参数取值说明
1近7天数据统计
2近30天数据统计
3近90天数据统计
4近180天数据统计
5近365天数据统计

请求示例:

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/service/patrol/stat/groupByShop",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值:

{
    "data": {
        "patrol_shop_summary_list": [
            {
                "check_total_count": 0,
                "scoreless_total_count": 0,
                "avg_score": 5.58,
                "rectify_count": 438,
                "rectify_done_count": 398,
                "realtime_need_count": 393,
                "realtime_total_count": 777,
                "snapshot_problem_count": 286,
                "snapshot_total_count": 645,
                "evaluate_need_count": 45,
                "evaluate_total_count": 126
            }
        ]
    },
    "code": 0,
    "msg": "succeed"
}

返回参数说明:

参数名类型说明
check_total_countint考评检查项总数
scoreless_total_countint有问题检查项数
avg_scorefloat考评得分,百分制
rectify_countint应整改问题数
rectify_done_countint整改完成数
realtime_need_countint 实时巡店需整改数
realtime_total_countint 实时巡店总次数
snapshot_problem_countint抓拍巡检有问题数
snapshot_total_countint抓拍巡检总次数
evaluate_need_countint门店考评需整改数
evaluate_total_countint门店考评总次数

错误码:

错误码说明

3.3.3 获取模板使用情况数据统计

接口描述: 通过本接口调用,可以获取到指定门店下基于门店统计的巡检工作数据统计

接口链接: /service/patrol/stat/groupByTemplate

接口版本:v2.0

接口参数:

参数名称是否必须类型说明示例
sunmi_shop_no string商米数字店铺平台的门店组织编号列表560279010307
periodint统计周期1

period参数说明:

参数取值说明
1近7天数据统计
2近30天数据统计
3近90天数据统计
4近180天数据统计
5近365天数据统计

请求示例:

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/service/patrol/stat/groupByTemplate",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值:

{
    "data": {
        "patrol_template_summary_list": [
            {
                "template_id": "549755813846",
                "template_name": "你好世界",
                "total_score": 3925,
                "total_full_score": 5240,
                "total_count": 126
            }
        ]
    },
    "code": 0,
    "msg": "succeed"
}
参数名类型说明
template_idint模板id
template_namestring模板名称
total_scoreint门店下模板累计得分
total_full_scoreint 门店下模板累计总分
total_countint总共使用次数

错误码:

错误码说明

3.3.4 获取模板-检查项使用情况数据统计

接口描述: 通过本接口调用,可以获取到指定门店下基于模板统计的巡检工作数据统计

接口链接: /service/patrol/stat/groupByCheckItem

接口版本:v2.0

接口参数:

参数名称是否必须类型说明示例
sunmi_shop_no string商米数字店铺平台的门店组织编号列表560279010307
periodint统计周期1

period参数说明:

参数取值说明
1近7天数据统计
2近30天数据统计
3近90天数据统计
4近180天数据统计
5近365天数据统计

请求示例:

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/service/patrol/stat/groupByCheckItem",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值:

{
    "data": {
        "patrol_check_item_summary_list": [
            {
                "template_id": "549755813846",
                "check_item_name": "1",
                "check_score_count": 9,
                "check_total_count": 12
            },
            {
                "template_id": "549755813846",
                "check_item_name": "2dada方式方法将老豆腐江东父老的肌肤豆腐煎豆腐",
                "check_score_count": 1,
                "check_total_count": 1
            },
            {
                "template_id": "549755813846",
                "check_item_name": "调料归类正确",
                "check_score_count": 3,
                "check_total_count": 5
            },
            {
                "template_id": "549755813846",
                "check_item_name": "食品归类正确",
                "check_score_count": 4,
                "check_total_count": 5
            },
            {
                "template_id": "549755813846",
                "check_item_name": "食品细菌含量未超标",
                "check_score_count": 3,
                "check_total_count": 5
            },
            {
                "template_id": "549755813846",
                "check_item_name": "食材未过期",
                "check_score_count": 5,
                "check_total_count": 5
            },
            {
                "template_id": "549755813846",
                "check_item_name": "食材清洗干净",
                "check_score_count": 4,
                "check_total_count": 5
            }
        ]
    },
    "code": 0,
    "msg": "succeed"
}

返回参数说明:

参数名类型说明
template_idint模板id
check_item_namestring检查项名称
check_score_countint检查得分次数
check_total_countint 检查次数

错误码:

错误码说明

商品管理接口

3.1 接口描述

商品管理接口包括两部分:

一部分是商品新增修改删除接口,这是数字店铺的通用基础功能,很多设备和服务都会用到,参考单独的商品对接的文档。

另一部分是价签业务相关的功能,包括商品与价签的绑定解绑等,在本文中进行描述。

3.2 接口列表

接口名称接口
商品绑定价签/product/bindEsl
商品解绑价签/product/unbindEsl
获取商品绑定价签/product/getBindEslList
修改商品绑定价签的模板/product/updateTemplate
获取商品列表/product/getList
获取商品详情/product/getInfo

3.3 接口详情

3.3.1 商品绑定价签

接口描述:通过本接口调用,用户可以将商品与指定价签进行绑定,同时指定对应模板。绑定之后价签将开始刷图。

请求链接:/product/bindEsl

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台的门店组织编号
shop_idstring第三方对接软件中门店的标识,对接的软件提供 (作为门店唯一标识即可,shop_id与sunmi_shop_no可互为替代,使用时传输任意一个即可)
product_idstring商品数据库ID,如果进行了对接,和数据对接传过来的id一致
esl_code否(esl_code与esl_id至少提供一个)string电子价签8位ID(价签正面的条码)
esl_id否(esl_code与esl_id至少提供一个)string电子价签数据库ID转码
template_idstring模板数据库ID

返回值: 

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

错误码:

错误码说明
5000数据库错误
5020参数错误
5015非法商品
5343非法模板
5300非法基站
5301非法价签
5338价签已被其他店铺绑定   
5342非法价签图片
5006OSS错误
5041非法对接软件店铺


3.3.2 商品解绑价签

接口描述:通过本接口调用,用户可以将商品与指定价签解除绑定。解绑之后价签将刷新显示解绑模板对应的内容。

请求链接:/product/unbindEsl

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台的门店组织编号
shop_idstring第三方对接软件中门店的标识,对接的软件提供 (作为门店唯一标识即可,shop_id与sunmi_shop_no可互为替代,使用时传输任意一个即可)
esl_code否(esl_code与esl_id至少提供一个)string电子价签8位ID (价签正面的条码)
esl_id否(esl_code与esl_id至少提供一个)string电子价签数据库ID转码

返回值: 

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

错误码:

错误码说明
5000数据库错误
5020参数错误
5301非法价签
5320价签未绑定
5338价签已被其他店铺绑定    
5342非法价签图片
5006OSS错误
5041非法对接软件店铺

3.3.3 获取商品绑定价签

接口描述:通过本接口调用,用户可以获取商品绑定的价签列表。

请求链接:/product/getBindEslList

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台的门店组织编号
shop_idstring第三方对接软件中门店的标识,对接的软件提供 (作为门店唯一标识即可,shop_id与sunmi_shop_no可互为替代,使用时传输任意一个即可)
product_idstring商品数据库ID,如果进行了对接,和数据对接传过来的id一致

返回值: 

{
    code:0,       /* 其他错误参考错误列表 */
    msg: "succeed",
    data: { 
       "esl_list": [{
            "esl_id": ”1000“,
            "esl_code": "DJKS90EN",
            "template_id": ”10002“,
            "status": 1,
     } ...   
    ]}
}

错误码:

错误码说明
5000数据库错误
5020参数错误
5301非法价签
5015非法商品
5041非法对接软件店铺

3.3.4 修改商品绑定价签的模板

接口描述:通过本接口调用,用户可以更新商品对应的模板。

请求链接:/product/updateTemplate

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台的门店组织编号
shop_idstring第三方对接软件中门店的标识,对接的软件提供 (作为门店唯一标识即可,shop_id与sunmi_shop_no可互为替代,使用时传输任意一个即可)
product_idstring商品数据库ID,如果进行了对接,和数据对接传过来的id一致
template_idstring模板数据库ID


返回值
: 

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

错误码:

错误码说明
5000数据库错误
5020参数错误
5005文件错误
5006OSS错误
5343非法模板
5015非法商品
5342非法价签图片
5041非法对接软件店铺

3.3.5 获取商品列表

接口描述:通过本接口调用,用户可以使用关键字搜索商品。

请求链接:/product/getList

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台的门店组织编号
shop_idstring第三方对接软件中门店的标识,对接的软件提供 (作为门店唯一标识即可,shop_id与sunmi_shop_no可互为替代,使用时传输任意一个即可)
keywordstring关键字
page_numint页码
page_sizeint每页记录数

返回值: 

{
    "code": 0,       /* 其他错误参考错误列表 */
    "msg": "succeed"
    "data": {
        "total_count": 1,
        "product_list": [
            {
                "id": ,
                "name": ,
                "seq_num": ,
                "bar_code": ,
                "category_id": ,
                "price": ,
                "modified_time":
            }
        ],
    },
 }

错误码:(历史原因,成功为0,失败为1)

3.3.6 获取商品信息

接口描述:通过本接口调用,用户可以获取商品信息。

请求链接:/product/getInfo

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台的门店组织编号
shop_idstring第三方对接软件中门店的标识,对接的软件提供 (作为门店唯一标识即可,shop_id与sunmi_shop_no可互为替代,使用时传输任意一个即可)
product_idstring商品数据库ID,如果进行了对接,和数据对接传过来的id一致

返回值: 

{
    code:0,       /* 其他错误参考错误列表 */
    msg: "succeed",
    data: {
        "id":,
        "name":,
        "alias":,
        "seq_num":,
        "bar_code":,
        "qr_code":,
        "unit":,
        "spec":,
        "area":,
        "level":,
        "brand":,
        "expire_time":,
        "price":,
        "promote_price":,
        "member_price":,
    }
}

错误码:(历史原因,成功为0,失败为1)

特殊代码说明

一、获取商米设备标识

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

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-666-6509(00:00~24:00,7*24小时服务)。   建议合作伙伴使用商米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来精细管理应用数据(比如按照业务分类或时间删除数据),也可以避免重要的应用数据被删除。

在程序的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)也可以避免该问题

调试设备说明

关于商米设备调试

ADB权限申请流程:在FT1mini 在设置->开发者选项->开发者指南->输入渠道绑定的手机号->获取验证码->填入收到的验证码->授权后就可以adb调试了

(本教程仅适用于非金融设备,如需要开启Sunmi P系列设备的调试权限,请联系销售人员)

默认商米的设备插上USB线就可以调试,商米也提供了设备调试权限的控制功能,合作伙伴在后台开启调试权限控制后(如下图所示),则需要通过邮箱或手机号获取调试权限才能调试该设备。如果不能直接调试,请查看合作伙伴后台是否开启了该权限。

注:调试权限的控制只针对绑定了合作伙伴(渠道)的设备生效。

启用调试权限控制后如何调试设备

如果合作伙伴启用了’调试权限控制’,则开发者需要在旗下设备上通过邮箱和手机号获取调试权限才能调试设备,合作伙伴可以在商米合作伙伴平台添加调试员(开发者)的手机号或邮箱。以下为获取设备调试权限的歩骤:

1.添加调试员。

开发者调试设备之前请了解设备所属的渠道,可以找自己公司相关的管理人员询问。管理人员需要在商米的合作伙伴平台后台添加调试员的手机号或邮箱。

2

2.插入USB(V1s、V2、M2、L2建议暂时通过关闭云端调试保护开关来调试设备)

确保自己有调试权限的手机号或邮箱后,将设备连接电脑,建议开发者在windows下调试,如果手机能被电脑正确识别,通常会出现如下的弹窗提示:

3

如果设备没有被电脑识别,请确认是否因以下原因引起。

  • 接触不良,请多次插拔扭动USB接口确认。
  • 数据线故障,换条数据线看下能不能识别。
  • 电脑没有安装移动设备驱动,可以使用第三方工具软件安装。

3.获取验证码。

点击上面的“我要调试”项,将进入手机号或邮箱验证权限步骤,同时设备的USB调试模式将自定开启(这里是指基础的调试模式,不是权限);点击“知道了”将退出弹窗,不会开启USB调试模式。

4

4.验证权限

输入之前添加的手机号或邮箱后点击’获取验证码’,商米将向手机号或邮箱发送验证码,填入验证码点击’授权并开启调试’。

5

5.打开权限。

打开权限后,可以查看logcat中有无输出判断是否可以调试设备。

6