对接引导

1 背景介绍

商米智能电子价签可以应用于商超、仓库、医院、会议等场景，用于显示商品价格、货品库存、人员信息等。

客户可以直接在商米数字店铺上管理电子价签，但在大部分实际场景中，客户的软件系统需要与商米数字店铺开放平台进行对接，从而将商品信息传给数字店铺，控制价签系统的业务功能，最终实现对商米电子价签的集成。

为了满足客户需求，赋能软件合作伙伴，商米数字店铺开放平台提供价签相关的openAPI，可以与第三方软件进行不同级别的对接。

数字店铺开放平台包括商米云服务版本，私有云版本和本地单机版本，不同版本的对接接口有一些区别。

说明：本文以商品信息显示为主要视角进行描述，电子价签在更多场景的对接应用也可以参考此文档。

2 对接流程

1、确定对接意向，阅读接口文档（数字店铺开放平台文档），沟通对接需求（对接级别，业务流程设计，对接注意点，对接排期等），建立沟通微信群

2、将【对接软件名称】、【邮箱地址】发送给商米技术支持团队，商米技术支持团队将通过邮件发出uat环境对接参数，包括：【app_id】、【secret_key】、【uat环境价签助手App】

3、开始对接，商米技术支持团队在微信群中进行技术支持。

4、uat环境对接完成，软件合作方自测，同时开通测试账号给商米方面同步进行验证。

5、商米发出onl线上生产环境参数，在onl环境完成对接上线，客户项目使用。

3 对接级别

商米数字店铺开放平台提供价签系统相关的多个接口，软件合作伙伴可以根据自己需要集成的功能，有选择性的进行对接。

为了便于理解，我们将电子价签的对接分为L1-L4的四个等级，代表了不同级别的对接，可用于不同的场景，请参考进行选择。

级别对接内容提供能力
L1商品数据对接除了基础的店铺绑定外，仅对接商品库，合作软件将商品信息同步到数字店铺平台（或者是数字店铺主动获取）。
对接后电子价签能够自动变价，但电子价签相关的管理能力均在数字店铺和价签助手APP实现，包括绑定、解绑、编辑模板等。
L2基本操作对接在L1基础上，增加商品价签的绑定解绑接口 （集成到APP中）
对接后可以在集成的软件上进行价签商品的绑定解绑，日常操作无需用到数字店铺或价签助手APP。
L3设备对接在L2基础上，还对接了价签的设备相关接口。
对接后可以在合作软件上进行基本的价签管理，包括切换模板、闪灯、重推等，但模板编辑功能、基站管理功能，仍然需要登录数字店铺或价签助手APP使用。
L4完整对接在L3能力基础上，全面对接电子价签系统。
对接后可以在合作软件上进行基本上所有价签相关的管理功能，除了独立的模板Studio（不用登录）之外，用户在日常使用中不会登录使用数字店铺。

大部分情况下进行L1级别的对接即可，部分情况需要进行L2级别的对接，如果要更高级别的对接，请双方沟通业务场景后再进行开发。

4 接口模块及文档说明

数字店铺开放平台按照模块对所有接口进行了分类，如果需要对接电子价签，请参考下表中提到的模块及对应文档。

模块 & 文档说明
商米设备隐私政策在使用商米设备前，请务必认真阅读商米隐私政策，充分理解各条款内容，包括但不限于免除或限制商米责任的条款。
鉴权认证数字店铺开放平台鉴权认证的通用规则，请在进行开发前仔细阅读。
店铺绑定商米的设备和服务以商户门店为维度进行管理，在对接具体的业务功能接口前，需要先和第三方软件进行店铺的绑定。
商品库商品增删改的接口，L1级别的对接只需要使用商品接口。该商品接口不止用于电子价签，其他一些设备和服务也可以使用。
电子价签ESL管理电子价签系统的相关接口，L2及以上级别的对接需要用到这些接口。

5 接口汇总说明

电子价签相关接口按照模块来分，软件合作伙伴可以组合不同模块的接口来实现自己需要的功能。

下表给出了L1-L4各个对接级别须对接的接口，有的接口比如闪灯、升级等，可以根据开发者的需求决定是否对接。

模块接口名称接口L1L2L3L4说明
店铺绑定
绑定商米门店/shop/bind√√√
预先在数字店铺创建门店的需要手动绑定

解绑商米门店/shop/unbind√√√


更新门店信息/shop/update√√√


创建商户/company/create


√通过接口创建的商户和门店将会自动绑定

获取对接软件创建商户列表/company/getList


√

获取对接软件创建商户详情/company/getInfo


√　

创建门店/shop/create


√

获取对接软件创建门店列表/shop/getList


√

获取对接软件创建门店详情/shop/getInfo


√

获取对接软件门店绑定状态/shop/getBindInfo



通过shop_id查询对应商米门店信息
商品库
新建商品/product/create√√√√
更新商品/product/update√√√√支持通过该接口新建商品，默认增量更新
删除商品/product/delete√√√√
获取对接软件全量商品数据api/getProductList (对接软件提供)



第三方对接软件提供给的接口，绑定门店后商米拉取全量商品数据
电子价签 – 商品商品绑定价签/product/bindEsl
√√√将价签、商品、模板3者进行绑定，绑定后会触发刷图，同时价签会绑定到门店

商品解绑价签/product/unbindEsl
√√√

获取商品绑定价签/product/getBindEslList

√√可能包括多个价签

修改商品绑定价签的模板/product/updateTemplate



价签ID、模板

获取商品列表/product/getList

√√

获取商品详情/product/getInfo

√√
电子价签 – 价签添加价签到门店/device/esl/bind



仅将价签添加到店铺中，但不绑定商品

从门店删除价签/device/esl/unbind

√√从账户中解绑删除价签，只有解绑的才能删

获取价签列表/device/esl/getList

√√包含价签状态

获取价签详情/device/esl/getInfo

√√通过价签ID，获取基本信息、绑定商品、使用模板

对价签推特定图片/device/esl/pushImage



第三方软件生成图片推给价签，对图片尺寸有限制

获取统计信息/device/getOverview

√√包括系统设备数量、商品数量、各个推送状态数量
电子价签 – 闪灯对价签闪灯/device/esl/flashLed

√√让某些价签以某种方式闪灯
电子价签 – 基站
获取基站列表/device/ap/getList


√

获取基站详情/device/ap/getInfo


√

修改基站信息/device/ap/updateName


√

重启基站/device/ap/reboot


√
电子价签 – 模板上传新建模板/template/create


√将客户从独立Studio中生成的json文件上传到价签系统中

更新指定模板/template/update


√

获取模板列表/template/getList


√

获取模板详情/template/getInfo


√

删除模板/template/delete


√
升级暂未开放





6 环境说明

商米数字店铺有多套环境，建议在uat环境进行开发联调，联调通过后正式上线到onl环境上。

环境数字店铺Web地址接口地址接口范例
uathttps://store.uat.sunmi.com/https://store.uat.sunmi.com/openapi/https://store.uat.sunmi.com/openapi/product/update
onlhttps://store.sunmi.com/https://store.sunmi.com/openapi/https://store.sunmi.com/openapi/product/update


电子价签

1 背景介绍

商米数字店铺（SUNMI Store）是商米提供的基于店铺物联网设备的店铺管理系统。

商米数字店铺作为一个开放平台，支持与第三方软件进行各种对接，包括设备层面智能摄像机、电子价签的对接，数据层面的商品信息、交易信息对接等。

如果客户想要在第三方软件上进行价签设备的管理，包括价签与商品的绑定，指定价签闪灯等，可以通过对接将相应功能集成到第三方软件中。

下文列出的就是全面对接价签系统管理功能的相关接口。

2 接口规范

2.1 协议说明

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

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

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

2.2 签名规则

参考鉴权认证

2.3 公共参数

参数名必填类型说明
app_id是string唯一标识接入身份，联系商米数字店铺提供
random是string随机字符串，由数字和字母组成，长度范围为6-10位
timestamp是int当前的unix timestamp，精度到秒级，10位数字
sign是string签名信息，详见签名规则

3 商品管理接口

3.1 接口描述

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

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

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

3.2 接口列表

接口名称接口
商品绑定价签/product/bindEsl
商品解绑价签/product/unbindEsl
获取商品绑定价签/product/getBindEslList
修改商品绑定价签的模板/product/updateTemplate
获取商品列表/product/getList
获取商品详情/product/getInfo
批量更新商品价签模板(定制接口，QM)/product/batch/bindEslWithTemplate

3.3 接口详情

3.3.1 商品绑定价签

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

请求链接：/product/bindEsl

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
product_id是string商品数据库ID，如果进行了对接，和数据对接传过来的id一致
esl_code否（esl_code与esl_id至少提供一个）string电子价签8位ID（条码）
esl_id否（esl_code与esl_id至少提供一个）string电子价签数据库ID转码
template_id是string模板数据库ID

返回值： 

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

错误码：

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


3.3.2 商品解绑价签

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

请求链接：/product/unbindEsl

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用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价签未绑定
5336价签已被其他店铺绑定    
5342非法价签图片
5006OSS错误
5041非法对接软件店铺

3.3.3 获取商品绑定价签

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

请求链接：/product/getBindEslList

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
product_id是string商品数据库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_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
product_id是string商品数据库ID，如果进行了对接，和数据对接传过来的id一致
template_id是string模板数据库ID


返回值： 

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

错误码：

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

3.3.5 获取商品列表

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

请求链接：/product/getList

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
keyword否string关键字
page_num否(默认1)int页码
page_size否（默认10）int每页记录数

返回值： 

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

3.3.6 获取商品信息

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

请求链接：/product/getInfo

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
product_id是string商品数据库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":,
    }
}

3.3.7 批量更新商品价签模板(定制接口，QM)

接口描述：通过本接口调用，用户可以批量更新商品以及对应的价签。

请求链接： /product/batch/bindEslWithTemplate

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
bind_list是string(
array[bind_info])		价签绑定关系列表
trace_id否string消息追踪编号

bind_info参数类型：

bind_info参数 类型是否必填说明
esl_codestring否（esl_code和esl_sn至少填写一个） 电子价签8位ID（价签正面的条码）
esl_snstring 否（esl_code和 esl_ sn至少填写一个）
template_idstring 否（template_id和company_template_id 不能同时指定）门店模板唯一ID标识
company_template_id string 否（template_id和company_template_id 不能同时指定 ） 商户模板唯一ID标识
product_id string 是商品唯一ID标识
seq_num string 否（如果不填写，默认与product_id一致）
name string 是
pricedouble是
bar_code string 否
alias string 否
unit string 否
spec string 否
level string 否
area string 否
brand string 否
qr_code string 否
status string 否
description string 否
promote_pricedouble否
promote_price_descriptionstring 否
member_pricedouble 否
member_price_descriptionstring 否
extra_infojson 否
extra_price_infojson 否
extra_custom_infojson 否

返回值： 

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

4 价签管理接口

4.1 接口描述

设备管理接口用来管理电子价签设备本身，包括价签与门店的绑定解绑等。

4.2 接口列表

接口名称接口
添加价签到门店 /device/esl/bind
从门店删除价签 /device/esl/unbind
获取价签列表/device/esl/getList
获取价签详情/device/esl/getInfo
对价签推特定图片 /device/esl/pushImage
获取统计信息/device/getOverview
获取商铺下所有价签信息/device/esl/getListByCompany

4.3 接口详情

4.3.1 添加价签到门店

接口描述：通过本接口调用，用户可以绑定价签到指定门店。这一步操作不是必须，在执行商品绑定价签的时候，如果对应价签没有被任何门店绑定，也会执行绑定价签到门店的动作。

请求链接：/device/esl/bind

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
esl_code否（esl_code和esl_sn至少提供一个）string电子价签8位ID（条码）
esl_sn否（esl_code和esl_sn至少提供一个）string电子价签SN

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: {
        "esl_id": “129200”,
    }
}

错误码：

错误码说明
5000数据库错误
5301非法价签
5338价签已被店铺绑定
5041非法对接软件店铺

4.3.2 从门店删除价签

接口描述：通过本接口调用，用户可以从指定店铺上解绑价签，价签删除后会显示出厂图，可以再次被其他门店使用。

请求链接：/device/esl/unbind

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
esl_id是string电子价签数据库ID转码

返回值： 

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

错误码：

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

4.3.3 获取价签列表

接口描述：通过本接口调用，用户可以获取价签列表，列表中包含价签状态。

请求链接：/device/esl/getList

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
page_num否（默认1）int当前页码
page_size否  (默认10)int当前页条目数量

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: {
         "total_count": 100,
        "esl_list": [{
               "esl_id": “1000”,
                "esl_code": "SKDI39DN",
                "esl_sn": "B101194N00002",
                "model_name": "SL121+"，
                "status": 2
             },
             ... ...
       ] }

返回字段描述：status

status 取值说明
0未激活
1未绑定
2待推送
3推送成功
4推送失败

错误码：

错误码说明
5000数据库错误
5020非法参数
5041非法对接软件店铺

4.3.4 获取价签详情

接口描述：通过本接口调用，用户可以获取价签详情(包含MAC地址，电量，信号强度等)。

请求链接：/device/esl/getInfo

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用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: {
            "esl_id": "1000",
            "esl_code": "SKDI39DN",
            "esl_sn": "B101194N00002",
            "model_name": "SL121+",
            "status": 2,
            "screen_size_name": "2.13寸",
            "software_version": "1.0.1",
            "battery": 90,
            "rssi": -37,
            "connect_time": 15683920394,
            "ap_id":  "10200",
            "ap_sn": "B201E95D00001",
            "ap_name": "",
      }
}

返回字段描述：status

status 取值说明
0未激活
1未绑定
2待推送
3推送成功
4推送失败

错误码

错误码说明
5000数据库错误
5023缺少参数
5502非法设备机型
5041非法对接软件店铺

4.3.5 对价签推特定图片

接口描述：通过本接口调用，用户可以指定价签推图。

请求链接：/device/esl/pushImage

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
esl_id是string电子价签数据库ID转码
pic是file上传的刷图文件

图片分辨率：

上传图片的颜色和大小尺寸需要符合要求，否则无法成功下发显示到电子价签屏幕上，相关参数参考下表。

电子价签型号支持颜色支持图片分辨率（px）
SL115黑白、黑白红152 * 152
SL121黑白、黑白红212 * 104
SL126黑白、黑白红296 * 152
SL126+黑白296 * 152
SL142黑白、黑白红400 * 300
SL142+黑白、黑白红400 * 300
SL175黑白、黑白红640 * 384

返回值： 

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

错误码：

错误码说明
5004系统错误
5005非法文件
5020非法参数
5300非法基站
5301非法价签
5041非法对接软件店铺

4.3.6 获取统计信息

接口描述： 通过本接口调用，用户可以获取价签和基站的统计概览信息。

请求链接：/device/getOverview

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）

返回值：

{
    "code":0,
    "data":{
            "ap_total_count":24,
            "esl_total_count":55,
            "esl_pending_count":54,
            "esl_failed_count":3
        },
    "msg":""
}
错误码说明
5041非法对接软件店铺

4.3.7 获取商铺下所有价签信息

接口描述：通过本接口调用，用户可以分页获取指定商铺下的价签信息。

请求链接： /device/esl/getListByCompany

接口参数：

参数名称 是否必须 类型 说明
sunmi_company_no是string 商米数字店铺平台 中商户的唯一编号 （仅限通过接口创 建的店铺查询)
page_num 否(默认1）int页码
page_size否（默认10）int 每页记录数

返回值： 

{
    "data": {
        "total_count": 1,
        "esl_list": [
            {
                "id": "314159282628",
                "esl_code": "HRBAGJAY",
                "sn": "B101194N00006",
                "mac": "00:01:01:02:02:02",
                "bin_version": "0.6.6",
                "battery": 4,
                "rssi": 0,
                "status": 1,
                "ap_sn": "tongyutestsn",
                "ap_id": "314159333800",
                "model_name": "SL121"
            }
        ]
    },
    "code": 0, /* 其他错误参考错误列表 */ 
    "msg": "succeed"
}

返回字段描述：status

status取值 说明
0 未激活
1未绑定
2待推送
3推送成功
4推送失败

错误码：

错误码说明
5000数据库错误
5041非法对接软件店铺
5903该商铺不是当前 saas 创建，无权查看

5 闪灯接口

5.1 接口描述

闪灯接口用于管理价签闪灯相关功能，包括让指示灯以某种颜色、频率进行闪烁。

5.2 接口列表

接口名称接口
指定价签闪灯/device/esl/flashLed
指定商品绑定的价签闪灯 /device/esl/product/flashLed

5.3 接口详情

5.3.1 指定价签闪灯

接口描述：通过本接口调用，可以让某些价签以某种方式闪灯。

请求链接：/device/esl/flashLed

接口参数：

返回值： 

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
esl_id是string电子价签数据库ID转码
channel否 （默认为4） intLED颜色： 1-白， 2-蓝， 4-绿， 8-红，512-青， 1024-紫， 2048-黄
cycle否 （默认为100） int单次闪烁周期， 单位10ms；即 1s=100个cycle
duration否 （默认为8） int总共闪灯次数
{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: { }
}

错误码

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

5.3.2 指定商品的绑定价签闪灯

接口描述：通过本接口调用，可以让某个商品绑定的价签某种方式闪灯。

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
product_id是string 商品数据库ID，如果进行了对接，和数据对接传过来的id一致
channel否 （默认为4） intLED颜色： 1-白， 2-蓝， 4-绿， 8-红，512-青， 1024-紫， 2048-黄
cycle否 （默认为100） int单次闪烁周期， 单位10ms；即 1s=100个cycle
duration否 （默认为8） int总共闪灯次数

{
code：0， /* 其他错误参考错误列表 */
msg: “succeed”，
data: { }
}

错误码

错误码说明
5000数据库错误
5051 非法商品
5041非法对接软件店铺

6 基站管理接口

6.1 接口描述

基站管理接口用来管理电子价签使用的无线基站，包括基站的绑定解绑重启等。

6.2 接口列表

接口名称接口
绑定基站到门店/device/ap/bind
从门店解绑基站/device/ap/unbind
获取基站列表/device/ap/getList
获取基站详情/device/ap/getInfo
修改基站信息/device/ap/updateName
重启基站/device/ap/reboot
获取商铺下所有基站信息/device/ap/getListByCompany
绑定基站到门店（定制接口，qm） /device/ap/shop/bind

6.3.1 绑定基站到门店

接口描述：通过本接口调用，用户可以绑定无线基站到指定门店。

请求链接：/device/ap/bind

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
ap_sn是string无线基站SN
ap_name否string无线基站名称
ap_mac否string无线基站MAC地址

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: {
        “ap_id": ”129200“, 
    }
}

错误码：

错误码说明
5000数据库错误
5023非法参数
5300非法基站
5339基站已被店铺绑定
5041非法对接软件店铺

6.3.2 从门店解绑基站

接口描述：通过本接口调用，用户可以从门店中解绑无线基站。

请求链接：/device/ap/unbind

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
ap_id否string无线基站编号（和ap_sn必须出现其一）
ap_sn否string无线基站SN(和ap_id必须出现其一)


返回值： 

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

错误码：

错误码说明
5000数据库错误
5300非法基站
5041非法对接软件店铺

6.3.3 获取基站列表

接口描述：通过本接口调用，用户可以获取无线基站列表 。

请求链接：/device/ap/getList

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
page_num否（默认1）int当前页码
page_size否（默认10）int当前页条目数量

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: { 
         "total_count": 100,
         "ap_list": [{
            "ap_id": “1000”,
            "ap_sn": "B201E96500001",
            "ap_name": "Gate 5"，
            "esl_count": 1920,
            "status": 2
        },
       ... ...
  ] }
}

返回字段描述：status

status 取值说明
0未激活
1在线
2离线

错误码：

错误码说明
5000数据库错误
5020非法参数
5041非法对接软件店铺

6.3.4 获取基站详情

接口描述：通过本接口调用，用户可以获取无线基站详情 。

请求链接：/device/ap/getInfo

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
ap_id是string无线基站编号

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: { 
          "ap_id": “1000”,
          "ap_sn": "B201E96500001",
          "ap_name": "Gate 5",
          "model_name": "SLAP1",
          "status": 2,
          "esl_count": 1920,
          "software_version": "1.0.1",
          "connect_time": 15683920394，
  ] }
}

返回字段描述：status

status 取值说明
0未激活
1在线
2离线

错误码：

错误码说明
5000数据库错误
5011非法设备机型
5300非法基站
5041非法对接软件店铺

6.3.5 修改基站信息

接口描述：通过本接口调用，用户可以修改无线基站名称 。

请求链接：/device/ap/updateName

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
ap_id是string无线基站编号
ap_name是string修改的名字

返回值： 

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

错误码：

错误码说明
5000数据库错误
5300非法基站
5041非法对接软件店铺

6.3.6 重启基站

接口描述：通过本接口调用，用户可以重启基站。

请求链接：/device/ap/reboot

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
ap_id是string无线基站编号

返回值： 

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

错误码：

错误码说明
5000数据库错误
5300非法基站
5041非法对接软件店铺

6.3.7 获取商铺下所有基站信息

接口描述： 通过本接口调用，用户可以分页获取指定商铺下的基站信息

请求链接 ： /device/ap/getListByCompany

请求参数：

参数名称 是否必须 类型 说明
sunmi_company_no 是 string 商米店铺平台中商户的唯一编号（仅限通过接口创建的店铺查询）
page_num 否(默认1)int 页码
page_size否（默认10）int 每页记录数

返回值：  

{
    "data": {
        "total_count": 1,
        "ap_list": [
            {
                "id": "314159283514",
                "sn": "B203P9CD00003",
                "name": "zqzqzzq",
                "mac": "0C:25:76:0C:25:08",
                "ip": "192.168.100.190",
                "model_name": "SLAP1",
                "esl_number": 0,
                "bin_version": "0.1.2",
                "status": 2
            }
        ]
    },
    "code": 0,/* 其他错误参考错误列表 */
    "msg": "succeed"
}

返回字段描述：status

status取值说明
0未激活
1在线
2离线

错误码：

错误码说明
5000 数据库错误
5041 非法对接软件店铺
5903 该商铺不是当前saas创建，无权查看

6.3.8 绑定基站到门店 (定制接口, qm）

接口描述：通过本接口调用，用户可以绑定无线基站到指定门店， 如果门店不存在，则创建门店以及绑定关系。

请求链接：/device/ap/shop/bind

接口参数：

参数名称是否必须类型说明
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
ap_sn是string无线基站SN
ap_name否string无线基站名称
ap_mac否string无线基站MAC地址

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: {
        “ap_id": ”129200“, 
        “sunmi_shop_no”: "20029384774"
    }
}

错误码：

错误码说明
5000数据库错误
5023非法参数
5300非法基站
5339基站已被店铺绑定
xxxx门店创建失败

7 模板管理接口

7.1 接口描述

模板管理接口用来对模板进行上传修改等操作，如果需要完全对接电子价签系统，不使用商米数字店铺任何功能，则需要对接这部分接口。

7.2 接口列表

接口名称接口
上传新建模板/template/create
更新指定模板/template/update
获取模板列表/template/getList
获取模板详情/template/getInfo
删除模板/template/delete
新建商户模板/template/company/create
更新商户模板 /template/company/update
获取商户模板列表/template/company/getList

7.3 接口详情

7.3.1 上传创建模板

接口描述：通过本接口调用，用户可以通过上传json格式的模板来创建新模板。模板json文件可以在数字店铺中下载，也可以在独立提供的模板设计网页中下载。

请求链接：/template/create

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
template_name是string模板名称
template_color是int模板支持的颜色类型 (1-黑白，2-黑白红)
template_screen是int模板支持的屏幕类型 (1 – 2.13寸，2 – 2.6寸，3 – 4.2寸)
template_json是stringjson格式的模板

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: {
        "template_id": "1000"
    }
}

错误码：

错误码说明
5000数据库错误
5005文件错误
5343非法模板
5346模板名称已存在
5041非法对接软件店铺

7.3.2 更新指定模板

接口描述：通过本接口调用，用户可以更新指定模板。

请求链接：/template/update

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
template_id是string
模板唯一标识ID
template_name否string模板名称
template_json否stringjson格式的模板

返回值： 

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

错误码：

错误码说明
5000数据库错误
5005文件错误
5343非法模板
5346模板名称已存在
5041非法对接软件店铺

7.3.3 获取模板列表

接口描述：通过本接口调用，用户可以获取模板列表。

请求链接：/template/getList

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
page_num否 (默认1)int当前页码
page_size否 (默认10)int当前页条目数量

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: {
　　”total_count“: 15,
       "template_list":[{
              "template_id": "100",
              "template_name": "sample",
              "template_color": 1,  /* 暂不支持*/
              "template_screen": 1},
              ... ...
   ]}
}

错误码：

错误码说明
5000数据库错误
5020非法参数
5041非法对接软件店铺

返回字段描述：color

color取值说明
1黑白
2黑白红

返回字段描述：screen

screen取值说明
12.13 寸
22.6 寸
34.2 寸

7.3.4 获取模板详情

接口描述：通过本接口调用，用户可以获取模板的详细属性。

请求链接：/template/getInfo

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
template_id是string模板唯一标识ID

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: {
              "template_name": "sample",
              "template_color_name": "BW",
              "template_screen_type_name": "2.6",
              "template_json":  "...",
              "template_color": 1,     /* 暂不支持*/
              "template_screen": 1,  /* 暂不支持*/
             
   }
}

错误码：

错误码说明
5000数据库错误
5005文件错误
5343非法模板
5041非法对接软件店铺

返回字段描述：color

color取值说明
1黑白
2黑白红

返回字段描述：screen

screen取值说明
12.13 寸
22.6 寸
34.2 寸

7.3.5 删除模板

接口描述：通过本接口调用，用户可以删除指定模板。

请求链接：/template/delete

接口参数：

参数名称是否必须类型说明
sunmi_shop_no否string商米数字店铺平台中门店的唯一编号（v2.0之后为必填项）
shop_id否string第三方对接软件中门店的唯一编号（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
template_id_list是array模板唯一标识ID列表

返回值： 

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

错误码：

错误码说明
5000数据库错误
5041非法对接软件店铺

7.3.6 上传商户模板

接口描述：通过本接口调用，用户可以通过上传json格式的模板来创建商户级别新模板。模板json文件可以在数字店铺中下载，也可以在独立提供的模板设计网页中下载。

请求链接：/template/company/create

接口参数：

参数名称是否必须类型说明
sunmi_company_no是string商米数字店铺平台中商户的唯一编号
template_name是string模板名称
template_color是int模板支持的颜色类型 (1-黑白，2-黑白红)
template_screen是int模板支持的屏幕类型 (1 – 2.13寸，2 – 2.6寸，3 – 4.2寸)
template_json是stringjson格式的模板

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: {
        "template_id": "1000"
    }
}

错误码：

错误码说明
5000数据库错误
5005文件错误
5343非法模板
5346模板名称已存在
5xxx非法对接软件商户

7.3.7 更新商户模板

接口描述：通过本接口调用，用户可以更新指定商户模板。

请求链接：/template/company/update

接口参数：

参数名称是否必须类型说明
sunmi_company_no是string商米数字店铺平台中商户的唯一编号
template_id是string
模板唯一标识ID
template_name否string模板名称
template_json否stringjson格式的模板

返回值： 

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

错误码：

错误码说明
5000数据库错误
5005文件错误
5343非法模板
5346模板名称已存在
5xxx非法对接软件商户

7.3.8 获取商户模板列表

接口描述：通过本接口调用，用户可以获取商户模板列表。

请求链接：/template/company/getList

接口参数：

参数名称是否必须类型说明
sunmi_company_no是string商米数字店铺平台中商户的唯一编号
page_num否 (默认1)int当前页码
page_size否 (默认10)int当前页条目数量

返回值： 

{
    code：0，       /* 其他错误参考错误列表 */
    msg: "succeed"，
    data: {
　　”total_count“: 15,
       "template_list":[{
              "template_id": "100",
              "template_name": "sample",
              "template_color": 1,  /* 暂不支持*/
              "template_screen": 1},
              ... ...
   ]}
}

错误码：

错误码说明
5000数据库错误
5020非法参数
5xxx非法对接软件商户

返回字段描述：color

color取值说明
1黑白
2黑白红

返回字段描述：screen

screen取值说明
12.13 寸
22.6 寸
34.2 寸