Manage Cards

This topic describes the API operations used to manage cards.

Request method	API	Description
GET	/v1.0/iot-02/building/rsa	Get an RSA public key
POST	/v1.0/iot-02/building/cards	Issue cards
PUT	/v1.0/iot-02/building/cards/actions/bind-face	Bind a card with a face image
PUT	/v1.0/iot-02/building/cards/actions/report-loss	Report a lost card
PUT	/v1.0/iot-02/building/cards/actions/refund	Remove multiple cards
PUT	/v1.0/iot-02/building/cards/actions/cancel-report-loss	Cancel reporting a lost card
PUT	/v1.0/iot-02/building/cards/actions/replace	Replace a card
GET	/v1.0/iot-02/building/cards	Query a list of cards
GET	/v1.0/iot-02/building/cards/actions/bind-face-card	Get the details of a card bound with a user’s face image
GET	/v1.0/iot-02/building/cards/actions/find-card-no	Get the details of a card by project ID and card number

Get an RSA public key

Functional description

Get the information about an RSA public key.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project 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

{
  "publicKey": "String // The public key"
}

Sample request

{
  "projectId": "The project ID"
}

Sample response

{
  "publicKey": "The public key"
}

Issue cards

Functional description

Issue cards.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
personId	String	body	The person ID.	false
cardNoList	String[]	body	The array of card numbers.	false
encryptPassword	String	body	The password.	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

{
  "allSuccess": "boolean // All operations are successful",
  "duplicateCardNoList": "String[] // The list of duplicate card numbers"
}

Sample request

{
  "encryptPassword": "The password",
  "personId": "The person ID",
  "cardNoList": "The array of card numbers",
  "projectId": "The project ID"
}

Sample response

{
  "allSuccess": "All operations are successful",
  "duplicateCardNoList": "The list of duplicate card numbers"
}

Bind a card with a face image

Functional description

Bind a card with a face image.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
personCardId	String	body	The ID of a new card bound with the specified face image.	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

{
  "personCardId": "The ID of a new card bound with the specified face image",
  "projectId": "The project ID"
}

Sample response

boolean{}

Report a lost card

Functional description

Report a lost card.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
personCardId	String	body	The primary key of the specified card.	false
personCardIds	String[]	body	The array of card numbers.	false
cardNo	String	body	The card number.	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

{
  "personCardId": "The primary key of the specified card",
  "personCardIds": "The array of card numbers",
  "projectId": "The project ID",
  "cardNo": "The card number"
}

Sample response

boolean{}

Remove multiple cards

Functional description

Remove multiple cards.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
personCardId	String	body	The primary key of the specified card.	false
personCardIds	String[]	body	The array of card numbers.	false
cardNo	String	body	The card number.	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

{
  "personCardId": "The primary key of the specified card",
  "personCardIds": "The array of card numbers",
  "projectId": "The project ID",
  "cardNo": "The card number"
}

Sample response

boolean{}

Cancel reporting a lost card

Functional description

Cancel reporting a lost card.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
personCardId	String	body	The primary key of the specified card.	false
personCardIds	String[]	body	The array of card numbers.	false
cardNo	String	body	The card number.	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

{
  "personCardId": "The primary key of the specified card",
  "personCardIds": "The array of card numbers",
  "projectId": "The project ID",
  "cardNo": "The card number"
}

Sample response

boolean{}

Replace a card

Functional description

Replace a card.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
personCardId	String	body	The primary key of the specified card.	false
personCardIds	String[]	body	The array of card numbers.	false
cardNo	String	body	The card number.	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

{
  "personCardId": "The primary key of the specified card",
  "personCardIds": "The array of card numbers",
  "projectId": "The project ID",
  "cardNo": "The card number"
}

Sample response

boolean{}

Query a list of cards

Functional description

Query a list of cards.

API endpoint

GET /v1.0/iot-02/building/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 person. 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 // The total number of cards",
  "allNum": "int // The total number of cards",
  "normalNum": "int // The number of normal cards",
  "freezeNum": "int // The number of frozen cards",
  "list": [
    {
      "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

{
  "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

{
  "total": "The total number of cards",
  "allNum": "The total number of cards",
  "normalNum": "The number of normal cards",
  "freezeNum": "The number of frozen cards",
  "list": [
    {
      "list": "Specifies whether a card can be bound with a face image"
    }
  ]
}

Get the details of a card bound with an image

Functional description

Get the details of a card bound with a user’s face image.

API endpoint

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

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

{
  "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"
}

Sample request

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

Sample response

{
  "personCardId": "The card ID of the specified person",
  "cardNo": "The card number",
  "projectId": "The project number",
  "personId": "The person ID",
  "cardType": "The type of a card. 1: physical card, 2: virtual card",
  "cardStatus": "The status of a card. 1: normal, 2: frozen",
  "bindFace": "Specifies whether a card is bound with a face image. 0: not bound, 1: bound",
  "activationTime": "The time when a card is activated",
  "reportLostTime": "The time when a lost card is reported",
  "cancelReportLostTime": "The time when the reporting of a lost card is canceled",
  "containPassword": "Indicates whether a password is set for a card"
}

Get the details of a card by project ID and card number

Functional description

Get the details of a card by project ID and card number.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	true
cardNo	String	body	The card number.	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

{
  "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"
}

Sample request

{
  "projectId": "The project ID",
  "cardNo": "The card number"
}

Sample response

{
  "personCardId": "The card ID of the specified person",
  "cardNo": "The card number",
  "projectId": "The project number",
  "personId": "The person ID",
  "cardType": "The type of a card. 1: physical card, 2: virtual card",
  "cardStatus": "The status of a card. 1: normal, 2: frozen",
  "bindFace": "Specifies whether a card is bound with a face image. 0: not bound, 1: bound",
  "activationTime": "The time when a card is activated",
  "reportLostTime": "The time when a lost card is reported",
  "cancelReportLostTime": "The time when the reporting of a lost card is canceled",
  "containPassword": "Indicates whether a password is set for a card"
}

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.