Frequently Asked Questions

1.Lock

1. How many users can be added to each lock, how many locks can be added to each account, and how many groups can be created?

1.The number of users that can be added to each lock:

-----No limit on the number of authorized administrators, but password, card, fingerprint, depending on the lock model

2. The number of locks that can be added under each account, the number of groups that can be created:

-----No limit

2. How to distinguish the generations of TTlocks? How to determine whether the lock supports certain functions?

The current locks are basically three generations of locks

After adding a lock to the app, the supported functional modules will be displayed in the app. You can also check whether the lock supports certain functions by obtaining the lock's feature value. How to obtain the lock's feature value: get lock details， The parameter “featureValue” among the returned values is the lock‘s feature value, which can be analyzed in detail according to the document: The explanation of featureValue and demonstrate codes

3.How to reset the lock?

1. Delete and reset the lock via Bluetooth in the TTLock App. Steps： Find the corresponding lock in the App---Settings---Delete

2. Disassemble the lock---find the reset button（as the following picture shows)---long press, and after hearing the prompt tone---enter 000# (it needs to be enabled to allow physical reset in the APP).

3. If the above two steps do not work, contact your lock manufacturer for consultation

4.Why doesn't the physical reset button respond?

Check if the physical reset button is disabled on the APP? If the physical reset button is disabled, you can only delete and reset it in the App via Bluetooth with the account that previously added the lock.

5.Why is the response so slow when unlocking with WiFi?

• Wi-Fi lock has enabled the power saving mode(or it is enabled by lock system by default)

• When the lock is in sleeping mode, Cloud Server is not able to send unlock commands in real time.

• For WiFi locks, remote unlocking does not follow the process of cached asynchronous command issuance. need to wake up the WiFi lock first, there are touch wakeup and timed wakeup. Only when the lock is awakened online can it be unlocked. The cached command is executed.

6.Does the smart lock have to be initialized (added) through the App?

You can use the keypad to add a password, IC card, or fingerprint as unlocking methods. However, an uninitialized lock can be initialized by others, which poses a security risk.

7.How to transfer locks and gateways to someone?

1.Delete them in the app and let others add them in the app

2.TTLock App---Settings---transfer lock(s) /transfer gateway---Fill in the recipient's account information

8.common commands on locks

9.What are the top administrators and authorized administrators?

Top admin：The account that adds the lock is the top administrator (the highest administrator)

Authorized admin：Ordinary electronic key users are granted the authority to manage locks, such as sending keys and obtaining passwords. Authorized admins have all permissions except for a few permissions such as deleting locks, reauthorizing, and changing the administrator's unlocking password.

The authorized user must first have an ekey for the current lock. The ekey can be sent to the authorized user through the send ekey API, and then call Key authorization API to complete the authorization.

10.Unlocking fail?

Lock time and invalid passcode may cause this issue, troubleshooting：

1.Check records，in TTLock app--corresponding lock---records，if there isn't any records, you can upload the lock data via bluetooth near the lock（Lock--Settings--Upload Data）

2.After getting the unlocking records, check whether the time is correct and whether the password is valid (mobile app Bluetooth unlocking will automatically calibrate the lock time)

3.A one-time password can only be used once within 6 hours of the start time, otherwise the password will become invalid; a permanent password is valid from the start time and must be used once within 24 hours of the start time, otherwise the password will become invalid; a timed password is valid between the start and end time and must be used once within 24 hours of the start time, otherwise it will become invalid;

11.Devices in TTLock can directly transferred to TTHotel? are TTHotel and TTLock using the same database?

No, you can only delete (reset) and re-add them.

They are not using the same database. For the steps and differences in calling the Open Platform API, please refer to this section: 1. How to Call the Open Platform API.

12.How to tell a lock is a wifilock？

1.Wifilocks, when you're adding wifilocks via TTLock, it will prompt you to configure the network, if you skipped this step, go to lock settings, there is an option named wifi to configure network.

2.Determine by lock feature value，how to get feature value、lock feature value, You can also use this method to check whether the lock supports other functions.

13.How to synchronize lock data with cloud data？

TTLock App---corresponding lock---settings---upload lock data

14.Error when initializing lock {"state":"fail","error":"LOCK_IS_IN_NO_SETTING_MODE"}

Please touch the lock panel to make it light up, then the lock will enter the setting mode.

15.How to calibrate the lock time？

App unlocking via bluetooth will automatically calibrate the lock time. You can also find the corresponding lock in the app---Settings---Lock Time---Calibrate Lock Time

16.What does locked online mean?

Normal locks are Bluetooth locks and lack the ability to communicate with the cloud. Therefore, they cannot receive commands from the cloud API or synchronize data with the cloud server automatically. The lock is online, meaning it is connected to a gateway or is a WiFi lock.

2.Open Platform

1.what is a developer account? what's an application? is there a limit on the number of applications I can apply for?

Developer accounts are used to apply for applications. One account can apply for multiple applications. Each application has its own client_id and client_secret, which will be used in subsequent calls to the open platform API.

Developer accounts have different versions：

Basic: Number of apps you can apply for is 3

Advanced v1: Number of apps you can apply for is 1,000

Advanced v2: Number of apps you can apply for is 1,500

Advanced v3：Number of apps you can apply for is 2,000

2.Can I use a developer account to bind my locks? What is the relationship between a developer account and a TT Lock account?

Developer accounts cannot be bound to locks. To bind a lock (i.e., initialize a lock), you must use the TTLock app.

Use the TTLock account and the client_id and client_secret within the app to call the token API to obtain a TTLock account token. Once you have the token, you can call other APIs to manage locks under your TTLock

3.How to call the open platform APIs?

Step 1: Apply for a developer account on the open platform. Apply for an application within your developer account. After your application is reviewed and approved, you will see the client_id and client_secret in the application.

Step 2: Download TTLock APp and register an account.

Step 3: Obtain a token of your TTLock account using the token API to manage the locks associated with your TTLock account.

Note: The above steps is only for TT Lock. For TTHotel integration, you can skip steps 1 and 2. Go to the TTHotel client, Settings --- Integration --- configure the corresponding information and get the integration information --- use the integration information to call the open platform API.

4.When calling the API to obtain a token, get error message:{the username or password is incorrect}.

1. Check that your account information is a TTLock app account.

2. Check if your account information is correct.

3. Your password must be encrypted with MD5.

5.When calling the API to manage the lock, an error message appears indicating that there is {no permission}.

1. The token was not obtained using the TTLock account that added the lock.

2. The current account does not have authorized administrator privileges.

3. The incorrect lock ID was used.

6.Is there any charge for the open platform?

Simply register a developer account and apply for an app on the open platform. The default version is the basic version, which is free. The basic version has a maximum of 30,000 interface calls per month, Each call counts once, and the call count can be viewed in the application. If the limit is reached, the call will fail and an email notification will be sent.

Email notification: Your app has or will soon exceed the limit for calling the interface this month. Further calls will be prohibited. To avoid impacting your business, please upgrade your developer account promptly.

Users can upgrade as needed.

Upgrade steps: Developer Account --- Basic Information --- Developer Version --- pay and upgrade (takes effect in about five minutes)

7.Does the maximum number of API calls in a single month refer to each application or the total number of all applications?

For each application, for example, the maximum number of calls per month for the basic version is 30,000, so the maximum number of calls for each application under this account is 30,000.

8.Where do the Lock ID and LockData used in API calls come from? Where can I obtain them after successful initialization?

The lock ID (lockId) and lock data (lockdata) are returned by the cloud platform after the lock is successfully initialized and uploaded to the platform. lockId is a unique identifier that remains unchanged even after multiple initializations. lockData is the key, containing encrypted lock information. lockId is the basis for all subsequent remote control, password management, and eKey distribution.

After successful initialization:

The lockId can be viewed in app--lock--basic information, or by calling the API：Get lock list

Lockdata can be obtained using the Get Single Key API：get ekey

9.{"errcode":10004,"errmsg":"invalid grant","description":"token No authorization，token is Expired or revoked authorization"}

Currently your role is an authorized administrator, the token becomes invalid due to expiration of permissions or revocation by the top administrator

10.{"errcode":80000,"errmsg":"date must be current time, in 5 minutes"}

The parameter date used in the API is not the current time and within 5 minutes, please use a timestamp within five minutes of the current time.

3.Integration

1.How to integrate with TTLock？

Step 1: Register an account on Open Platform. This is your developer account. Use this account to apply for an application. After this application gets reviewed and approved by us, you could see the client_id and client_secret in the application you applied.

Step 2: Use the API of getting Access Token to get the accessToken of your ttlock account. Pleae Note : use the username and passcode of your TTLock APP account, not your developer account

Step 3: after you get the accessToken from step2, you could use it to call other APIs, as the following picture shows:

2.How to integrate with TTHotel?

To integrate with TTHotel, you don't need to apply for a developer account and application to get Client_id and Client_secret on our open platform. You can directly go to the client to obtain the integration information. The specific process is as follows:

Step 1. TTHotel--Settings--Integration--Get client_id, client_secret, account and password (ie username and password)

Step 2. Get the token based on the integration information, as shown in the following figure:

Step 3: After obtaining the token, you can call other related APIs, such as obtaining the random password:

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.

3.How to integrate with Card Encoder?

please take the following links as your reference：

1.Integration methods，Card encoder source code、Manual and demo

2.Process of issuing cards with our demo

4.How to control smart locks with Web system？

When operating a smart lock on the web (H5 or browser), you can only access lock information and control operations through the official API (with a gateway or if your lock is a Wi-Fi lock).

Reason: The web client lacks Bluetooth to establish a connection with the smart lock.

Specific process: H5 page → Request API → Cloud server → Gateway (via Bluetooth) → Lock

5.How to store my data on my own server?

Some customers want to store data on their own servers and only execute related commands within the intranet due to security considersations. For this, we provide three integration methods (charged):

• 4.1 Connect with our interface based on your own software (for devices that already have a complete system and are only used for device connection)

  If you have your own server, you only need to connect to our interface. We provide SDK (Android & IOS), Jar package (Server), DLL. Based on the SDK, jar package and manual we provide, customers can develop their own APP and API to interact with the local server.。

  basic flow：

  

• 4.2 Directly use the software we provide (provide a complete system for managing lock devices)

  We will provide the APP、Web、Server and API

  On-premise demo：

  API ：API Demo

  Web ：http://onpremise.ttlock.com/

  App ：https://www.pgyer.com/uEG3

  

• 4.3 Customers conduct secondary development on the original functions based on the source code we provide (used for self-development of software when there are developers available)

6.What's the difference between the on-premise SDK and the open platform SDK?

The methods in the SDK are basically the same, but the lockdata generated by the open platform SDK cannot be used in the on-premise server JAR package.

4.Passcode

1.When deleting a random password via Bluetooth, it says the data does not exist.

The random password must be used once on the lock to be recorded.

2.Why does the password say invalid?

1. The lock's time is incorrect, causing the password to become invalid. Please calibrate the lock's time and try again.

2. A one-time password can only be used once within 6 hours of the start time, otherwise it will become invalid. A permanent password is valid from the start time and must be used once within 24 hours of the start time, otherwise it will become invalid. A time-limited password is valid from the start time and end time, and must be used once within 24 hours of the start time, otherwise it will become invalid.

3.Why can I still unlock the lock even though the password is not in the app?

Some operations may cause the cloud and lock data to become out of sync. Please upload the lock data in the app to synchronize and then check the app.

4.What precautions should I take when sending passwords?

random passcode：

The random password is generated by an algorithm. there are some precautions when sending the random password:

• If the password time range is on the same day, rounding is performed only in half-hour intervals. For example, for time periods like 9:55 - 11:00 and 10:55 - 12:00, the actual time ranges considered are 9:30 - 11:00 and 10:30 - 12:00.

  If the time range is not on the same day, rounding is performed in full-hour intervals.

  If it spans a year, rounding is performed in monthly intervals.

• For time-limited random password type = 3, only one password can be generated within the same time range.

  For passwords on the same day, the start or end time must be staggered by half an hour before a new password can be generated. This means the time periods for the two passwords must be staggered by one hour.

  For passwords on different days, the start or end time must be staggered by one hour. This means the time periods for the two identical passwords must be staggered by one hour.

custom passcode：

Custom passwords only support timed and permanent types. The validity period can be accurate to minutes. Unlike random password, there is no restriction on use within 24 hours or the number of passwords in the same time period.

5.Can the expired timed password and the new timed password have the same time range? Can the custom password have the same time range?

No，yes

6.Will expired custom passwords be automatically deleted? What if the lock runs out of memory?

No, the oldest password will be "pushed out" (deleted) from the lock's memory after the memory is exceeded.

7.When adding a custom password, it prompts that the same password already exists.

Reasons：

• Random passwords are generated by an algorithm, so no two passwords are the same.

• Once a custom password is generated, if you don't manually delete it, it will remain in the lock even after it expires.

• Server data is inconsistent with lock data for some reason.

Solutions：

1.delete passcode by passcode itself：Applicable situation: The lock itself is not connected to the gateway, and the server does not know the password expiration. Therefore, it is impossible to obtain the expired password by obtaining the password list, and the password ID cannot be obtained.

2.delete passcode by passcode ID：get passcode ID first and then call this API to delete the passcode

3.reset passcode---delete all passcodes in the lock

8.Get passwords successfully, but unlocking fails.

1. Ensure the lock ID is correct and the password is within its validity period.

2. Go to the app, Lock, then Settings, Lock Time, and calibrate the lock time, then try again.

3. Custom password: If addType = 1, first use the SDK method to send the password and then call the API to synchronize with the cloud server. If addType = 2, ensure the lock is online (i.e., connected to a gateway or using Wi-Fi). You can then upload the lock data and check the password status in the app.

5.Gateway/WiFiLock

1.What is a gateway? How does a gateway connect to a lock? Is the relationship between locks and gateways many-to-many?

1.The smart lock itself is not connected to the Internet and can only communicate with Bluetooth. The gateway is a small device that can be connected to the cloud server and lock, making remote management of the smart lock possible.

2.Once the gateway is initialized, it will automatically search for nearby locks. If the lock and gateway found belong to the same administrator account, they will be automatically associated, so please make sure that the lock and gateway are added with the same account.

3.yes, you can query the relationship and signal strength between the lock and gateway by using the Get Gateway Managed Lock List and Get Lock Connected Gateway List . When initiating a remote operation to the lock, the system will select the gateway with the best signal strength to issue the operation command.

2.How to add a gateway in the App？

take G2 gateway as an example：

3.Calling the unlock API through the gateway returns errcode -4043 (this lock does not support this operation)

If you try to remotely unlock your lock with a gateway or WiFi lock and receive an errcode of -4043 (this lock does not support this operation), please try toggling "Remote Unlock" on the lock settings page in the TTLock app and try again.

There is no API to enable this setting remotely; it is only supported via the SDK/App.

4.Error code：{"errcode":-3037,"errmsg":"The gateway is busy. Please try again later."}

• It indicates that the gateway is processing other instructions. Try again later.

• The gateway is actually offline, but the offline status has not yet been updated to the server. Please check your network.

5.Error code：error code 1 (failed or means "no")

This is a general error code indicating an unknown error. Possible causes include:

• It could be due to an unstable signal between the lock and the gateway (Bluetooth connection, ensure the distance is not too far) or an unstable network between the gateway and the server. Try using a different lock or gateway.

• "When performing remote operations through the gateway, the gateway needs to establish a Bluetooth connection with the lock. This process usually takes a few seconds. The weaker the Bluetooth signal strength between the gateway and the lock, the longer the time will be, and there is even a possibility of failure. Interruption of the Bluetooth connection during communication (such as touching the panel) will also increase the time or even cause the operation to fail."

• Door lock malfunction or gateway malfunction

• Other unknown errors

6.How can I obtain unlocking and locking records without using a gateway? Can the records be automatically transmitted back through the API?

No (except for WiFi locks). If the lock itself doesn't have internet connectivity, there's no upload channel without a gateway, and records can't be returned to the server automatically.

Without a gateway, unlock records can only be retrieved actively via Bluetooth or by calling the open platform interface.

7.The difference between WiFi lock and gateway

• WIFILock(i.e. smart lock with built-in WiFi module)，Gateway is a middleware used to connect the lock and the cloud server.

• WiFiLock uses gateway's APIs.

8.Will I be notified if the gateway goes offline?

Yes, sometimes the poor network environment causes the gateway to go online and offline frequently. The App will only push notifications when the gateway is offline for more than 30 minutes.

9.How often does the gateway update the signal value of nearby locks to the backend?

Normally it is 10 minutes, but if the signal value differs by no more than 5, the value will not be updated, only the update time.

10.The WiFi lock has disabled power saving mode via the SDK, but when calling the API, but still get error message: "Wifi is in power saving mode, please turn it off and try again."

Calling the SDK to modify only makes changes to the lock itself. The cloud settings are not synchronized yet. Call the following API to synchronize the configuration:Modify lock settings

11.How to check the lock's online status:

If the lock is a WiFi lock, call the API to get lock details. The returned parameters include the isOnline parameter; isOnline = 1 indicates the lock is online.

If the lock is a gateway lock (i.e., a Bluetooth lock connected to a gateway), call the API to get lock details. The returned parameters include the hasGateway parameter; hasGateway = 1 indicates the lock is currently connected to a gateway and is online (excluding gateway network issues). If the gateway goes offline, it normally takes 10 minutes to update the gateway status. Therefore, if the gateway goes offline, hasGateway = 0 will only be available after 10 minutes.

6.Issue Cards

1.Card encoder connection problem

Please refer to this link：Issues of card encoder

2.Error code 106

(1) The card is blank and cannot be used for card reading, writing, clearing, reporting loss, and other card data operations.

Method: First write the blank card to the hotel card of the corresponding hotel.

(2) The card has been initialized as a card for another hotel and cannot be written to the hotel card of the current hotel.

Method: Restore the card to a blank card under the original hotel and then perform related operations under the current hotel.

(3) The card has been initialized as a hotel card and cannot be used to issue a project card.

Method: Restore the card to a blank card under the original hotel and then perform related operations under the current hotel.

(4) The sector used by the card does not correspond to the current sector of the card encoder and cannot be parsed.

Method: Set the card encoder to the sector currently used by the card and then perform related operations.

3.The card was issued successfully, but the door could not be opened.

4.How to report a card lost

5.Which sectors are the default ones for the TTHotel Card? all of them will be used?

Currently, the default sectors for the Tongtong Hotel Card are 12, 13, 14, 15, and 16. TTHotel uses all of the sectors from 12 to 16, while it does not use any of the sectors from 1 to 11.

6.A card supports writing multiple MACs?

One sector can write four MAC addresses. Our card has 16 sectors.

7.Does the lock support reading the MAC addresses of commonly used IC card types on the market and matching them for unlocking?

Most of the cards on the market are supported.

8.How to issue master cards and building cards, floor cardsand room cards?

Fill in the corresponding parameters according to the table below，" √ " means real data：

Take Master card as an example：

9.Can a single card be used to write multiple lock records and unlock multiple locks? Can't I specify a start time when issuing cards? For multiple records in card, can I only clear the card and not specify deletion?

1. Yes, just write the corresponding information of the two locks into the card separately;

2. No, You cannot specify a start time, the default starts from the current time;

3. Yes, you can only clear the card or restore a blank card.

7.CallBack URL

1.How to configure a Callback URL？what‘s it for？

After the application is reviewed and approved, the developer can set the callback URL in the application details page of the management center.

If it is a WiFi lock or a lock connected to a gateway, when a lock record is generated, the record will be automatically read and uploaded to the cloud server. The cloud will call the callback URL provided by the developer to achieve quasi-real-time notification of the unlocking record.

Note: to receive lock records notify, please make sure the lock's administrator have get access token with your application's clientId.

2.Format of callback URL

for example：https://yourdomain.com/your-path?param1=value1

request method：

POST, ContentType:application/x-www-form-urlencoded ，Please ensure that the server can receive the corresponding request type

port：80/443

3.I've set callback URLs for Open Platform apps A and B. Why are notifications from app A being sent back to the URL in app B?

If you've previously obtained tokens using both apps, callback notifications will be sent back to the one with the longer validity period.

Solution: Simply refresh the token using the app you want to use.

4.Which specific events will trigger callback notifications?

1. For most lock records, see: Record Type

2. Gateway and WiFi lock online and offline status

3. WiFi lock asynchronous request results

4. Lock on/off status (supported only by specific WiFi lock models)

5. Camera events

6. Abnormal alarm events

There will be no callback notifications for adding, deleting, modifying, or checking permissions (passwords, IC cards, etc.) or automatic door locking.

5.Why didn't I receive the callback notification?

1.First, test the callback address you set in the open platform to see if it works. if you are integrating with TThotel, call this API for testing

2.Verify that the lock's administrator account has obtained an access token using the current app's clientId. This ensures that the current app can receive push notifications.

3.If the lock's administrator account obtained tokens using two different apps, callback notifications will be sent to the one with the longer validity period. Simply refresh the token in the app you want to receive callback notifications from.

4.Verify that the lock is online（check your network）.

5.Check if the server certificate has expired.

6.Why are duplicate events being called back?

For callback notifications from the open platform, our server does not filter the information sent to the client. Within the lock, unlock records that haven't been read are marked as 0. When the gateway retrieves unlock records to the server, the server does two things: 1. Sends a notification to the client's server based on the callback address; 2. Returns the read result to the lock, marking successfully read records as 1.

If a problem occurs in step 2, when the gateway retrieves unlock records again, it may cause multiple retrievals of previously retrieved unlock records.

Recommendations:

1. Ensure the gateway network is functioning correctly.

2. Clients can filter on their own servers based on the lockDate and recordType values in the callback records.

3. Upload lock data in the App's lock settings and observe the results.