设备安装单对接

1.背景介绍

用于外部工单系统与内部基多的安装单进行数据更新同步

2. 接口规范

2.1 协议说明

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

Content-Typeapplication/json
数据格式返回为Json格式
字符编码UTF-8字符编码
签名算法RSA
签名规则参考2.2

2.2 签名规则

使用非对称加密方式，请求方生成密钥对，保留密钥对的私钥，并对请求体进行加签后再作请求，防止消息被篡改。提供接口的一方保留密钥对的公钥，对请求体进行签名验证。

2.2.1 生成密钥对

  1. 使用openssl工具生成RSA私钥和公钥 (2048 bit)
  2. 把RSA私钥转换成PKCS8格式
  3. 将RSA公钥发送给需要验签的一方

2.2.2 加签步骤

  1. 获取请求体 post 内容，不包括字节类型参数，如文件、字节流，剔除 sign 字段，剔除值为空的参数;
  2. 按照第一个字符的键值 ASCII 码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推；
  3. 将排序后的参数与其对应值，组合成 参数=参数值 的格式，并且把这些参数用 & 字符连接起来，此时生成的字符串为待签名字符串。示例：
原请求体：
{"app_id":"20210021","time_stamp":1643093114,"biz_content":{"order_no":"","shop_no":""}}

处理完成后："app_id='20210021'&time_stamp=1643093114&biz_content={'order_no':'','shop_no':'','shop_name':''}"
  • 使用rsa 私钥对字符串进行加签(使用sha1算法，并进行base64处理)。

2.3 公共参数

参数名必填类型说明示例
app_id是string唯一标识接入身份，联系商米数字店铺提供“20210021”
time_stamp是int当前的unix timestamp，精度到秒级，10位数字1643093114
sign是string签名信息skdsaijaowpeoqpo

3. 安装单接口

3.1 基多服务端同步接口

接口描述：通过此接口将工单数据同步到基多服务中

请求链接：http://quito.sunmi.com/quito/api/mgt/order/subOrder/updateInfo

接口版本：v 1.0

加密之前的字段：

安装单字段

参数名称必须类型说明
sub_order_no是string设备安装单编号（子订单编号）
shop_no是string门店编号
shop_name是string门店名称
sn否string设备号
install_mode否string安装方式
WALL_MOUNTING 挂壁安装
RACK_MOUNTING 底架支座安装
install_pic否string安装照片，英文逗号分隔，最多5张
install_video否string安装视频，一个
order_process_status是string安装进度
WAIT_ORDER 待预约
ORDER_FAILED 预约失败
WAIT_INSTALL 待上门
WAIT_ACCEPT 待验收
ACCEPTED 已验收
ACCEPT_FAILED 验收失败
INSTALL_CANCEL 取消安装
installer_sp否string安装网点
installer否string安装人员
install_cancel_reason否string取消安装原因
install_date否string安装日期 YY/MM/DD
book_visit_date否string预约上门日期 YY/MM/DD
device_apply_type否string设备用途
device_mode是string设备型号

请求示例：

{"app_id":"20210021",
"time_stamp":1643093114,
"sign":"skdsaijaowpeoqpo",
"biz_content":{"order_no":"BOb676d92478b9c94096",
              "shop_no":"910553061572",
              "shop_name":"我的店铺",
              "order_process_status":"WAIT_ORDER",
              "device_mode":"NPE01",
}}

返回值：

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

错误码：

code说明
1更新成功
-1其他错误
5000数据库错误
5026验签失败
6055sn与门店绑定不一致
6056设备未完成回收/维保换机流程
6057 订单状态不能回退
6088设备型号不匹配

3.2 第三方工单系统创建接口

接口描述：通过此接口将安装订单数据导入进第三方工单系统

请求链接：/api/order/create

接口版本：v 1.0

加密之前的字段：

安装订单字段属性

参数名称必须类型说明
order_no是string主订单编号
apply_time是int订单申请时间戳
created_time是int订单创建时间戳
shop_no是string门店编号
shop_name是string门店名称
city是string市
district是string区
address是string详细地址
house_no是string门牌号
comment是string备注
remark是string审核备注
sub_order_list是list[sub_order]子订单列表，每一笔子订单对应一台设备安装
pictures是list[string]现场照片
reference_company否string推荐人公司
reference_name否string推荐人姓名
reference_phone否string推荐人联系方式
contact_name是string店家联系人
contact_tel是string店家联系电话
router_cnt是int路由数量
router_model否string路由型号

sub_order 子订单属性

参数名称必须类型说明
sub_order_no是string子订单编号
device_mode是string设备型号, NPG01: 32寸商业显示器, NPE01: 24寸商业显示器设备型号,NPH01: 43寸商业显示器（4G）,NPH02: 43寸商业显示器

请求示例：

{"app_id":"20210021",
"time_stamp":1643093114,
"sign":"skdsaijaowpeoqpo",
"biz_content":{
    "order_no":"BOb676d92478b9c94096",
    "created_time":1643093114,
    "shop_no":"910553061572",
    "shop_name":"我的店铺",
    "city":"上海市",
    "district":"杨浦区",
    "address":"淞沪路388号",
    "house_no":"203",
    "commment":"",
    "remark":"",
    "sub_order_list":[{
        "sub_order_no":"SBOC12CEF63480CE180640009",
        "device_mode":"NPG01"}
        ],
    "pictures":["http://sunmi.cdn.com/1234.jpg"],
    "reference_company":"商米",
    "reference_name":"张三",
    "reference_phone":"17239123321",
    "contact_name":"李四",
    "contact_tel":"241244124",
    "router_cnt":1,
    "router_model":""
}

返回值：

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

错误码：

code说明
1导入成功
-1其他错误
5000数据库错误
5020无效参数
5021无效路径
5023参数缺失
5026验签失败

3.3 第三方工单系统更新接口

接口描述：通过此接口修改第三方工单系统的订单数据

请求链接：/api/order/update

接口版本：v 1.0

加密之前的字段：

参数名称必须类型说明
order_no是string主订单编号
shop_name否string门店名称
city否string市
district否string区
address否string详细地址
house_no否string门牌号
comment否string备注
remark否string审核备注
sub_order_list否list[sub_order]子订单列表，每一笔子订单对应一台设备安装
pictures否list[string]现场照片
reference_company否string推荐人公司
reference_name否string推荐人姓名
reference_phone否string推荐人联系方式
contact_name否string店家联系人
contact_tel否string店家联系电话
router_cnt否int路由数量
router_model否string路由型号

sub_order 子订单属性

参数名称必须类型说明
sub_order_no是string子订单编号
device_mode是string设备型号, NPG01: 32寸商业显示器, NPE01: 24寸商业显示器设备型号,NPH01: 43寸商业显示器（4G）,NPH02: 43寸商业显示器

请求示例：

{"app_id":"20210021",
"time_stamp":1643093114,
"sign":"skdsaijaowpeoqpo",
"biz_content":{
    "order_no":"BOb676d92478b9c94096",
    "shop_no":"910553061572",
    "shop_name":"我的店铺",
    "city":"上海市",
    "district":"杨浦区",
    "address":"淞沪路388号",
    "house_no":"203",
    "commment":"",
    "remark":"",
    "sub_order_list":[{
        "sub_order_no":"SBOC12CEF63480CE180640009",
        "device_mode":"NPG01"}
        ],
    "pictures":["http://sunmi.cdn.com/1234.jpg"],
    "reference_company":"商米",
    "reference_name":"张三",
    "reference_phone":"17239123321",
    "contact_name":"李四",
    "contact_tel":"241244124",
    "router_cnt":1,
    "router_model":""
}

返回值：

{"code":1,"msg":"success"}
code说明
1成功
-1其他错误
5000数据库错误
5020无效参数
5021无效路径
5023参数缺失
5026验签失败
5047无效订单

员工对齐

1 概要

1.1 简介

商米数字店铺（SUNMI Store）中的合法用户可以拥有有指定组织下的员工身份。

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_id是string唯一标识接入身份，联系商米数字店铺提供 LMWWQVTW4QGCC
random是string随机字符串，由数字和字母组成，长度范围为6-10位 5dsf6698
timestamp是int当前的unix timestamp，精度到秒级，10位数字 1581333970
sign是string签名信息，详见2.2 2E7CED3164B6BBDB81145F3CBE204597

3 开放API接口

3.1 用户注册

接口描述：通过本接口调用，实现商米数字平台用户注册。

请求链接：/employee/create

接口版本：v1.0.0

接口参数：

参数名称 是否必须 类型 说明 示例
user_id是stringuser_id
sunmi_company_no是string商户编号
name是int名称1
number是string员工工号
username是string员工账号(手机号/邮箱)
gender否string性别(男/女)
sso_username否string员工用户名(手机号)
mapping_list否string员工能管理的店铺列表

返回值： 

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

错误码：

错误码说明
204手机号码已经存在

巡店

1 背景介绍

商米巡店功能开放，支持H5实现的SDK调用

2 接口规范

2.1 协议说明

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

注：消息体大小不得超过1M，超过1M的请求，直接拒绝！

Content-Typeapplication/x-www-form-urlencoded
数据格式返回为JSON格式
字符编码UTF-8字符编码
授权方式Auth2.0
授权规则参考商米OAuth2.0授权http://docs.test.sunmi.com/htmls/商米oauth2-0/

2.2 请求头设置

略，要带token

3 巡店业务接口

3.1 获取门店列表

接口描述：通过本接口调用，用户可以获取可查看的所有门店

请求链接：/patrol/org/getList

接口版本：v2.0

参数：

参数名称是否必须类型说明示例
sunmi_company_no是string商户编号
inspection_user_id否string巡检人id
plan_start_time否integer巡店计划开始时间
plan_end_time否integer巡店计划结束时间

请求示例：

略

返回值：

{
	"code": 0,
	"msg": "",
	"data": {
		"org_list": [{
			"org_pid": 2945,
			"org_tag": 442,
			"level": 2,
			"org_id":3812,
			"org_name": "Lorem occaecat",
			"sunmi_shop_no": "298374832745742387",
			"org_status": 1,
			"business_status": 1,
			"type_one": 1,
			"type_two": 1,
			"type_name": "1",
			"province": 1,
			"city": 1,
			"area": 1,
			"lat": "38",
			"lng": "98",
			"address": "铁岭",
			"business_area": 40854915,
			"region": "aliqua",
			"business_hours": "nulla",
			"contact_person": "anim exercitation",
			"contact_tel": "irure ut",
			"contact_email": "mollit exerc",
			"created_time": -98259710,
			"modified_time": 15094789,
			"patrol_service_status": -36606166,
			"patrol_plan_status": 82471639,
			"inspection_user_auth": 22425348,
			"patrol_service_active_duration": -57840792,
			"patrol_service_active_status": 2411480,
			"children": [{
				"org_pid": 86480169,
				"org_tag": -62506489,
				"level": 86737874,
				"org_id": 99824037,
				"org_status": -13855870,
				"org_name": "do qui aute non",
				"sunmi_shop_no": "occaecat id",
				"business_status": -32078036,
				"type_one": 98245914,
				"type_two": 5120503,
				"type_name": "et cillum ",
				"province": 86019116,
				"city": -26065136,
				"area": "consequat in dolore",
				"lat": "officia labore",
				"lng": "eiusmod occaecat consequat et",
				"address": "dolore officia cupidatat eiusmod et",
				"business_area": 44639054,
				"region": "Ut tempor ex ea laboris",
				"business_hours": "sed mollit in",
				"contact_person": "sint Lorem",
				"contact_tel": "reprehenderit",
				"created_time": 9669190,
				"modified_time": 28811257,
				"patrol_service_status": 67245690,
				"patrol_plan_status": 46486322,
				"inspection_user_auth": "consectetur",
				"patrol_service_active_status": "id est non",
				"patrol_service_active_duration": "consequat magna dolor ad"
			}]
		}]
	}
}

商米OAuth2.0授权

1 背景介绍

商米支持 OAuth2.0 协议认证和授权，支持通用的 OAuth2.0 方案，例如 Web 服务应用，客户端应用等

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_id是string唯一标识接入身份，联系商米数字店铺提供 LMWWQVTW4QGCC
random是string随机字符串，由数字和字母组成，长度范围为6-10位 5dsf6698
timestamp是int当前的unix timestamp，精度到秒级，10位数字 1581333970
sign是string签名信息，详见3.2.2 2E7CED3164B6BBDB81145F3CBE204597

3 授权接口

3.1 获取Authorization Code

略

3.2 获取Access Token

接口描述：通过本接口调用，用户可以获取相关门店下所有设备列表。

请求链接：/oauth/getToken

口版本：v2.0

备注：此接口可不使用公共参数

参数：

参数名称是否必须类型说明示例
code是string一次性code，使用后立即失效
user_id是string用户id
app_id是string唯一标识接入身份

请求示例：

略

返回值：

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

身份证介绍demo

对接调试一共分为两部分，一部分为安卓应用对接的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.1.2下载

note:v1.1.1版本已经弃用，请用最新版本

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、参考DEMO

注：金融机的NFC功能非安卓标准NFC，需要调用金融SDK进行非接读卡。具体可参考DEMO中的金融读卡内容。

 商米提供了2种不同路径的调用方式：EidCardDemo-OpenApi为端对云的方式，安装apk后输入对应appid和key就可以直接读取身份信息。好处是集成方便，数据路径较短。坏处是安全性没有第二种高。

EidCardDemo为端对云对云的方式，好处是安全性高，坏处是路径较长。

  • 详细处理参考：EidCardDemo （安卓应用首先访问应用服务器，应用服务器通过商米Open Api访问商米服务器进行身份证读取）
  • 直连商米 Open Api 接口：EidCardDemo-OpenApi （直连商米open api服务器即安卓应用直接访问商米服务器进行身份证读取。该用法可能会导致appid与appkey同时泄漏，造成损失将由应用商自己承担）

1.6、详细接口说明

  • 详细接口文档：
SunmiEID-SDK-release-v1.1.2下载

1.7、错误码ErrorCode

2、身份证服务 API 接口

2.1、公共参数说明

2.1.1、概要

请求域名：https://openapi.sunmi.com

openapi的sdk：

golang 版本：https://github.com/sunmi-OS/sunmi-openapi-go-sdk

  1. 商米身份证服务的接口采用 HTTPS 协议
  2. 请求方式统一使用 POST
  3. 请求数据格式为 application/json

2.1.2、公共header说明

  1. 请求必传header

请求公共参数

参数名 类型 说明
Sunmi-Timestamp Integer 当前时间戳
Sunmi-Sign string 签名内容
Sunmi-Nonce Integer 6位随机数
Sunmi-Appid string 申请的APPID

返回公共参数

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

2.1.3、签名生成说明

签名算法：hmac256

签名生成方式：

1、拼接stringA（即 stringA=json-body + Sunmi-Appid + Sunmi-Timestamp + Sunmi-Nonce）

2、获取申请的AppKey作为hmac256算法的密钥key

3、最后进行 hmac256(stringA, Appkey)最终获取到sign值

2.1.4、公共错误码

返回码说明
1成功返回
20000网关校验缺少参数
20001请求超过有效期
30000开发者身份验证失败
30001开发者权限不足
40000签名验证失败
40001签名失败
50000服务器异常
50001网关异常

2.2、身份证云识别接口

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

2.2.1、请求参数

参数名类型说明
request_idstringandroid端生成的 request_id
encrypt_factorstring加密因子（8 位大小写字母和数字组成的的随机字符串，建议每次访问随机生成）

2.2.2、返回参数

成功返回

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

成功返回 data 域内容

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

示例：

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

失败返回

参数名类型说明
codeInteger返回码，参见常见业务错误码
datastring空字符串
msgstring错误提示信息，如有错误此字段返回错误描述
{
    "code": 20000,
    "data": "",
    "msg": "Missing required parameters"
}

2.2.3、解密说明

  • 加密方式：DES_CBC_PKCS5Padding 加密
  • 加密因子：传入的 encrypt_factor
  • 加密key：开发者平台申请的AppKey

解密流程：

  1. 对 info 字符串 base64 解码（standard 标准解码），解码完为 stringA
  2. 对 stringA 字符串进行 des 解密，截取AppKey前8位作为秘钥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",

 2.2.4、常见业务错误码

返回码说明
50000服务器异常
14200没有权限
14201sdk版本过低
14202无可使用次数
14203读卡错误
14204参数异常

密码保护：友盟广告投放接口

这是一篇受密码保护的文章，您需要提供访问密码：

升级异常的固件恢复方法

1. 概述

本文指导用户通过线下手动升级的方式，恢复升级异常的固件。

2. 获取升级固件

请务必从商米售前获取对应型号摄像头的升级固件 ，否则出现升级异常概不负责。

目前商米有的IPC摄像头有两款，分别是

  1. AI识客摄像机，英文名Face Sense Camera，简称FS，目前的型号是FM020。
  2. 智能看店摄像机，英文名Store Sense Camera，简称SS，目前的型号是FM010。

3. 升级规则

  1. 不同机型之间系统固件不能互相升级，例如FS和SS之间不能升级，所以请务必根据自己的机型来获取对应的正式环境固件。
  2. 固件本身有自己的签名机制和升级校验方法，所以请务必从商米处获取固件，切勿随便从第三方获取固件。

4. 详细流程

4.1 拷贝固件到TF卡

  1. 从摄像头的TF卡槽中取出TF卡；
  2. 将TF卡插入windows电脑，执行格式化操作，文件系统设置为exfat，卷标设置为SUNMI-XXXX（其中XXXX为摄像头MAC地址最后四位，摄像头MAC地址见机身背面标贴）。 注：卷标SUNMI-XXXX中的-为英文半角符号，非中文全角符号；XXXX中的字母为大写。
  3. 进入TF卡目录，将从商米处 （详见2. 获取升级固件）获取到的升级固件解压后拷贝到根目录下，并把固件重命名为up.bin。

4.2 升级固件

  1. 将带有固件的TF卡重新插入摄像头的TF卡槽中。
  2. 重新上电摄像头。
  3. 等待10秒左右，直到设备亮红灯，则说明正在固件升级 。
  4. 升级需要一些时间，再耐心等待1min左右，直到重新亮绿灯说明设备开始重启，当设备再次闪烁绿灯或者亮蓝灯说明设备已经重启完毕。

4.3 进行首配

  1. 重启后，长按设备上的Reset按键5秒以上进行恢复出厂设置。
  2. 恢复出厂重启后，使用正式环境的商米APP，按照《用户指南》手册中的软件配置指引完成摄像头的首次配置。
  3. 首配完成后，使用商米助手APP或登录正式环境的WEB服务网站https://store.sunmi.com 将设备固件更新到最新版本。
  4. 记得删除原来SD卡中的up.bin文件，避免不必要的意外升级。

增值服务-巡店服务 接口

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_id是string唯一标识接入身份，联系商米数字店铺提供
random是string随机字符串，由数字和字母组成，长度范围为6-10位
timestamp是int当前的unix timestamp，精度到秒级，10位数字
sign是string签名信息，详见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
period是int统计周期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最后一次巡检时间(秒)

错误码：

错误码说明
5041 请求中未找到shop_id参数

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

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

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

接口版本：v2.0

接口参数：

参数名称是否必须类型说明示例
sunmi_shop_no 是string店铺编号列表560279010307
period是int统计周期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门店考评总次数

错误码：

错误码说明
5041 请求中未找到shop_id参数

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

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

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

接口版本：v2.0

接口参数：

参数名称是否必须类型说明示例
sunmi_shop_no 是string店铺编号列表560279010307
period是int统计周期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总共使用次数

错误码：

错误码说明
5041 请求中未找到shop_id参数

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

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

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

接口版本：v2.0

接口参数：

参数名称是否必须类型说明示例
sunmi_shop_no 是string店铺编号列表560279010307
period是int统计周期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 检查次数

错误码：

错误码说明
5041 请求中未找到shop_id参数

自动草稿

自动草稿