1 背景介绍
商米数字店铺(SUNMI Store)是商米提供的围绕商户店铺中物联网设备基础上的店铺管理系统。
商米数字店铺作为一个开放平台,支持与第三方SaaS厂商进行各种数据的对接,包括商品信息对接,交易信息对接,会员体系对接等。
2 接口规范
2.1 协议说明
对接的openAPI接口目前只开放HTTPS方式,所有的消息一律采用POST方式。
注:消息体大小不得超过1M,超过1M的请求,直接拒绝!
Content-Type | application/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 开放API接口
3.1 会员库对接 v1.0
3.1.1 会员字段属性
以下属性均为会员基础属性。
商米数字平台会员参数 | 类型 | 说明 | 是否必须 | 参数说明 |
member_id | string | 会员编号 | 是 | |
name | string | 会员姓名 | ||
address | string | 地址 | ||
phone | string | 联系电话 | ||
ali_id | string | 会员阿里ID | ||
wechat_id | string | 会员微信ID | ||
gender | int | 性别 | 1-男, 2-女 | |
age | int | 年龄 | ||
total_purchase_amount | double(精确到小数点后四位) | 总计消费金额 | ||
member_points | double | 会员积分 | ||
pic | file | 会员照片 | ||
attributes | list[{‘attribute_key’: ‘attribute_value’}] | 自定义会员属性,最大可支持5个自定义属性。 可以指定 attribute_key 和 attribet_value的key-value组添加属性,类型皆为string | ||
group_id | string | 如果需要将会员直接录入指定人脸分组,则需要设定group_id,pic参数需要同时生效,以确保会员人脸被识别和录入 |
以下属性均为会员消费记录属性:
商米数字平台会员消费记录参数 | 类型 | 说明 | 是否必须 | 参数说明 |
member_id | string | 会员编号 | 是 | |
shop_id | string | 会员消费门店编号 | 是 | |
shop_name | string | 会员消费门店名称 | ||
order_id | string | 订单编号 | 是 | |
order_time | int | 订单时间 | ||
coupon_id | string | 卡券编号 | ||
order_amount | double(精确到小数点后四位) | 订单消费金额 | ||
total_purchase_amount | double(精确到小数点后四位) | 总计消费金额 | ||
valid_member_points | double | 有效会员积分 |
3.2 接口列表
接口名称 | 接口描述 |
/member/create | 添加会员 |
/member/assign | 将会员与指定门店的IPC设备关联 |
3.3 接口详情
3.3.1 添加会员
接口描述:通过本接口调用,用户可以添加会员。
请求链接:/member/create
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
sunmi_company_no | 是 | string | 商米数字店铺平台商户唯一编号 |
member_list | 是 | array | 新建会员对象列表 |
total_purchase_amount | 否 | double(精确到小数点后四位) | 会员总消费金额 |
member_points | 否 | double | 会员积分 |
ali_id | 否 | string | 会员阿里ID |
wechat_id | 否 | string | 会员微信ID |
pic | 否 | file | 会员照片 |
attributes | 否 | list[{‘attribute_key’: ‘attribute_value’}] | 自定义会员属性,最大可支持5个自定义属性。 可以指定 attribute_key 和 attribet_value的key-value组添加属性,类型皆为string |
返回值:
{ "code": 0, /* 其他错误参考错误列表 */ "msg": "succeed", "data": { } }
错误码:
错误码 | 说明 |
5000 | 数据库错误 |
5006 | 文件存储错误 |
5520 | 已经达到最大人脸分组数量或已经达到最大人脸容量 |
3.3.2 将会员与指定门店的IPC设备关联
接口描述:通过本接口调用,将会员与指定门店的IPC设备关联,IPC会根据member的录入照片生成的FaceID同步到店内所有IPC上。
请求链接:/member/assign
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
sunmi_company_no | 是 | string | 商米数字店铺平台商户唯一编号 |
sunmi_shop_no | 是 | string | 商米数字店铺平台店铺唯一编号 |
group_id | 是 | string | 会员分组编号 |
member_id_list | 是 | list[string] | 会员编号列表 |
返回值:
{ "code": 0, /* 其他错误参考错误列表 */ "msg": "succeed", "data": { "success_list": [ { "member_id": "263", "msg": "", "errcode": 0 } ], "failed_list": [ { "member_id": "262", "msg": "member info has no faceId", "errcode": 5700 } ] } }
错误码:
错误码 | 说明 |
5000 | 数据库错误 |
5520 | 已经达到最大人脸分组数量或已经达到最大人脸容量 |
5521 | 人脸信息不存在 |
5522 | 人脸库不存在 |
5528 | 会员人脸关联失败 |
5032 | 非法店铺 |
5700 | 无人脸信息的会员 |