Online Card Issuance

Last Updated on : 2025-05-30 01:56:03download

The network card issuer is one of the hardware products in the hotel industry solutions, many hotels have the PMS system and the online card issuance system at present, it reflects the ecological integration of Tuya hardware and software for the hotel&residential PaaS system. The platform developer can easily realize some core capabilities by using designated hardware and PaaS interfaces, such as online card issuance, door lock card management, and card issuer management.

Terminology

Term	Explanation
Card Issuer	The card issuer is a hardware for reading and writing operations on the card, it can execute operations such as card reading, writing, authorization, and formatting.
Card	There are various function cards, such as building card, unit card, floor card, etc. There are multiple sectors in the card, and each sector will be written according to the agreed protocol.
Online Card Issuance	Refers to issuing cards online, it is relative to the card issuance in the offline version

Hardware Recommendations

SN	Card Issuer	Product ID	Category Code	Protocol
1	Hotel Card Issuer	9fmzfqdz3ezzrejo	hotelms_4z_2	wifi
2	Hotel Card Issuer	ei1lgxxyhhpjsugh	hotelms_4z_2	wifi
3	Hotel Card Issuer	9fmzfqdz3ezzrejo	zig_gyms	wifi
4	Hotel Card Issuer	ei1lgxxyhhpjsugh	zig_gyms	wifi
5	Information Terminal	vhpt6vdutvws4wsx	nb_ms	wifi

API List

Request method	API	Description
POST	/v1.0/osaas/projects/{project_id}/card-issue-devices/card-issuer/{device_id}/card-info-write	Card issuer card writing: send card writing command to the card issuer device (according to the effective time and expiration time, send the card writing command to the card issuer to generate card information)
POST	/v1.0/osaas/projects/{project_id}/card-issue-devices/card-issuer/{device_id}/card-info-read	Card issuer card reading: send card reading command to the card issuer device, and issue card reading command to the specified card through the card issuer to obtain card information (card information is pushed by Pulsar, and message subscription needs to be enabled in advance)
GET	/v1.0/osaas/projects/{project_id}/card-issue-devices	Obtain the list of locks & card issuers devices under the project (obtain the device information of specific device types such as locks and card issuers under the project through the unique ID of the project)
GET	/v1.0/osaas/rooms/{room_id}/card-issue-devices	Obtain the list of locks & card issuers under the room (obtain the list of specific device types such as locks and card issuers through the unique ID of the room)
POST	/v1.0/osaas/projects/{project_id}/card-issue-devices/lock-devices/{device_id}/cards	Doorlock card operation: issue card (use the unique id of the card generated by the card issuer to issue the door card to the door lock, so as to achieve the operation of unlocking with the specified card)
DELETE	/v1.0/osaas/projects/{project_id}/card-issue-devices/lock-devices/{device_id}/cards/{lock_card_id}	Doorlock card operation: delete card (use the unique id of the card to send a delete card command to the doorlock, so that the card will be invalid for unlocking the doorlock)
PUT	/v1.0/osaas/projects/{project_id}/card-issue-devices/lock-devices/{device_id}/cards/{lock_card_id}/freeze-status	Doorlock card operation: card status modification (use the unique id of the card to modify the status of the card corresponding to the specified doorlock, supporting two operations of freezing and unfreezing)
PUT	/v1.0/osaas/projects/{project_id}/card-issue-devices/lock-devices/{device_id}/cards/{lock_card_id}	Doorlock card operation: card modification (modify the card effective time and expiration time of the corresponding doorlock without using the card issuer to re-make the card)

Error Code

Error Code	Message	Description
10701409	DEVICE_UNSUPPORTED	The device does not support this operation
10701410	CARD_NOT_FOUND	Card does not exist
10701411	LOCK_CARD_DEVICE_TYPE_UNSUPPORTED	Device type is not supported
10701412	DEVICE_OPERATING_NOT_RETRY	Device is operating, no need to retry

Pulsar Event Notification

Check the push message section for the details of message notification related operations.

Code	bizCode&Description
10001	(“cardIssueCommandExecuteReport”, “Card issuer write card report”)
10001	(“fkqCardReadCommandReport”, “card issuer read card report”)
10001	(“lockCreateCardCommandReport”, “Door lock write card reporting”)
10001	(“lockDelCardCommandReport”, “Door lock delete card report”)
10001	(“lockModifyCardCommandReport”, “Door lock modify card report”)
10001	(“lockFreezeCardCommandReport”, “Door lock freeze card reporting”)
10001	(“lockUnFreezeCardCommandReport”, “Door lock unfreeze card report”)

1. Online card issuance - card issuer write card report

BizCode: cardIssueCommandExecuteReport

Description: card issuer card writing event result reporting

Parameter	Type	Description
operateId	String	The unique id of the operation (return value through OpenAPI call)
operateResult	Integer	Operation result
deviceId	String	Device identity
cardId	String	Card unique identification

Operation result details.

Parameter	Description
0	Failure
1	Success
2	Time out
3	Card not detected
4	Illegal card

2. Online card issuance - card issuer read card report

BizCode: fkqCardReadCommandReport

Description: card issuer card reading event result reporting

Parameter	Type	Description
operateId	String	The unique id of the operation (return value through OpenAPI call)
operateResult	Integer	Operation result
deviceId	String	Device identity
cardInfo	JsonString	Card information

Parameter	Type	Description
cardId	String	Card unique identification
cardUid	String	Card hardware identification
effectiveTime	Long	Effective time
invalidTime	Long	Expiration time

Operation result details.

Parameter	Description
0	Failure
1	Success
2	Time out
3	Card not detected
4	Illegal card

3. Lock execution result event reporting - door lock write card report

BizCode: lockCreateCardCommandReport

Description: door lock writing card reporting

Parameter	Type	Description
operateId	String	The unique id of the operation (return value through OpenAPI call)
operateResult	Integer	Operation result
lockCardId	String	The unique identification of the card inside the lock
deviceId	String	Device identity

Operation result details.

Parameter	Description
-1	Reply timed out
1	Failure
2	Success
3	Unlock method duplication
4	Unlock method is full
5	Unlock method does not exist

4. Lock execution result event reporting - door lock card deletion report

BizCode: lockDelCardCommandReport

Description: door lock delete card report

Parameter	Type	Description
operateId	String	The unique id of the operation (return value through OpenAPI call)
operateResult	Integer	Operation result
lockCardId	String	The unique identification of the card inside the lock
deviceId	String	Device identity

5. Lock execution result event report - door lock modify card report

BizCode: lockModifyCardCommandReport

Description: door lock modify card report

Parameter	Type	Description
operateId	String	The unique id of the operation (return value through OpenAPI call)
operateResult	Integer	Operation result
lockCardId	String	The unique identification of the card inside the lock
deviceId	String	Device identity

6. Lock execution result event reporting - door lock freezing card report

BizCode: lockFreezeCardCommandReport

Description: door lock freezing card reporting

Parameter	Type	Description
operateId	String	The unique id of the operation (return value through OpenAPI call)
operateResult	Integer	Operation result
lockCardId	String	The unique identification of the card inside the lock
deviceId	String	Device identity

7. Lock execution result event reporting - door lock unfreezing card report

BizCode: lockUnFreezeCardCommandReport

Description: door lock unfreezing card reporting

Parameter	Type	Description
operateId	String	The unique id of the operation (return value through OpenAPI call)
operateResult	Integer	Operation result
lockCardId	String	The unique identification of the card inside the lock
deviceId	String	Device identity

Prev DocAccess control action execution

Next DocCard Issuer Management