Manage Cards Held by Persons

Last Updated on : 2023-01-12 07:14:45download

This topic describes the API operations used to manage cards held by persons.

Request method	API	Description
GET	/v1.0/iot-02/building/personnel-cards	Get a list of cards held by persons
GET	/v1.0/iot-02/building/personnel-cards/actions/hold-cards	Get the details of a card held by a person
GET	/v1.0/iot-02/building/personnel-cards/actions/personnel-detail	Get the basic information about the specified person
PUT	/v1.0/iot-02/building/personnel-cards/actions/edit-password	Edit the password of the specified card

Get a list of cards held by persons

Functional description

Get a list of cards held by persons.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
structureId	String	body	The ID of the target organization.	false
searchType	int	body	The query type. Valid values: `1`: Only query persons directly associated with the specified `structureId`. `2`: Query persons associated with the specified `structureId` and all the subordinate organizations. Default value.	false
name	String	body	The name.	false
enabled	int	body	Indicates whether to enable a card. Valid values: `1`: Enable. Default value: `1`. `2`: Disable.	false
sex	int	body	The gender.	false
mobile	String	body	The mobile phone number.	false
feature	String	body	The biometrics.	false
holdCard	String	body	Indicates whether a person holds a card. Valid values: `0`: no `1`: yes	false
containPassword	int	body	Indicates whether a password is set for a card. Valid values: `0`: no `1`: yes	false
page	int	body	The current page number.	false
pageSize	int	body	The number of items to be returned per page.	false
cardStatus	int	body	The status of a card. Valid values: `1`: The card is in normal status. `2`: The card is frozen.	false
cardNo	String	body	The card number.	false
personId	String	body	The person ID.	false
cardType	int	body	The type of a card. Valid values: `1`: physical card. `2`: virtual card.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

{
  "total": "int",
  "list": [
    {
      "personId": "String // The ID of the specified person",
      "name": "String // The name",
      "enabled": "int // Indicates whether to enable a person",
      "sex": "int // The code of the gender",
      "sexStr": "String // The value of the gender",
      "certArea": "String // The area to which the certificate belongs",
      "mobileCountry": "String // The country code",
      "mobile": "String // The mobile phone number",
      "feature": "String // The biometrics",
      "imagePath": "String // The path of the specified image",
      "structureIds": "String[] // The ID of the specified organization",
      "structureNames": "String[] // The organization name",
      "holdCardNum": "int // The number of cards",
      "containPassword": "int // Indicates whether a password is set for a card"
    }
  ]
}

Sample request

{
  "searchType": "The search type. Valid values: 1: Only query persons directly associated with the specified structureId. 2: Query persons associated with the specified structureId and all the subordinate organizations. Default value.",
  "sex": "The gender",
  "mobile": "The mobile phone number",
  "cardType": "The type of a card. 1: physical card, 2: virtual card",
  "structureId": "The organization ID",
  "pageSize": "The number of items to be returned per page",
  "containPassword": "Indicates whether a password is set for a card. 0: no, 1: yes",
  "cardNo": "The card number",
  "enabled": "Indicates whether to enable a card. 1: enable (default value), 2: disable",
  "feature": "The biometrics",
  "holdCard": "Indicates whether a person holds a card. 0: no, 1: yes",
  "name": "The name",
  "personId": "The person ID",
  "page": "The current page number",
  "projectId": "The project ID",
  "cardStatus": "The status of a card. 1: normal, 2: frozen",
}

Sample response

{
    "result": {
        "list": [
            {
                "cert_area": "CN",
                "contain_password": 0,
                "enabled": 1,
                "hold_card_num": 2,
                "image_path": "saas/building/building_faceImg/1663644590a79c781cde7.jpg",
                "mobile": "421****1242",
                "mobile_country": "+86",
                "name": "13541",
                "person_id": "1572065489755312***",
                "sex": 1,
                "sex_str": "Male",
                "structure_ids": [
                    "1439128101413011***"
                ],
                "structure_names": [
                    "Root Organization 66678",
                ]
            }
        ],
        "total": 103
    },
    "success": true,
    "t": 1664188109402,
    "tid": "f65bb75a3d8511ed84fd2237f0528b74"
}

Get the details of a card held by a person

Functional description

Get the details of a card held by a person.

API endpoint

GET /v1.0/iot-02/building/personnel-cards/actions/hold-cards

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
personId	String	body	The person ID.	true
cardStatus	int	body	The status of a card. Valid values: `1`: The card is in normal status. `2`: The card is frozen.	false
cardNo	String	body	The card number used for an accurate query.	true

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

{
  "allNum": "int // The total number of cards held by a person",
  "freezeNum": "int // The number of frozen cards held by a person",
  "normalNum": "int // The number of normal cards held by a person",
  "cardList": [
    {
      "name": "String // The name",
      "personCardId": "String // The card ID of the specified person",
      "cardNo": "String // The card number",
      "projectId": "String // The project number",
      "personId": "String // The ID of the specified person",
      "cardType": "int // The type of a card. 1: physical card, 2: virtual card",
      "cardStatus": "int // The status of a card. 1: normal, 2: frozen",
      "bindFace": "int // Specifies whether a card is bound with a face image. 0: not bound, 1: bound",
      "activationTime": "long // The time when a card is activated",
      "reportLostTime": "long // The time when a lost card is reported",
      "cancelReportLostTime": "long // The time when the reporting of a lost card is canceled",
      "containPassword": "int // Indicates whether a password is set for a card",
      "structureNames": "String[] // The organization name",
      "mobileCountry": "String // The country code",
      "mobile": "String // The mobile phone number",
      "canBindFace": "boolean // Specifies whether a card can be bound with a face image"
    }
  ]
}

Sample request

{
  "personId": "The person ID",
  "projectId": "The project ID",
  "cardNo": "The card number used for an accurate query",
  "cardStatus": "The status of a card. @see com.tuya.lingshu.biz.personcard.enums.PersonCardStatusEnum"
}

Sample response

{
    "result": {
        "all_num": 2,
        "card_list": [
            {
                "activation_time": 1662544806542,
                "bind_face": 1,
                "cancel_report_lost_time": 1662546245334,
                "card_no": "45454567",
                "card_status": 1,
                "card_type": 1,
                "contain_password": 1,
                "person_card_id": "1567452642714648***",
                "person_id": "1567428253323362***",
                "project_id": "1424615984265764***",
                "report_lost_time": 1662546168253
            },
            {
                "activation_time": 1662542164834,
                "bind_face": 0,
                "card_no": "232232232",
                "card_status": 2,
                "card_type": 1,
                "contain_password": 1,
                "person_card_id": "1567441562588217***",
                "person_id": "1567428253323362***",
                "project_id": "1424615984265764***",
                "report_lost_time": 1662544087744
            }
        ],
        "freeze_num": 1,
        "normal_num": 1
    },
    "success": true,
    "t": 1664188173781,
    "tid": "1cceff353d8611ed84fd2237f0528b74"
}

Get the person information

Functional description

Get the basic information about the specified person.

API endpoint

GET /v1.0/iot-02/building/personnel-cards/actions/personnel-detail

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
personId	String	body	The person ID.	true

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

{
  "personId": "String // The ID of the specified person",
  "name": "String // The name",
  "mobileCountry": "String // The country code",
  "mobile": "String // The mobile phone number",
  "imageUrl": "String // The URL of the specified image",
  "imagePath": "String // The path of the specified image",
  "structureNames": "String[] // The organization name",
  "containPassword": "int // Indicates whether a password is set for a card"
}

Sample request

{
  "personId": "The person ID",
  "projectId": "The project ID"
}

Sample response

{
  "personId": "The person ID",
  "name": "The name",
  "mobileCountry": "The country code",
  "mobile": "The mobile phone number",
  "imageUrl": "The URL of the specified image",
  "imagePath": "The path to the specified image",
  "structureNames": "The organization name",
  "containPassword": "Indicates whether a password is set for a card"
}

Edit the password of the specified card

Functional description

Edit the password of the specified card.

API endpoint

PUT /v1.0/iot-02/building/personnel-cards/actions/edit-password

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
personId	String	body	The person ID.	true
clearPassword	boolean	body	Specifies whether to clear a password.	true
encryptPassword	String	body	The encryption password.	true

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

boolean{}

Sample request

{
  "clearPassword": "Specifies whether to clear a password",
  "encryptPassword": "The encryption password",
  "personId": "The person ID",
  "projectId": "The project ID"
}

Sample response

boolean{}

Error code

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error code	Description
500	A system error has occurred while processing your request.

Prev DocManage Cards

Next DocManage Person Permissions