人脸分组管理接口

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/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默认人脸分组的信息无法修改