对接引导

[toc]

1 背景介绍

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

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

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

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

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

2 对接级别

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

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

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

3 接口模块及文档说明

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

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

4 接口汇总说明

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

下表给出了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/bind


如果不使用商米助手,需要对接基站绑定相关接口

从门店解绑基站/device/ap/unbind




获取基站列表/device/ap/getList




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




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




重启基站/device/ap/reboot



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


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

更新指定模板/template/update




获取模板列表/template/getList




获取模板详情/template/getInfo




删除模板/template/delete



升级暂未开放





5 环境说明

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

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