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各个对接级别须对接的接口，有的接口比如闪灯、升级等，可以根据开发者的需求决定是否对接。
| 模块 | 接口名称 | 接口 | L1 | L2 | L3 | L4 | 说明 |
|---|---|---|---|---|---|---|---|
| 店铺绑定 | 绑定商米门店 | /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环境上。
