Example of TTHotel integration

1、Overview

Users want to integrate the hotel card issuing function into their own management system, to realize not to use the TTHotel, but also in their own hotel management system for management at the same time using the hotel card issued or issued passwords, bluetooth keys, remote control of locks and other functions.

2、Prerequisites

1. Go to the official website of TTHotel to download TTHotel app, then create a hotel. It is best to consult the lock supplier (manufacturer) to obtain the supplier number used when creating a hotel. If the lock manufacturer cannot provide the number, the developer can also contact TT hotel customer service to obtain it. After the registration is completed, user can use mobile app to add locks.

2. The hotel administrator account applies for integration in the TTHotel client settings , and obtains the integration parameters through "copy" button. Developers can then use these parameters to obtain the hotelInfo for card issuance and the accessToken for locks management system integration. Deverloper can request API to obtain the data of locks such as building number, floor number, Lock Mac, etc. And those data can also be exported directly in the integration page as excel table.

3、Integrating with TTHotel

Integrating with TTHotel and manage locks by request Open Platform API For example with sending random passcode

1. Export integration data on the TTHotel client(include clientId, clientSecret, username, password with MD5 encryption, Note: Do not use TTHotel password, and do not re-encrypt the exported password), the request get access token API to gain accessToken

2. Use the obtained accessToken to call other APIs:

   • use the hotel lock list API to gain the lock information in the hotel

   • Request get random passcode API to obtain a random passcode

If you use the TTHotel app to add a lock with gateway, you can also request the API to remotely operate the lock which connected to the gateway.

4、How to Integrate with card encoder and demo

Take the card encoder DLL DEMO as an example（demo download address），and take DLL document 、source code as your reference. for integration, please refer integration, for using demo, please refer to Demo

1. Export integration data (client_id and client_secret) in TTHotel client, refer to Prerequisites

   Integration: Request API https://cnapi.ttlock.com/v3/hotel/getInfo to gain hotelInfo, please refer to DLL documnet regarding the details of this API.

   Demo:just fill in the client_id and client_secret and click get hotelInfo

2. After connecting the card issuer, Win+X---device manager---Port, to check the serial port used by the card encoder.

   Integration: after confirming that the card encoder is connected to the serial port, use "int CE_ConnectComm (const char *portName)" to configure the card encoder to connect to the device by connecting to the serial port.

   Demo: just fill in the port and click Connect device port.

   

3. After the serial port configuration is successful, next step is to configure card encoder with hotelinfo within 10 minutes

   Integration: use "int CE_InitCardEncoder(const char *hotelInfo)" to configure card encoder. If card encoder has already been configured before, there is no need to do this step again, this method should use hotelinfo within 10 minutes

   Demo: just click Configure card encoder

4. Change the card encoder's sector to match the hotel's sector. You can check the hotel's sector in the TTHotel---Hotel---Hotel Information in the top options bar. The default sectors used by TTHotels are 12, 13, 14, 15, and 16. Therefore, use this method to configure the sector parameters to "0000000000011111" (1 represents an available sector). Unlocking will only succeed if the lock sector matches the card sector. If the hotel sector has been modified, reconfigure the card encoder sector.

   Integration: This step corresponds to the int CE_SetSectors(const char *sectors) method (Configuring the card issuer sector) in the DLL Manual.

   Demo: Once you know the hotel's sector, you can directly configure it.

   

5. Initialize and encrypt a blank card into a hotel-specific card. If a 106 error message is returned, it means the card has already been encrypted as a card by other hotel's hotelInfo and is not a blank card. Encrypting a blank card into a hotel card is only necessary for the first time you issue a hotel card. You do not need to repeat this process for subsequent card encoders. If you have previously issued a card at any hotel, you can skip this step. When changing hotels, it is best to restore the card to a blank one. This interface requires a hotelinfo function within 10 minutes.

   Integration: This step corresponds to the CE_InitCard(const char *hotelInfo) method in the DLL manual.

   Demo: Click Initialize card as hotel card and place a blank card on the card encoder.

   

6. Request API to gain hotel lock list or Export lock data to excel sheet on the TTHotel client integration page(note that the lock building number and floor number are used, not the building name and floor name), validity period is the timestamps accurate to the second.

   Integration: use "int CE_WriteCard(const char *hotelInfo, int buildNo, int floorNo, const char *mac,unsigned long timestamp, bool allowLockOut)" to write a new unlock data into card, Added unlocking data is superimposed and not overwritten. Then you can use the method "int CE_ReadCard(const char *hotelInfo, char **hotelArray)" to read the data in the card

   Demo: Simply fill in the relevant data and follow the steps

   

5.Notes

• The integration information of TTHotel is similar to creating an application on the open platform. Developers can use its information to manage and control locks (obtain lock-related data, such as lock lists, password lists, etc.). It is worth noting that TTHotel has its own database, so the data generated by calling the open platform API cannot be viewed by the TTHotel client, but can be viewed in the TTHotel app;

• Some customers integrating with TTHotel want to implement both remote card issuance (issuing through a gateway, with the card number sent into the lock) and local card issuance (issuing through a card encoder, with the lock‘s information programmed into the card). Integrating these two methods is not recommended for the following reason: remotely deleting an issued card through the API effectively blacklists the card from the door lock, rendering it unusable on this lock. This can result in the same card being successfully issued but unable to unlock the door when issued through the card encoder. Because both the door lock and the card contain each other's information, and local card issuance is performed offline, the card is blacklisted within the lock to ensure consistency in unlocking.