常见问题

1.锁相关问题

1.每把锁可添加的用户数量，每个账号下可添加的锁的数量，可以创建的分组数量?

• 每把锁可添加的用户数量：授权管理员数量没限制，密码、卡片、指纹，具体取决于锁的型号

• 每个账号下可添加的锁的数量，可以创建的群组数量：没限制

2.如何区分通通锁是几代？如何判断锁是否支持某些功能？

现在的锁基本都是三代锁

app添加锁后支持的功能模块会显示出来，也可以通过获取锁的特征值进行查看锁是否支持某些功能，如何获取锁特征值：获取锁详情信息， 返回值的featureValue即为锁特征值，可以根据该文档查看进行具体分析：锁特征值说明以及示例代码

3.如何重置锁？

1.通通锁App蓝牙删除重置，App内找到对应锁---设置---删除

2.打开锁体---找到重置按钮---长按，听到提示音后---输入000#（需要App对应锁设置里面开启允许物理重置），重置按钮如下示例图

3.以上两步均不行，联系锁厂/供应商进行咨询

4.物理重置按钮为什么没反应？

检查是否在APP上开启了禁用物理重置键？如果禁用了物理重置键就只能通过app蓝牙删除重置，即用之前添加锁的账号删除。

5.为什么用wifi开锁反应好慢？

• Wi-Fi锁开启了省电模式（或被系统默认启用了）；

• 在锁休眠的状态下，云端无法实时下发开锁指令；

• WiFi远程开锁不走缓存异步下发指令的流程，唤醒WiFi锁（有触摸唤醒，定时唤醒），只有在唤醒在线状态才能开锁。缓存命令才被执行。

6.智能锁必须通过 App 初始化（添加）一次吗？

可以通过按键添加密码、IC卡、指纹开锁方式使用。但未初始化过的锁可以被别人初始化，有安全隐患。

7.如何把锁和网关转移给别人？

1.直接重置锁，然后让他人账户绑定

2.通通锁APP---设置---转移智能锁（/转移网关）---填写接收人账户信息

8.锁常用操作指令

9.锁的主管理员（最高管理员）和授权管理员？

主管理员（最高管理员）：添加锁的账户就是主管理员（最高管理员）

授权管理员：授予普通电子钥匙用户管理锁的权限，如发送钥匙和获取密码等权限，授权用户拥有除了删除锁、再授权、修改管理员开锁密码等极少数权限外的所有权限。

被授权用户必需先拥有一把当前锁的电子钥匙，可以通过发送钥匙接口给被授权用户发送电子钥匙，再调用授权API。

10.开锁失败原因？

可能是锁时间不准确、密码失效等，排查思路：

1.查看开锁记录，在通通锁app--找到对应锁---开所记录，没有开锁记录去锁旁边上传锁数据（对应锁--设置--上传锁数据）

2.拿到开锁记录后查看时间是否正确，以及密码是否在有效期（手机app蓝牙开锁会自动校准锁时间）

3.单次密码 只能在开始时间后6小时内使用一次，否则密码失效；永久密码 从开始时间开始永久有效，必需在开始时间24小时内使用一次，否则密码失效；限期密码 在开始和结束时间内有效，必需在开始时间24小时内使用一次，否则将失效；

11.通通锁内的设备可以直接转移到通通酒店吗？通通酒店和通通锁数据可以互通吗？

不能，只能删除（重置）重新添加。

不互通，通通锁账户不能登录通通酒店，反之亦然。

12.如何区分普通锁和WiFi锁的区别？

1.WiFi锁添加的时候会让你配置WiFi， 或者添加成功后去锁设置里面看一下有没有WiFi选项

2.通过锁特征值来判断，使用获取锁详情接口获取锁特征值、锁特征值位数含义，也可以通过该方法判断锁是否支持其他功能

13.如何同步锁内数据和云端数据?

通通锁App---对应锁---设置---上传数据

14.初始化锁的时候报错{"state":"fail","error":"LOCK_IS_IN_NO_SETTING_MODE"}  

把锁摸亮使其进入设置模式

15.如何校准锁时间？

通通锁App蓝牙开锁会自动校准锁时间，也可在app内找到对应锁---设置---锁时间---校准锁时间

16.锁在线是什么意思？

普通锁为蓝牙锁，不具有和云端交流的能力，所以不能接收云端API的指令以及和云端数据保持同步。锁在线，即锁连接有网关 或 锁是WiFi锁。

17.通通锁App如何导出门锁数据？

通通锁App本身没有导出门锁数据的功能，可以登录通通锁web端管理系统进行导出：

2.开放平台相关问题

1.开发者账户是用来干什么的？账户里面的应用是什么？申请应用数量有限制吗？

开发者账户用来申请应用，一个账户可以申请多个应用，每个应用都有自己的client_id 和 client_secret；后续调用开放平台API会使用到。

基础版可以申请的应用数量：3个

高级版v1可以申请的应用数量：1000个

高级版v2可以申请的应用数量：1500个

高级版v3可以申请的应用数量：2000个

2.开发者账户可以用来绑定我的锁吗？开发者账户和通通锁账户有什么关系？

• 开发者账户只是用来申请应用获取client Id和client Secret，不能绑定锁，绑定锁（即初始化锁）要用通通锁APP。

• 通通锁账户 + 开发者账户应用内的client_id 和 client_secret 调用获取token的API获取通通锁账户token，获取token后可以调用其他API管理通通锁账户下的锁

3.如何调用开放平台API？

大致流程如下, 具体详细步骤请参考下方“对接相关问题”章节中的"通通锁App对接"以及“通通酒店对接”

step 1 ：开放平台申请开发者账户--账户内申请应用--应用得到审核后可以看到client_id 和 client_secret。

step 2：下载通通锁app，注册通通锁app账户

step 3：根据获取token的接口获取到通通锁账户的token，从而管理该账户下的锁

注：上述方式针对通通锁，通通酒店对接可以省略step1，2，去通通酒店客户端，设置---酒店对接---配置好相应信息之后获取到对接信息---拿对应信息调用开放平台API即可

4.调用API获取token时提示username或password错误

1.检查账户信息是否为通通锁APP账户

2.检查账户信息是否填写错误

3.密码要用md5加密

5.调用API对锁进行管理的时候报错：-2018 没有权限

1.没有用添加锁的通通锁账户获取token进行操作

2.当前账户没有授权管理员权限

3.传错锁id

6.开放平台收费吗？如果超出接口调用次数会怎么样？如何升级开发者版本？

开放平台对接注册开发者账户，申请应用即可，默认为基础版，免费。基础版每月接口最多调用次数为30000次，每调用一次就计数一次，调用次数可以在应用里面看，如接口次数达到上限，则调用接口失败并邮件提醒。

邮件提醒：您的应用本月调用接口的次数已经或即将超限，将禁止继续调用接口。为避免影响到您的业务，请及时完成开发者账号的升级。

用户可以根据自己需求进行升级。

升级步骤：开发者账户---基本信息---开发者版本---付费升级（五分钟左右生效），也可以通过该步骤查看升级费用。

7.单月最大接口可调用数是指每个应用的还是所有应用累加的？

每个应用的，例如基础版单月最大调用数为：30,000，那么该账户下的每个应用的最大调用次数都为30,000

8.调用API的Lock ID、LockData是哪里来的？初始化成功后从哪里获取？

锁ID（lockId）和锁数据（lockdata）是在锁成功初始化并上传到云平台后由平台返回的， lockId是一个唯一标识符，即使多次初始化也不会改变。lockData 是关键，它包含加密后的锁信息。lockId是后续所有远程控制、密码管理、eKey 分发的基础。

初始化成功后：

lockId可以在app--锁--基本信息中查看，也可调用API：获取名下锁列表；

lockdata可以用获取单把钥匙API获取：获取单把钥匙；

9.{"errcode":10004,"errmsg":"invalid grant","description":"token无授权，token已失效或被撤销授权"}

当前为授权管理员，权限过期或被主管理员撤回导致token失效

10.{"errcode":80000,"errmsg":"date must be current time, in 5 minutes","description":"请求时间必需为当前时间前后五分钟以内"}

调用API时使用的参数date不是当前时间且在五分钟内，请使用当前时间五分钟内的时间戳。

3.对接相关问题

1.通通锁App如何对接？

步骤 1：在开放平台注册一个账号，这个就是您的开发者账号，用这个账号申请一个应用，经过我们的审核并通过后，您就可以在您申请的应用中看到client_id和client_secret；

步骤 2：使用获取token的 API 获取您的 ttlock 帐户的访问令牌，请注意：账户密码是通通锁App账户密码，不是开放平台的开发者账户密码；

步骤 3：获取到步骤2中的accessToken后，就可以使用它来调用其他API，如下图所示：

2.通通酒店如何对接？

对接通通酒店则不需要去我们开放平台申请开发者账户并申请应用，可以直接去客户端获取信息，具体流程如下：

Step 1.通通酒店--设置--对接信息--获取client_id、client_secret、账户和密码（即username and password）

Step 2.根据对接信息获取token，如下图所示：

Step 3：获取到token之后可以调用其他相关API，如获取随机密码：

注意：

• 通通酒店的对接信息类似于在开放平台创建了一个应用，开发者可以用其对接信息管理和控制锁（获取锁相关的数据，如锁列表，密码列表等），值得注意的是：通通酒店有自己的数据库，因此调用开放平台接口生成的数据无法通通酒店客户端进行查看，可在app内查看；

• 有些客户对接通通酒店希望实现远程发卡（网关发卡，把卡号写入锁中）和本地发卡（发卡器发卡，把门锁信息写入卡中），不推荐两种方式混合使用，具体原因为：通过接口远程删除发的卡时，其实质为把该卡从门锁中拉黑，此卡无法从该门锁中使用，这样就会导致同一张卡再用发卡器发卡时造成发卡成功但无法开锁。因为门锁和卡内都有对方信息且本地发卡是离线的，为保证卡能否开锁的一致性，所以在锁内拉黑该卡。

3.发卡器发卡对接?

一般对接了通通酒店之后，希望对接发卡器进行发卡，请参考下方链接：

1.酒店发卡对接方式，DLL对接源码、对接手册以及demo

2.发卡器对接流程以及demo发卡流程示例

4.Web系统如何控制智能锁？

在 Web（H5 或浏览器环境）中操作智能锁，确实只能通过官方提供的 API 来进行锁的信息获取与操作控制。

原因：Web端没有蓝牙可以和智能锁建立联系

具体流程：H5 页面 → 请求 API → 云服务器 → 网关（通过蓝牙）→ 锁

5.微信小程序如何对接？

1. 登录小程序后台

2. 点击左下角小程序头像，选择“账号设置” -> “第三方设置” -> “插件管理”

3. 点击“添加插件” -> 搜索小程序插件APPID -> 添加插件（插件仅支持企业账号添加）

6.如何对接本地化/数据存储到自己的服务器？

一些客户考虑到安全性问题，希望数据保存在自己的服务器上，且相关指令都仅仅在内网内进行，对此，我们提供三种对接方式（收费）

• 6.1 基于自己的软件与我方接口进行对接（用于已经有一套完整的系统，仅用于设备对接）

  有自己的服务器，仅仅需要对接我们的接口，我们提供SDK（Android & IOS），Jar 包（Server），DLL以及小程序插件。根据我们提供的SDK，jar包和手册，客户自己进行开发APP以及和本地服务器交互的API。

  基本流程：

  

• 6.2 直接使用我方提供的软件 （提供一套完整的系统用于管理锁设备）

  我们提供APP、Web端、Server端和相应API。

  示例：

  本地化相关接口文档：http://xiaoyaoji.cn/project/1XKJIUUwSY5/1jitKisUEUK

  本地化方案web端演示：http://onpremise.ttlock.com/

  本地化方案演示app下载：https://www.pgyer.com/uEG3

  

• 6.3 客户基于我方提供的源代码，在原有功能上进行二次开发 （用于有开发人员的情况下自行开发软件）

7.本地化的SDK跟开放平台的SDK中方法有什么区别？

方法基本都是一样的，但是用开放平台SDK生成的lockdata无法在本地化配套的服务器Jar包中使用。

4.密码相关问题

1.蓝牙删除随机密码提示数据不存在

因为随机密码的生成和校验都是根据算法来的，所以随机生成的密码需要在锁上使用一次才会记录在锁里

2.为什么密码提示无效密码？

1.锁内时间不对，导致密码失效， 校准锁时间再次尝试

2.单次密码 只能在开始时间后6小时内使用一次，否则密码失效；永久密码 从开始时间开始永久有效，必需在开始时间24小时内使用一次，否则密码失效；限期密码 在开始和结束时间内有效，必需在开始时间24小时内使用一次，否则将失效；

3.为什么app里没有该密码，确依旧能开锁？

某些操作导致云端和锁本身数据不同步，在app内---锁设置---上传锁数据，进行数据同步然后再查看app

4.发送密码有哪些注意事项？

随机密码：

随机密码由算法生成，为防止撞库，发送随机密码有一些注意事项：

• 如果密码时间范围是同一天，则只能按半小时为间隔进行舍入。例如，对于 9:55 - 11:00 和 10:55 - 12:00 这样的时间段，实际考虑的时间范围是 9:30 - 11:00 和 10:30 - 12:00。 如果时间范围不是同一天，则会按一小时为间隔进行舍入。

  如果跨年，则会按月为间隔进行舍入。

• 限时随机密码type =3 ，相同时间段内的密码只能有一个

  同一天的密码， 开始 或 结束时间需要错开半个小时才能获取到新的密码，即两个密码的时间段要错开一个小时。

  不是同一天的密码，开始 或 结束时间要错开一个小时，，即两个相同密码的时间段要错开一个小时。

自定义密码：

自定义密码只支持限期、永久类型，有效期可以精确到分钟，没有像随机密码方案那样必需在24小时内使用的限制和同时间段个数限制。

5.过期的时效密码 和 新的失效密码 时间范围一样可以吗？自定义密码的时效范围一样可以吗？

不可以，可以

6.过期的自定义密码会自动删除吗？如果锁没内存了怎么办？

不会，超出内存之后最早添加的密码会被“挤出”锁内存（从锁内存中删除）

7.添加密码时提示：相同密码已存在

可能原因：

• 随机密码由算法生成，不会存在相同的情况；

• 自定义密码生成后，如果不自己手动删除，即使过期之后依旧存在锁内；

• 其他原因导致云端和锁本身数据不一致；

解决方法：

1.根据密码值删除密码：适用于锁本身没有连接网关，服务器是不知道密码过期的，则无法通过获取密码列表获取到过期密码，无法获取到密码id进行删除，直接根据密码本身去进行删除

2.根据密码ID删除密码：可以获取到密码id

3.重置密码/或使用清空码---删除锁内所有密码

8.调用发送密码API，成功返回密码，但是开锁却失败

1.请确保锁id是正确的以及密码在有效期内

2.可以去app内---对应锁---设置---锁时间---校准锁时间，然后再次尝试

3.自定义密码：如果addType = 1， 请先使用sdk内方法发送然后再调用API同步云端； addType = 2， 请确保锁在线（即锁连接了网关 或 锁是WIFI锁）。可以进一步上传锁数据，然后去app里面查看发送密码状态。

5.网关/WiFi锁相关问题

1.什么是网关？网关如何与锁连接？锁和网关之间是多对多的吗？

1.通通锁智能门锁本身不联网，只能通过蓝牙连接与外界通迅，网关是一个可以联网的小设备，使远程管理智能锁成为可能。

2.不需要用户去手动关联。网关初始化完成即会自动搜索附近的锁，如果搜索到的锁和网关属于同一个管理员账号，就会自动关联上，所以请确保锁和网关是用同一个账号添加的。

3.是的，可以通过获取网关管理的锁列表和获取锁连接的网关列表两个接口查询锁和网关之间的关联关系和信号强度。当向锁发起远程操作时，系统会选择信号强度最好的网关下发操作指令。

2.如何在app中添加网关？

以G2网关为例：

3.通过网关调用unlock API，返回errcode为-4043(此锁不支持该操作)

• 通过网关或WiFi锁远程开锁，如果返回errcode为-4043(此锁不支持该操作)，请尝试在通通锁APP的锁设置页打开“远程开锁”的开关后再试。

• 没有API接口可以打开或关闭此功能，此操纵仅支持sdk/APP操作。

4.错误码：{"errcode":-3037,"errmsg":"The gateway is busy. Please try again later.","description":"网关正忙，请稍后再试。"}

• 表明网关正在处理别的指令，稍后在尝试即可

• 网关实际已离线，但是离线状态还未更新至服务器，请检查网络

5.错误码：error code 1 {failed or means "no"}

一般是用于表示未知错的通用错误码，推测可能原因：

• 可能是由于锁跟网关之间的信号（蓝牙连接，确保不要距离太远） 或 网关跟服务器之间的网络不稳定， 可以尝试换其他的锁或者网关进行尝试

• “通过网关执行远程操作，网关需要和锁之间建立蓝牙连接通讯，这个过程一般需要几秒钟时间，网关和锁之间的蓝牙连接信号强度越弱，耗时会越长，甚至有失败的可能性。通讯过程中蓝牙连接被打断（如触碰到面板等）也会导致耗时增加甚至操作失败”

• 门锁异常或者网关异常

• 其他未知错误

6.如不借助网关，如何获得开关门记录，记录能不能通过接口自动回传?

不能（WiFi锁除外），锁本身不具有联网功能的话，没有网关就没有上传通道，没办法将记录返回给PMS；

没有网关只有蓝牙主动获取开锁记录，或调用开放平台接口主动获取

7.WiFi锁和网关的区别？WIFI锁的API和网关的是一样的吗？

• WIFI锁（即内置 WiFi 模块的智能锁），网关（Gateway）则是个中间件，用于连接锁和云服务器的设备

• gateway的API，WiFi锁基本都能用

8.网关掉线会收到通知吗？

• 会，有时网络环境差导致网关频繁上下线，为避免反复通知，只有当网关掉线超过半小时后app才会推送通知。

9.网关多久会更新一次附近锁的信号值给后台？

• 10分钟，但如果信号值前后相差不超过5，不会更新值，只更新更新时间。

10.WiFi锁通过SDK关闭了省电/睡眠模式，但是调用API依旧提示："Wifi is in power saving mode, please turn it off and try again"

• 调用SDK修改只是在锁本身上进行了修改，云端还没有同步设置，调用下方API同步配置：修改锁设置项

11.如何获取锁在线状态

如果锁是WiFi锁，调用获取锁详细信息API，返回参数中有isOnline参数；isOnline = 1 表示锁在线

如果锁是网关锁（即连接网关的蓝牙锁），调用获取锁详细信息API，返回参数中有hasGateway参数；hasGateway = 1，表示当前锁连接了一个网关，锁是在线的 （排除网关网络问题）；网关掉线，正常情况下需要10分钟才会更新网关状态，所以如果网关掉线，10分钟后才能获取到门锁hasGateway = 0；

6.发卡问题

1.发卡器连接问题

请参考链接：发卡器连接问题

2.发卡106问题

(1) 卡片为空白卡，无法进行读卡、写卡、清卡、挂失等相关卡数据操作。

方法：先将空白卡写成对应酒店的酒店卡，对应demo中第(5)步

(2) 卡片已初始化为其它酒店的卡，无法将该卡写成当前酒店的酒店卡。

方法：将卡片在原来的酒店下恢复为空白卡，即用原来酒店的hotelInfo执行恢复空白卡操作，然后再在当前酒店下进行相关操作。

(3) 卡片已初始化为酒店卡，无法进行发工程卡的操作。

方法：将卡片在原来的酒店下恢复为空白卡，再在当前酒店下进行相关操作。

(4) 卡片使用的扇区与发卡器当前扇区不对应，无法解析。

方法：将发卡器设置成卡片当前使用的扇区，然后进行相关操作。

3.发卡成功，但无法开门

4.如何挂失卡

DLL Demo挂失后如何恢复：

重新执行挂失操作，把挂失时间往前写六年，比如上次写的挂失到期时间是2025.9.25，恢复的时候时间戳设置为2019之类（ 这是因为DLL执行挂失操作的时候会默认再延长五年）

5.通通酒店卡默认是哪几个扇区，全部使用吗？

现在通通酒店默认扇区是 12,13,14,15,16，12～16 扇区通通酒店全部使用，1～11 扇区通通酒店不会使用

6.一张卡支持写入多个MAC吗？

一个扇区可以写4个mac地址，我们卡16个扇区

7.锁支持读取市面上通用的IC卡种的MAC地址，并进行匹配开锁吗？

市面上大部分卡都是支持的

8.如何发总卡以及楼栋、楼层以及房间卡？

根据下表填写对应参数即可, " √ " 表示为真实数据：

总卡：

9.一张卡可以写多个锁信息并进行开锁吗？发卡不能指定开始时间吗？对于多条发卡记录只能清空卡不能指定删除吗？

可以，将两条锁的对应信息分别写入卡里即可；不能指定开始时间，默认从当前时间开始；是的，只能清空卡 或 恢复空白卡

7.回调地址相关问题

1.如何设置回调地址？有什么作用？

应用审核通过后，开发者可以在管理中心的应用详情页里设置实现好的回调接口地址。

是WiFi锁或锁有连接网关时，当有锁记录产生，记录会自动被读取并上传到云端，云端调用开发者提供的接口，实现开锁记录的准实时通知。

注意：需要确保锁的管理员账号用当前应用的clientId获取了访问令牌，当前应用才能接收到记录推送。

2.回调地址格式

示例：https://yourdomain.com/your-path?param1=value1

请求方式：

POST, ContentType:application/x-www-form-urlencoded ，请确保服务器能够接收对应的请求类型。

使用端口：80/443

3.在开放平台应用A和B中分别设置了回调地址，为什么A应用的通知会回调给应用B中的URL？

如果之前用两个app都获取过token的话，回调通知会回调给token有效期长的那个

解决方法：想用哪个应用收取回调通知，用哪个应用重新刷新token就可以

4.具体哪些事件才会有回调通知？

1.绝大多数锁记录，可参考：云端锁操作记录类型说明

2.网关、WiFi锁的上下线

3.WiFi锁异步请求结果

4.锁的开关状态，只有特定型号的WiFi锁支持

5.摄像头事件

6.异常报警事件

权限（密码、IC卡等）的增删改查、门锁自动闭锁不会有回调通知

5.为什么没有收到回调通知？

1.首先测试设置的回调地址，测试是否能够成功，对接通通锁的可以直接开放平台应用界面内点击测试；对接通通酒店的可以调该API进行测试：锁记录回调通知

2.检查锁的管理员账号用当前应用的clientId获取了访问令牌，这样当前应用才能接收到记录推送

3.检查门锁是否在线（即是否连接了网关或门锁是WiFi锁），网络是否稳定

4.如果有多个应用，锁的管理员账号分别用两个应用获取了token，回调通知会回调给token有效期长的那个，想用哪个应用收取回调通知，用哪个应用重新刷新token就可以

5.检查服务器证书是否过期

6.为什么会回调重复的事件？

对于开放平台的回调通知，我们服务器并没有对回调给客户的信息做过滤，在锁内，没有被读取的开锁记录在锁内会被标为0，当网关在拉取开锁记录给服务器，服务器会做两件事 1.根据回调地址发送通知到客户服务器，2.读取结果返回给锁，成功读取的会被标为1

在第2步中间如果出现问题，当网关再次拉取开锁记录，可能会导致多次拉取之前已经拉取过的开锁记录

建议：

1.确保网关网络正常

2.可以根据回调记录中的 lockDate 和 recordType在自己服务器做过滤

3.App--锁设置内上传锁数据，再观察