卡片管理

卡片管理

请求方式	API	描述
GET	/v1.0/iot-02/building/rsa	获取 RSA 公钥信息
POST	/v1.0/iot-02/building/cards	开卡
PUT	/v1.0/iot-02/building/cards/actions/bind-face	绑定人脸
PUT	/v1.0/iot-02/building/cards/actions/report-loss	挂失
PUT	/v1.0/iot-02/building/cards/actions/refund	批量退卡
PUT	/v1.0/iot-02/building/cards/actions/cancel-report-loss	解挂
PUT	/v1.0/iot-02/building/cards/actions/replace	换卡
GET	/v1.0/iot-02/building/cards	查询卡片列表
GET	/v1.0/iot-02/building/cards/actions/bind-face-card	获取绑定人脸的卡片
GET	/v1.0/iot-02/building/cards/actions/find-card-no	获取卡片信息

获取 RSA 公钥信息

功能描述

获取 RSA 公钥信息。

接口地址

GET /v1.0/iot-02/building/rsa

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	True

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功。true：成功，false：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Object	返回结果

result 参数说明

{
  "publicKey": "String //公钥"
}

请求示例

{
  "projectId": "项目 ID"
}

响应示例

{
  "publicKey": "公钥"
}

开卡

功能描述

开卡。

接口地址

POST /v1.0/iot-02/building/cards

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	True
personId	String	body	人员 ID	false
cardNoList	String[]	body	卡号数组	false
encryptPassword	String	body	密码	false

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功。true：成功，false：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Object	返回结果

result 参数说明

{
  "allSuccess": "boolean //全部成功",
  "duplicateCardNoList": "String[] //重复的卡号"
}

请求示例

{
  "encryptPassword": "密码",
  "personId": "人员ID",
  "cardNoList": "卡号数组",
  "projectId": "项目ID"
}

响应示例

{
  "allSuccess": "全部成功",
  "duplicateCardNoList": "重复的卡号"
}

绑定人脸

功能描述

绑定人脸。

接口地址

PUT /v1.0/iot-02/building/cards/actions/bind-face

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	true
personCardId	String	body	绑定人脸的新卡 ID	true

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功。true：成功，false：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Object	返回结果

result 参数说明

boolean{}

请求示例

{
  "personCardId": "绑定人脸的新卡 ID",
  "projectId": "项目 ID"
}

响应示例

boolean{}

挂失

功能描述

挂失。

接口地址

PUT /v1.0/iot-02/building/cards/actions/report-loss

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	true
personCardId	String	body	卡片主键	false
personCardIds	String[]	body	卡号数组	false
cardNo	String	body	单张卡号	true

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功。true：成功，false：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Object	返回结果

result 参数说明

boolean{}

请求示例

{
  "personCardId": "卡片主键",
  "personCardIds": "卡号数组",
  "projectId": "项目 ID",
  "cardNo": "单张卡号"
}

响应示例

boolean{}

批量退卡

功能描述

批量退卡。

接口地址

PUT /v1.0/iot-02/building/cards/actions/refund

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	true
personCardId	String	body	卡片主键	false
personCardIds	String[]	body	卡号数组	false
cardNo	String	body	单张卡号	true

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功。true：成功，false：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Object	返回结果

result 参数说明

boolean{}

请求示例

{
  "personCardId": "卡片主键",
  "personCardIds": "卡号数组",
  "projectId": "项目 ID",
  "cardNo": "单张卡号"
}

响应示例

boolean{}

解挂

功能描述

解挂。

接口地址

PUT /v1.0/iot-02/building/cards/actions/cancel-report-loss

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	true
personCardId	String	body	卡片主键	false
personCardIds	String[]	body	卡号数组	false
cardNo	String	body	单张卡号	true

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功。true：成功，false：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Object	返回结果

result 参数说明

boolean{}

请求示例

{
  "personCardId": "卡片主键",
  "personCardIds": "卡号数组",
  "projectId": "项目 ID",
  "cardNo": "单张卡号"
}

响应示例

boolean{}

换卡

功能描述

换卡。

接口地址

PUT /v1.0/iot-02/building/cards/actions/replace

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	true
personCardId	String	body	卡片主键	false
personCardIds	String[]	body	卡号数组	false
cardNo	String	body	单张卡号	true

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功。true：成功，false：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Object	返回结果

result 参数说明

boolean{}

请求示例

{
  "personCardId": "卡片主键",
  "personCardIds": "卡号数组",
  "projectId": "项目 ID",
  "cardNo": "单张卡号"
}

响应示例

boolean{}

查询列表

功能描述

查询列表。

接口地址

GET /v1.0/iot-02/building/cards

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	true
structureId	String	body	组织 ID	false
searchType	int	body	查询类型。 1：只查询 structureId 下直接关联人员 2：查询 structureId 关联及所有下级组织人员（默认）	false
name	String	body	姓名	false
enabled	int	body	是否启用。 1：启用（默认 1） 2：禁用	false
sex	int	body	性别	false
mobile	String	body	手机号	false
feature	String	body	生物特征	false
holdCard	String	body	是否持有卡片。 0：无 1：有	false
containPassword	int	body	是否有卡密码。0-无 1-有	false
page	int	body	当前页	false
pageSize	int	body	每页数	false
cardStatus	int	body	卡状态。 1：正常 2：冻结	false
cardNo	String	body	卡号	false
personId	String	body	人员 ID	false
cardType	int	body	卡类型。 1：实体卡 2：虚拟卡	false

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功。true：成功，false：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Object	返回结果

result 参数说明

{
  "total": "int //卡片总数",
  "allNum": "int //卡片总数",
  "normalNum": "int //正常",
  "freezeNum": "int //冻结",
  "list": [
    {
      "name": "String //姓名",
      "personCardId": "String //人员卡ID",
      "cardNo": "String //卡号",
      "projectId": "String //项目编号",
      "personId": "String //人员ID",
      "cardType": "int //卡类型：1-实体卡，2-虚拟卡",
      "cardStatus": "int //卡状态：1-正常，2-冻结",
      "bindFace": "int //绑定人脸：0-未绑定，1-绑定",
      "activationTime": "long //开卡时间",
      "reportLostTime": "long //挂失时间",
      "cancelReportLostTime": "long //解除挂失时间",
      "containPassword": "int //是否有卡密码",
      "structureNames": "String[] //组织名称",
      "mobileCountry": "String // 电话区号",
      "mobile": "String //手机号",
      "canBindFace": "boolean //是否可以绑定人脸"
    }
  ]
}

请求示例

{
  "searchType": "查询类型。1-只查询 structureId 下直接关联人员，2-查询 structureId 关联及所有下级组织人员（默认）",
  "sex": "性别",
  "mobile": "手机号",
  "cardType": "卡类型：1-实体卡，2-虚拟卡",
  "structureId": "组织ID",
  "pageSize": "每页数",
  "containPassword": "是否有卡密码，0-无，1-有",
  "cardNo": "卡号",
  "enabled": "是否启用，1-启用（默认1） ，2-禁用",
  "feature": "生物特征",
  "holdCard": "是否持有卡片，0-无，1-有",
  "name": "姓名",
  "personId": "人员ID",
  "page": "当前页",
  "projectId": "项目ID",
  "cardStatus": "卡状态，1-正常，2-冻结"
}

响应示例

{
  "total": "卡片总数",
  "allNum": "卡片总数",
  "normalNum": "正常",
  "freezeNum": "冻结",
  "list": [
    {
      "list": "是否可以绑定人脸"
    }
  ]
}

获取人员绑定人脸的卡片

功能描述

获取人员绑定人脸的卡片。

接口地址

GET /v1.0/iot-02/building/cards/actions/bind-face-card

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	true
personId	String	body	人员 ID	true

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功。true：成功，false：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Object	返回结果

result 参数说明

{
  "personCardId": "String //人员卡 ID",
  "cardNo": "String //卡号",
  "projectId": "String //项目编号",
  "personId": "String //人员 ID",
  "cardType": "int //卡类型：1-实体卡，2-虚拟卡",
  "cardStatus": "int //卡状态：1-正常，2-冻结",
  "bindFace": "int //绑定人脸：0-未绑定，1-绑定",
  "activationTime": "long //开卡时间",
  "reportLostTime": "long //挂失时间",
  "cancelReportLostTime": "long //解除挂失时间",
  "containPassword": "int //卡密码"
}

请求示例

{
  "personId": "人员 ID",
  "projectId": "项目 ID"
}

响应示例

{
  "personCardId": "人员卡 ID",
  "cardNo": "卡号",
  "projectId": "项目编号",
  "personId": "人员 ID",
  "cardType": "卡类型：1-实体卡，2-虚拟卡",
  "cardStatus": "卡状态：1-正常，2-冻结",
  "bindFace": "绑定人脸：0-未绑定，1-绑定",
  "activationTime": "开卡时间",
  "reportLostTime": "挂失时间",
  "cancelReportLostTime": "解除挂失时间",
  "containPassword": "卡密码"
}

根据项目 ID 及卡号，获取卡片信息

功能描述

根据项目 ID 及卡号，获取卡片信息。

接口地址

GET /v1.0/iot-02/building/cards/actions/find-card-no

请求参数

参数名	类型	参数类型	说明	是否必需
projectId	String	body	项目 ID	true
cardNo	String	body	卡号	true

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功。true：成功，false：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Object	返回结果

result 参数说明

{
  "personCardId": "String //人员卡 ID",
  "cardNo": "String //卡号",
  "projectId": "String //项目编号",
  "personId": "String //人员 ID",
  "cardType": "int //卡类型：1-实体卡，2-虚拟卡",
  "cardStatus": "int //卡状态：1-正常，2-冻结",
  "bindFace": "int //绑定人脸：0-未绑定，1-绑定",
  "activationTime": "long //开卡时间",
  "reportLostTime": "long //挂失时间",
  "cancelReportLostTime": "long //解除挂失时间",
  "containPassword": "int //卡密码"
}

请求示例

{
  "projectId": "项目 ID",
  "cardNo": "卡号"
}

响应示例

{
  "personCardId": "人员卡 ID",
  "cardNo": "卡号",
  "projectId": "项目编号",
  "personId": "人员 ID",
  "cardType": "卡类型：1-实体卡，2-虚拟卡",
  "cardStatus": "卡状态：1-正常，2-冻结",
  "bindFace": "绑定人脸：0-未绑定，1-绑定",
  "activationTime": "开卡时间",
  "reportLostTime": "挂失时间",
  "cancelReportLostTime": "解除挂失时间",
  "containPassword": "卡密码"
}

错误码

以下为该接口常见的业务异常。更多的异常错误，请参见 全局错误码。

错误码	说明
500	系统错误