人脸分组管理接口

3.1 接口描述

人脸管理接口是用来管理与人脸相关的接口,商米数字店铺会在云上保存相关已授权数据和配置,并将需要的数据同步给店内智能摄像机设备。

3.2 接口列表

接口名称接口描述
/face/group/getList获取人脸分组列表
/face/group/getInfo获取指定人脸分组信息
/face/group/create添加人脸分组
/face/group/update修改指定人脸分组
/face/group/delete删除指定人脸分组
/face/group/getFaceList获取指定人脸分组内的人脸列表
/face/getInfo获取指定人脸的详细信息
/face/add向指定人脸分组添加人脸信息
/face/update修改指定人脸的属性信息
/face/updatePicture修改指定人脸图片的属性信息
/face/delete从指定人脸分组中删除人脸信息
/face/group/move将指定人脸在人脸分组中迁移
/face/group/updateMoveStrategy修改生客分组移组条件

3.3 接口详情

3.3.1 获取人脸分组列表

接口描述:通过本接口调用,用户可以获得人脸分组列表。

请求链接:/face/group/getList

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项 )560279010307
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 10096

请求示例:  

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/group/getList",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

{
    "data": {
        "group_list": [
            {
                "group_id": "578968814328",
                "type": 1,
                "count": 0,
                "capacity": 1000,
                "last_modified_time": 0,
                "group_name": "stranger",
                "description": "",
                "customer_key1": "",
                "customer_key2": "",
                "customer_key3": "",
                "customer_key4": "",
                "customer_key5": ""
            },
            {
                "group_id": "578968814329",
                "type": 2,
                "count": 0,
                "capacity": 1000,
                "last_modified_time": 0,
                "group_name": "regular",
                "description": "",
                "customer_key1": "",
                "customer_key2": "",
                "customer_key3": "",
                "customer_key4": "",
                "customer_key5": ""
            },
            {
                "group_id": "578968814330",
                "type": 3,
                "count": 0,
                "capacity": 1000,
                "last_modified_time": 0,
                "group_name": "employee",
                "description": "",
                "customer_key1": "",
                "customer_key2": "",
                "customer_key3": "",
                "customer_key4": "",
                "customer_key5": ""
            },
            {
                "group_id": "578968817934",
                "type": 5,
                "count": 0,
                "capacity": 1000,
                "last_modified_time": 0,
                "group_name": "YiliuTest",
                "description": "",
                "customer_key1": "",
                "customer_key2": "",
                "customer_key3": "",
                "customer_key4": "",
                "customer_key5": ""
            }
        ]
    },
    "code": 0,  /* 其他错误参考错误列表 */
    "msg": "succeed"
}

返回字段描述:type

type 取值说明
1生客人脸库
2熟客人脸库
3店员人脸库
5自定义人脸库

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数

3.3.2 获取指定人脸分组信息

接口描述:通过本接口调用,获取指定人脸分组信息。

请求链接:/face/group/getInfo

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 560279010307
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 10096
group_idstring人脸分组唯一标识ID 578968814328

请求示例:  

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/group/getInfo",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "group_id": "578968814328",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

{
    "data": {
        "group_id": "578968814328",
        "type": 1,
        "count": 0,
        "capacity": 1000,
        "last_modified_time": 0,
        "group_name": "stranger",
        "description": "",
        "customer_key1": "",
        "customer_key2": "",
        "customer_key3": "",
        "customer_key4": "",
        "customer_key5": ""
    },
    "code": 0,  /* 其他错误参考错误列表 */
    "msg": "succeed"
}

返回字段描述:type

type 取值说明
1生客人脸库
2熟客人脸库
3店员人脸库
5自定义人脸库

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数

3.3.3 添加人脸分组

接口描述:通过本接口调用,用户可以 添加人脸分组。

请求链接:/face/group/create

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 560279010307
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 10096
namestring人脸分组名称Mike
type是·int人脸分组类型 (1-生客, 2-熟客,3-店员 ,5-自定义,会员)5
capacityint人脸分组容量10000
descriptionstring人脸分组描述此分组用于对于金卡会员管理
customer_key1string人脸分组自定义扩展字段1 名称vip_level
customer_key2string人脸分组自定义扩展字段2 名称hobby
customer_key3string人脸分组自定义扩展字段3 名称foreigner
customer_key4string人脸分组自定义扩展字段4 名称figure
customer_key5string人脸分组自定义扩展字段5 名称hairstyle

请求示例:  

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/group/create",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "name": "Mike",
    "type": 5,
    "capacity": 1000,
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

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

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数
5518 人脸库创建失败
5520已经达到最大人脸分组数量或已经达到最大人脸容量
5523已经存在该人脸分组

3.3.4 修改指定人脸分组

接口描述:通过本接口调用,用户可以修改指定人脸分组。

请求链接:/face/group/update

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 100939070408
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 15220
group_idstring人脸分组唯一标识ID578968817476
namestring人脸分组名称Mike
capacityint人脸分组容量10000
descriptionstring人脸分组描述 此分组用于对于金卡会员管理
customer_key1string人脸分组自定义扩展字段1 名称vip_level
customer_key2string人脸分组自定义扩展字段2 名称hobby
customer_key3string人脸分组自定义扩展字段3 名称foreigner
customer_key4string人脸分组自定义扩展字段4 名称figure
customer_key5string人脸分组自定义扩展字段5 名称hairstyle

请求示例:  

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/group/update",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "name": "Mike",
    "type": 5,
    "capacity": 1000,
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

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

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数
5506未查询到该数据
5520已经达到最大人脸分组数量或已经达到最大人脸容量
5525默认人脸库不允许修改

3.3.5 删除指定人脸分组

接口描述:通过本接口调用,用户可以删除指定人脸分组。

请求链接:/face/group/delete

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 560279010307
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 10096
group_idstring人脸分组唯一标识ID578968814328

请求示例:  

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/group/delete",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "group_id": "578968814328",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

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

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数
5506未查询到该数据
5524默认人脸库不允许被删除
5509非空人脸库

3.3.6 获取指定人脸分组内的人脸列表

接口描述:通过本接口调用,用户可以获取指定人脸分组内的人脸列表。

请求链接:/face/group/getFaceList

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 100939020409
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 7948
group_idstring人脸分组唯一标识ID578968813726
page_num否 (默认1)int当前页码1
page_size否 (默认10)int当前页条目数量10

请求示例:  

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/group/getFaceList",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "group_id": "578968813726",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

{
    "data": {
        "face_list": [
            {
                "face_id": "578968751459",
                "group_id": "578968813726",
                "group_name": "",
                "gender": 1,
                "age_range": 6,
                "arrival_count": 0,
                "create_time": 1579591542,
                "last_arrival_time": 0,
                "name": "lll",
                "customer_key1": "",
                "customer_key2": "",
                "customer_key3": "",
                "customer_key4": "",
                "customer_key5": ""
            }
        ],
        "total_num": 1
    },
    "code": 0,  /* 其他错误参考错误列表 */
    "msg": "succeed"
}

返回字段描述:gender

gender 取值说明
0未知
1
2

返回字段描述:age_range

age_range 取值说明
10~6岁
27~12岁
313~18岁
419~28岁
529~35岁
636~45岁
746~55岁
856~ 岁

错误码:

错误码说明
5000数据库错误
5506未查询到数据
5013未找到数据
5041请求中未找到shop_id参数

3.3.7 获取指定人脸的详细信息

接口描述:通过本接口调用,用户可以获取指定人脸的详细信息。

请求链接:/face/getInfo

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no stirng 商米数字店铺平台唯一编号(v2.0之后为必填项) 100939020409
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 7948
face_idstring人脸唯一标识ID578968751459

请求示例:  

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/getInfo",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "face_id": "578968751459",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

{
    "data": {
        "age_range": 6,
        "arrival_count": 0,
        "create_time": 1579591542,
        "face_id": "578968751459",
        "gender": 1,
        "group_id": "578968813726",
        "group_name": "stranger",
        "last_arrival_time": 0,
        "name": "lll"
    },
    "code": 0,  /* 其他错误参考错误列表 */
    "msg": "succeed"
}

错误码:

错误码说明
5000数据库错误
5506未找到数据
5013未找到数据
5041请求中未找到shop_id参数

3.3.8 向指定人脸分组添加人脸信息

接口描述:通过本接口调用,用户可以向指定人脸分组添加人脸信息。

请求链接:/face/add

接口版本:v2.0

接口参数

Content-Type:application/form-data

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项)100939020409
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 7948
group_idstring人脸分组唯一标识ID578968813726
namestring人脸对应姓名Mike
picfile人脸对应图片文件(1M以下)face.png
genderint人脸对应性别 (1-男性, 2 女性)1
age_rangeint人脸对应年龄段4
customer_value1string人脸分组自定义扩展字段1 内容1
customer_value2string人脸分组自定义扩展字段2 内容sing
customer_value3string人脸分组自定义扩展字段3 内容americans
customer_value4string人脸分组自定义扩展字段4 内容fat
customer_value5string人脸分组自定义扩展字段5 内容short hair

请求示例

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/add",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "group_id": "578968813726",
    "name": "Mike",
    "pic": {
      "value": fs.createReadStream("/D:/image/face.png"),
      "options": {
        "filename": "/D:/image/face.png",
        "contentType": null
      }
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值

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

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数
5520已经达到最大人脸分组数量或已经达到最大人脸容量

备注: 人脸图片添加入人脸库后,商米数字店铺平台会进行相应处理,并生成对应的face_id。由于处理图片信息需要一定时间,所以目前采用异步消息通知处理结果。

具体请参考 《消息推送中心》文档

同步处理并返回方式正在开发中。

3.3.9 修改指定人脸的属性信息

接口描述:通过本接口调用,用户可以修改指定人脸的属性信息。

请求链接:/face/update

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 100939020409
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 7948
group_idstring人脸分组唯一标识ID578968813726
face_idstring
人脸唯一标识ID578968751459
namestring人脸对应姓名Mike
genderint人脸对应性别 (1 – 男, 2 – 女)1
age_rangeint人脸对应年龄段4
customer_value1string人脸分组自定义扩展字段1 内容1
customer_value2string人脸分组自定义扩展字段2 内容sing
customer_value3string人脸分组自定义扩展字段3 内容americans
customer_value4string人脸分组自定义扩展字段4 内容fat
customer_value5string人脸分组自定义扩展字段5 内容short hair

字段描述:age_range

age_range 取值说明
10~6岁
27~12岁
313~18岁
419~28岁
529~35岁
636~45岁
746~55岁
856~ 岁

请求示例:  

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/update",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "group_id": "578968813726",
    "face_id": "578968751459",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

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

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数
5520已经达到最大人脸分组数量或已经达到最大人脸容量
5521指定人脸分组中不存在该人脸信息

3.3.10 从指定人脸分组中删除人脸信息

接口描述:通过本接口调用,用户可以从指定人脸分组中删除人脸信息。

请求链接:/face/delete

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 100939020409
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 7948
group_idstring人脸分组唯一标识ID578968813726
face_id_listarray[string]人脸唯一标识ID[578968751459]

请求示例:  

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/delete",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "group_id": "578968813726",
    "face_id_list": ["578968751459"],
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

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

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数

3.3.11 将指定人脸在人脸分组中迁移

接口描述:通过本接口调用,用户可以将指定人脸在人脸分组中迁移。

请求链接:/face/group/move

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 100939020409
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 7948
source_group_idstring原始人脸分组唯一标识ID578968813726
target_group_idstring目标人脸分组唯一标识ID578968813727
face_id_listarray[string]需要迁移的人脸ID数组[578968751459]

请求示例:  

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/group/move",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "source_group_id": "578968813726",
    "target_group_id": "578968813727",
    "face_id_list": ["578968751459"],
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

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

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数
5520已经达到最大人脸分组数量或已经达到最大人脸容量
5521指定人脸分组中不存在该人脸信息
5522人脸库不存在

3.3.12 修改生客分组移组条件

接口描述:通过本接口调用,用户可以修改生客库移库条件。

请求链接:/face/group/updateMoveStrategy

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 100939020409
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 7948
target_group_idstring目标人脸分组唯一标识ID578968813727
thresholdint达到生客移库条件的生客出现次数4
periodint达到生客移库条件的计数周期,以秒为单位604800

请求示例

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/face/group/updateMoveStrategy",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "target_group_id": "578968813727",
    "threshold": 4,
    "period": 604800,
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值

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

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数
5506未查询到该数据
5520已经达到最大人脸分组数量或已经达到最大人脸容量
5525默认人脸分组的信息无法修改

设备管理接口

2.1 接口描述

设备管理接口用来管理智能摄像机设备的基本属性,比如名称等。

2.2 接口列表

接口名称接口描述
/device/ipc/getList获取设备列表
/device/ipc/getListByCompany获取商铺下所有设备列表
/device/ipc/getInfo获取设备基本信息
/device/ipc/updateName修改设备名称
/device/ipc/bind绑定设备
/device/ipc/unbind解绑设备

2.3 接口详情

2.3.1 获取设备列表

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

请求链接:/device/ipc/getList

接口版本:v2.0

接口参数

参数名称是否必须类型说明 示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 560279010307
shop_idstring
店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 10096

请求示例: 

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/device/ipc/getList",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581333970,
    "random": "5dsf6698",
    "sign": "5EA14F9445D72DDE113AA95B04797D29"
  }

返回值: 

{
    "data": {
        "total_count": 1,
        "ipc_list": [
            {
                "ipc_id": "549755805878",
                "ipc_sn": "C101P98200023",
                "ipc_name": "小松松大魔王",
                "model_name": "FM010",
                "software_version": "1.2.6",
                "check_version_time": 1566365781,
                "connect_time": 1565951330,
                "active_status": 0,
                "screenshot_url": "https://xxxxxxxx/IMG/IPC/e36654e8a95a9ad27b5bb585a0f7df50a0de0dd6e0aeaee47b4e34c4f4636f9a"
            }
        ]
    },
    "code": 0,  /* 其他错误参考错误列表 */
    "msg": "succeed"
}

返回字段描述:active_status

active_status 取值说明
0设备离线
1设备在线

错误码:

错误码说明
5000数据库错误
5013未查询到数据
5041请求中未找到shop_id参数

2.3.2 获取设备基本信息

接口描述:通过本接口调用,用户可以获取指定设备基本信息。

请求链接:/device/ipc/getInfo

接口版本:v2.0

接口参数

参数名称是否必须类型说明 示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 560279010307
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 10096
ipc_idstring摄像机设备唯一ID(与ipc_sn必出现其一,若同时输入,必须一致) 549755805878
ipc_snstring摄像机SN(与ipc_id必出现其一, 若同时输入,必须一致 )C101P98200023

请求示例 : 

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/device/ipc/getInfo",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "ipc_id": "549755805878",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581333970,
    "random": "5dsf6698",
    "sign": "140E3195C0F00DB09457E015AA79D79B"
  }

返回值: 

{
    "data": {
        "ipc_id": "549755805878",
        "ipc_sn": "C101P98200023",
        "ipc_name": "小松松大魔王",
        "model_name": "FM010",
        "software_version": "1.2.6",
        "check_version_time": 1566365781,
        "connect_time": 1565951330,
        "active_status": 0,
        "screenshot_url": "https://xxxxxxxx/IMG/IPC/e36654e8a95a9ad27b5bb585a0f7df50a0de0dd6e0aeaee47b4e34c4f4636f9a"
    },
    "code": 0,  /* 其他错误参考错误列表 */
    "msg": "succeed"
}

返回字段描述:active_status

active_status 取值说明
0设备离线
1设备在线

错误码:

错误码说明
5000数据库错误
5013未找到数据
5041请求中未找到shop_id参数
5501ipc设备不存在

2.3.3 修改设备名称

接口描述:通过本接口调用,用户可以修改设备名称。

请求链接:/device/ipc/updateName

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 560279010307
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 10096
ipc_idstring摄像机设备唯一ID 摄像机SN(与ipc_sn必出现其一, 若同时输入,必须一致 549755805878
ipc_snstring 摄像机SN(与ipc_id必出现其一, 若同时输入,必须一致 )C101P98200023
ipc_namestring修改的新设备名称示例设备

请求示例

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/device/ipc/updateName",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "ipc_id": "549755805878",
    "ipc_name": "示例设备",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581333970,
    "random": "5dsf6698",
    "sign": "140E3195C0F00DB09457E015AA79D79B"
  }

返回值: 

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

错误码:

错误码说明
5000数据库错误
5011与设备通讯错误
5013未找到数据
5041请求中未找到shop_id参数
5501ipc设备不存在
5506数据库中未找到该ipc设备信息
5510设备未绑定

2.3.4 绑定设备

接口描述:通过本接口调用,用户可以绑定指定设备。

请求链接:/device/ipc/bind

接口版本:v2.0

接口参数

参数名称 是否必须 类型 说明 示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 560279010307
shop_id string 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 10096
ipc_sn string 摄像机设备SN号 C101D96U00034
mac string 摄像机设备mac地址 0C25766F5705

请求示例:

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/device/ipc/bind",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "ipc_sn": "C201D8BS00089",
    "mac":"0C25766F5705",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1578972864,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回示例:

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

错误码:

错误码 说明
5000 数据库错误
5013 未找到数据
5020 无效参数
5041 请求中未找到shop_id参数
5079 无效mac地址
5501 设备不存在
5509 设备被绑定

2.3.5 解绑设备

接口描述:通过本接口调用,用户可以解绑指定设备。

请求链接:/device/ipc/unbind

接口版本:v2.0

接口参数

参数名称 是否必须 类型 说明 示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 560279010307
shop_id string 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 10096
ipc_sn string 摄像机设备SN号(ipc_sn与ipc_id有其一即可) C101D96U00034
ipc_id string 摄像机设备唯一ID(ipc_sn与ipc_id有其一即可) 549755805878

请求示例:

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/device/ipc/unbind",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_shop_no": "560279010307",
    "ipc_sn": "C201D8BS00089",
    "ipc_id":"549755805878",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1578972864,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回示例:

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

错误码:

错误码 说明
5000 数据库错误
5013 未查询到数据
5020 无效参数
5041 请求中未找到shop_id参数
5501 设备不存在
5510 设备未绑定

2.3.6 获取商户下设备列表

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

请求链接:/device/ipc/getListByCompany

接口版本:v2.0

接口参数

参数名称是否必须类型说明 示例
sunmi_company_no string 商米数字商户唯一编号(v2.0之后为必填项) 560279010307

请求示例: 

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/device/ipc/getListByCompany",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "sunmi_company_no": "560279010307",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581333970,
    "random": "5dsf6698",
    "sign": "5EA14F9445D72DDE113AA95B04797D29"
  }

返回值: 

{
    "data": {
        "total_count": 1,
        "ipc_list": [
            {
                "ipc_id": "549755811632",
                "ipc_sn": "C101E96500011",
                "ipc_name": "My Camera",
                "model_name": "FM010",
                "software_version": "1.0.0",
                "active_status": 1
            }
        ]
    },
    "code": 0,  /* 其他错误参考错误列表 */
    "msg": "succeed"
}

返回字段描述:active_status

active_status 取值说明
0设备离线
1设备在线

错误码:

错误码说明
5000数据库错误
5041绑定关系有问题
5013未查询到数据

模板管理接口

7.1 接口描述

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

7.2 接口列表

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

7.3 接口详情

7.3.1 上传创建模板

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

请求链接:/template/create

接口参数

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

返回值: 

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

错误码:

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

7.3.2 更新指定模板

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

请求链接:/template/update

接口参数

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

返回值: 

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

错误码:

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

7.3.3 获取模板列表

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

请求链接:/template/getList

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容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_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容v2.0之前版本的字段在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
template_idstring模板唯一标识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_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
template_id_listarray模板唯一标识ID列表

返回值: 

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

错误码:

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

基站管理接口

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

6.3 接口详情

6.3.1 绑定基站到门店

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

请求链接:/device/ap/bind

接口参数

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

返回值: 

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

错误码:

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

6.3.2 从门店解绑基站

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

请求链接:/device/ap/unbind

接口参数

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


返回值
: 

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

错误码:

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

6.3.3 获取基站列表

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

请求链接:/device/ap/getList

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容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_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
ap_idstring无线基站编号

返回值: 

{
    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_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
ap_idstring无线基站编号
ap_namestring修改的名字

返回值: 

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

错误码:

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

6.3.6 重启基站

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

请求链接:/device/ap/reboot

接口参数

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

返回值: 

{
    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创建,无权查看

闪灯接口

5.1 接口描述

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

5.2 接口列表

接口名称接口
指定价签闪灯/device/esl/flashLed

5.3 接口详情

5.3.1 指定价签闪灯

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

请求链接:/device/esl/flashLed

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
esl_idstring电子价签数据库ID转码
channelint (默认为4) LED颜色: 1-白, 2-蓝, 4-绿, 8-红,512-青, 1024-紫, 2048-黄
cycleint (默认为100) 单次闪烁周期, 单位10ms;即 1s=100个cycle
durationint (默认为8) 总共闪灯次数

返回值: 

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

错误码

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

价签管理接口

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_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容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_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
esl_idstring电子价签数据库ID转码

返回值: 

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

错误码:

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

4.3.3 获取价签列表

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

请求链接:/device/esl/getList

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容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_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号(此参数为后向兼容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_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
esl_idstring电子价签数据库ID转码
picfile上传的刷图文件

图片分辨率:

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

电子价签型号支持颜色支持图片分辨率(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_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容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 创建,无权查看

商品管理接口

3.1 接口描述

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

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

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

3.2 接口列表

接口名称接口
商品绑定价签/product/bindEsl
商品解绑价签/product/unbindEsl
获取商品绑定价签/product/getBindEslList
修改商品绑定价签的模板/product/updateTemplate
获取商品列表/product/getList
获取商品详情/product/getInfo

3.3 接口详情

3.3.1 商品绑定价签

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

请求链接:/product/bindEsl

接口参数

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

返回值: 

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

错误码:

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


3.3.2 商品解绑价签

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

请求链接:/product/unbindEsl

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容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价签未绑定
5338价签已被其他店铺绑定    
5342非法价签图片
5006OSS错误
5041非法对接软件店铺

3.3.3 获取商品绑定价签

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

请求链接:/product/getBindEslList

接口参数

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


返回值
: 

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

错误码:

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

3.3.5 获取商品列表

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

请求链接:/product/getList

接口参数

参数名称是否必须类型说明
sunmi_shop_nostring商米数字店铺平台中门店的唯一编号(v2.0之后为必填项)
shop_idstring第三方对接软件中门店的唯一编号
(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
keywordstring关键字
page_numint页码
page_sizeint每页记录数

返回值: 

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

错误码:(历史原因,成功为0,失败为1)

3.3.6 获取商品信息

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

请求链接:/product/getInfo

接口参数

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

错误码:(历史原因,成功为0,失败为1)

收银审计

1 场景描述

本文档主要是描述针对于IPC对接用户需要使用收银审计功能的对接步骤。基于商米的IPC摄像机和软件商传入的门店订单信息,商米数字店铺的收银审计服务可以针对每笔交易产生收银审计视频。用户可以在商米助手APP内查看,也可以通过接口方式导出到第三方平台进行观看。

2 主要流程

下图的流程描述了需要对接的整个流程和步骤,主要分为几个步骤:

  1. 创建商户/门店以及获得用户授权
  2. 绑定IPC设备到门店
  3. 同步订单数据到商米数字店铺平台
  4. 用户在商米助手上开启收银审计服务
  5. 用户可以通过商米助手APP查看生成的每日收银审计视频
  6. 通过openAPI接口,可以导出收银审计视频到对接的软件平台

3 详细流程

3.1 商户/门店创建

目前商米数字店铺提供两种创建模式,可以通过商米助手APP或商米数字店铺(store.sunmi.com)直接创建,也可以通过openAPI进行商户和门店的创建。

3.1.1 通过商米助手APP和商米数字店铺进行门店创建和授权

您可以从IOS和Android应用市场下载商米助手APP,安装之后进行用户注册和商户创建:

您也可以通过web页面(store.sunmi.com)进行用户和商户的创建。

在商米数字店铺平台创建完成商户和门店之后,要和第三方平台进行授权。用户在数字店铺页面上可以获取门店授权码(24小时内有效)。

在获取到门店编号以及店铺密钥之后,可以通过调用openAPI接口 (/shop/bind)进行门店授权。【接口详情: 商米数字店铺开放平台->店铺绑定和授权->门店接口->4.3.1 绑定商米门店】

3.1.2 通过openAPI接口进行商户和门店的创建

如果您希望通过纯接口的方式进行操作,用户无需手动注册和提供店铺密钥。也可以通过openAPI接口直接创建商户和门店。接口调用顺序如下

  1. 调用创建商户接口 /company/create
  2. 调用创建商户接口 /shop/create, 将门店添加到刚才创建的商户下
    【接口详情: 商米数字店铺开放平台-> 店铺绑定和授权->商户接口->3.3.1 创建商户】
    【接口详情: 商米数字店铺开放平台-> 店铺绑定和授权->门店接口 ->4.3.4 创建门店】

注:通过接口创建的商户和门店无需再次经过授权绑定环节,可以直接使用后续操作。

3.2 绑定IPC设备到门店

商米数字店铺提供了两种设备绑定方法,您可以根据需要选择其中任意一种。

3.2.1 通过商米助手进行IPC绑定门店

您可以在商米助手APP设备页上选择门店并进行设备绑定。绑定完成之后会在设备列表中展示出来。

3.2.2 通过openAPI接口进行IPC绑定门店

您也可以使用openAPI接口直接绑定IPC到指定门店内。调用接口 /device/ipc/bind 。
【接口详情: 商米数字店铺开放平台->智能摄像机IPC->云端API->4.3.4 绑定设备】

3.3 同步订单数据到商米数字店铺

要使用收银审计功能,您需要首先同步订单数据到商米数字店铺。通过以下接口可以进行订单同步操作 /order/create

【接口详情: 商米数字店铺开放平台-> 订单库->3.1.2 创建订单推送接口】

3.4 收银审计服务开通

用户需要在商米助手APP中,选择需要开通收银审计服务的门店和对应设备。

您可以在服务页 -> 收银审计进入收银审计服务。并选择新建服务。

3.5 商米助手查看收银审计视频

当订单正常导入并且服务开通之后,您即可在收银审计服务页面查看每笔订单对应的收银审计视频。

3.6 openAPI获取收银审计视频列表

如果您需要导出收银审计视频,可以通过以下接口: /service/audit/getVideoList
【接口详情: 商米数字店铺开放平台-> 增值服务->3.3.2 获取收银视频列表 】

客流统计和会员到店推送

1 场景描述

本文档主要是描述针对于IPC对接用户需要使用客流统计和会员到店推送等功能所需要的对接过程和步骤。

2 主要流程

下图的流程描述了需要对接的整个流程和步骤,主要分为几个步骤:

  1. 创建商户/门店以及获得用户授权
  2. 绑定IPC设备到门店
  3. 设置和同步人脸库基础数据到门店
  4. IPC设备捕获数据并上传云端
  5. 通过openAPI和消息中心获取相应信息

3 详细流程

3.1 商户/门店创建

目前商米数字店铺提供两种创建模式,可以通过商米助手APP或商米数字店铺(store.sunmi.com)直接创建,也可以通过openAPI进行商户和门店的创建。

3.1.1 通过商米助手APP和商米数字店铺进行门店创建和授权

您可以从IOS和Android应用市场下载商米助手APP,安装之后进行用户注册和商户创建:

您也可以通过web页面(store.sunmi.com)进行用户和商户的创建。

在商米数字店铺平台创建完成商户和门店之后,要和第三方平台进行授权。用户在数字店铺页面上可以获取门店授权码(24小时内有效)。

在获取到门店编号以及店铺密钥之后,可以通过调用openAPI接口 (/shop/bind)进行门店授权。 【接口详情: 商米数字店铺开放平台->店铺绑定和授权->门店接口->4.3.1 绑定商米门店】

3.1.2 通过openAPI接口进行商户和门店的创建

如果您希望通过纯接口的方式进行操作,用户无需手动注册和提供店铺密钥。也可以通过openAPI接口直接创建商户和门店。接口调用顺序如下

  1. 调用创建商户接口 /company/create
  2. 调用创建商户接口 /shop/create, 将门店添加到刚才创建的商户下
    【接口详情: 商米数字店铺开放平台-> 店铺绑定和授权->商户接口->3.3.1 创建商户】
  3. 【接口详情: 商米数字店铺开放平台-> 店铺绑定和授权->门店接口 ->4.3.4 创建门店】

注:通过接口创建的商户和门店无需再次经过授权绑定环节,可以直接使用后续操作。

3.2 绑定IPC设备到门店

商米数字店铺提供了两种设备绑定方法,您可以根据需要选择其中任意一种。

3.2.1 通过商米助手进行IPC绑定门店

您可以在商米助手APP设备页上选择门店并进行设备绑定。绑定完成之后会在设备列表中展示出来。

3.2.2 通过openAPI接口进行IPC绑定门店

您也可以使用openAPI接口直接绑定IPC到指定门店内。调用接口 /device/ipc/bind 。
【接口详情: 商米数字店铺开放平台->智能摄像机IPC->云端API->2.3.4 绑定设备】

3.3 人脸数据导入

要导入和使用人脸信息,您需要经过两步操作:
1)创建或指定人脸分组, 调用创建人脸分组接口 /face/group/create
【接口详情: 商米数字店铺开放平台-> 智能摄像机IPC->云端API->3.3.3 添加人脸分组】

2) 将人脸图片及相关信息添加到人脸分组, 调用添加人脸接口 /face/add
【接口详情: 商米数字店铺开放平台-> 智能摄像机IPC->云端API->5.3.8 向指定人脸分组添加人脸信息】

3.4 设备数据上报

在完成以上操作,并将IPC设备安装完成之后,通过商米助手APP对IPC设备进行基础配置(如进店划线,对焦等操作)。您可以在商米助手和商米数字店铺钟获取多维度客流统计数据。

3.5 接口获取客流数据

如果需要客流数据导出,您可以调用相关的客流openAPI接口。如下图所示:

【接口详情: 商米数字店铺开放平台-> 智能摄像机IPC->云端API->6 人流统计接口】

3.6 实时到店推送

如果您需要实时到店推送信息,可以使用平台提供的消息中心的能力。

如果您想要针对特定门店的人员到店进行推送,可以调用以下openAPI函数注册回调地址: /hook/add
【接口详情: 商米数字店铺开放平台-> 消息中心->消息订阅接口->5.3.1 增加消息监听 】.

具体的回调消息类型以及返回请求的内容,请参考【 商米数字店铺开放平台-> 消息中心-> 智能摄像机IPC事件及消息示例 】

如果您需要为所有门店指定统一的回调地址,请联系我们的技术服务人员,我们会进行后台统一配置。

云打印机CP事件及消息示例

1 事件列表

event取值说明
6001未经处理的文字小票上传消息
6002未经处理的图片小票上传消息
6003经过处理的小票消息

2 事件消息示例

2.1 未经处理的文字小票上传消息(event=6001)

报文格式: application/x-www-form-urlencoded;param=value;charset=UTF-8

消息体格式:
{ 
  "app_id": 'CSJGYI6T8P237',                //唯一标识接入身份,联系商米数字店铺提供
  "event": '6002',                          // 触发消息的类型
  "payload": '{
       "id":"70dcd2f600e45736e1",           // 系统生成的小票ID
       "sn":"N302D9WZC0064",                // 打印设备SN
       "text": "abc"                        // 文字小票内容
  }',
  "random": 'NDL8GXR',                          // 随机字符串,由数字和字母组成,长度范围为6-10位
  "shop_id": '29203',                           // 店铺在SaaS软件体系下的唯一标识, 没有或者不需要则为空
  "sign": '738D9FF2482D59E5DC1FB32B6F445464',   //签名校验
  "sunmi_shop_no": '28393437387',               // 商米数字店铺平台门店唯一编号, 没有或者不需要则为空
  "timestamp": '1604567375'                     //当前的unix timestamp,精度到秒级,10位数字
}

备注:payload字段对应的值为string类型,解析对此string类型内容进行json解析

2.2 未经处理的图片小票上传消息 (event=6002)

报文格式: application/x-www-form-urlencoded;param=value;charset=UTF-8

消息体格式:
{ 
  "app_id": 'CSJGYI6T8P237',                //唯一标识接入身份,联系商米数字店铺提供
  "event": '6002',                          // 触发消息的类型
  "payload": '{
       "id":"70dcd2f600e45736e1",           // 系统生成的小票ID
       "sn":"N302D9WZC0064",                // 打印设备SN
       "base64_image":"DKJOIFDNLKSDJLSJDISDNLKFJDLSLDJF==",  // 图片小票的base64 encoded string
  }',
  "random": 'NDL8GXR',                          // 随机字符串,由数字和字母组成,长度范围为6-10位
  "shop_id": '29203',                           // 店铺在SaaS软件体系下的唯一标识, 没有或者不需要则为空
  "sign": '738D9FF2482D59E5DC1FB32B6F445464',   //签名校验
  "sunmi_shop_no": '28393437387',               // 商米数字店铺平台门店唯一编号, 没有或者不需要则为空
  "timestamp": '1604567375'                     //当前的unix timestamp,精度到秒级,10位数字
}

备注:payload字段对应的值为string类型,解析对此string类型内容进行json解析

2.3 经过处理的小票消息 (event=6003)

报文格式: application/x-www-form-urlencoded;param=value;charset=UTF-8

消息体格式:
{ 
  "app_id": 'CSJGYI6T8P237',                //唯一标识接入身份,联系商米数字店铺提供
  "event": '6003',                          // 触发消息的类型
  "payload": '{
       "id":"70dcd2f600e45736e1",           // 系统生成的小票ID
       "sn":"N302D9WZC0064",                // 打印设备SN
       "order_time":"2020-11-05 17:45:00",  // 小票生成时间 
       "order_id":"202011051707",           // 小票上的订单ID 
       "order_received_amount":"20",          // 小票金额 
       "sales_detail_list":[                // 明细列表
            { "amount":"4",                   // 商品单价
              "item":"维他柠檬茶",           // 商品名字
              "quantity":"1"                  // 商品数量
            }, 
            {"amount":"7","item":"梅汤","quantity":"1"},
            {"amount":"6","item":"旺仔牛奶","quantity":"1"}, 
            {"amount":"3","item":"罐","quantity":"1"}
      ]
  }',
  "random": 'NDL8GXR',                          // 随机字符串,由数字和字母组成,长度范围为6-10位
  "shop_id": '29203',                           // 店铺在SaaS软件体系下的唯一标识, 没有或者不需要则为空
  "sign": '738D9FF2482D59E5DC1FB32B6F445464',   //签名校验
  "sunmi_shop_no": '28393437387',               // 商米数字店铺平台门店唯一编号, 没有或者不需要则为空
  "timestamp": '1604567375'                     //当前的unix timestamp,精度到秒级,10位数字
}

备注:payload字段对应的值为string类型,解析对此string类型内容进行json解析

附录:签名sign生成规则

2.1 协议说明

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

2.2 签名规则

对于所有的接入者,数字店铺开放平台会分配以下内容:

  • app_id: 唯一标识接入身份
  • secret_key: 该用户独有的签名校验

签名规则应用于对HTTP请求中的参数进行MD5签名,规则顺序如下:

  1. 参数必须包含random字段,为一个随机字符串,由数字和字母组成,长度范围为6-10位
  2. 参数必须包含timestamp字段 ,为当前的unix timestamp,精度到秒级,10位数字, 格式可以参考 https://tool.chinaz.com/tools/unixtime.aspx
  3. 参数必须包含app_id字段
  4. 首先对于所有包含key的传递参数按照ASCII码顺序从小到大排序,将key-value键值对依此组成字符串 (文件参数不参与验签)
  5. 在字符串尾部拼接该SaaS厂商独有的签名校验secret_key值,拼接方法见例子详述
  6. 对字符串进行MD5签名
  7. 对生成的MD5签名转化为全大写