目录

发消息

      无法接收消息

应用

      在微信插件（原企业号）中找不到应用

      访问链接提示“将要访问 URL”

      应用链接无法打开、打开空白

      打开页面提示“防欺诈盗号，请勿支付或输入账号密码”

      企业微信打开页面提示“请在微信客户端打开链接”

      页面展示出现广告

      设置可信域名时，提示“校验域名所有权不通过”

接口

      企业微信的UA

      调用接口报错，提示缺少参数

jssdk

      拉起电子发票列表

客户端调试

      企业微信Windows版本调试

      企业微信Mac版本调试

智慧硬件常见问题

      1. 硬件设备上显示已连接，企业微信app侧显示未连接？

      2. 设备已注册网络，但发起激活设备时报错600014（设备未注册网络）？

      3. 扫码绑定二维码提示签名校验错误？

      4. 激活设备一直报错600004？

      5. 成员已打卡但管理端查询无记录？

      6. 成员自助录入，手机端操作录入人脸，考勤机显示录入指纹界面？

      7. 不在考勤机范围的人员也可以打卡并显人员的姓名，显示的人员不在考勤机可用范围？

      8. 正常连接的情况下，企业微信app侧设备连接状态在已连接和未连接不断切换？

      9. 设备触发全量拉取通讯录注意事项

      10. 其他注意事项

      11. 网络请求超时处理建议

      12. 请求失败重试

      13. 门禁设备是否需要同时适配普通企业和家校企业？

      14. 门禁设备实现了远程开门上报逻辑，在企业微信上操作后远程开门成功后，为什么没有产生门禁通行记录？

      15. 硬件数据上报接口纷繁众多，上报考勤打卡，上报门禁通行，如何区分接口何时进行调用？我是否多调用了接口或者少调用了接口？

      16. 云端对接设备，我在服务商管理后台更改了设备型号参数，为什么没生效？

发消息

无法接收消息

需要确认几点：
1.发消息指定范围，是否包括当前成员。
2.当前成员是否在应用的可见范围之内。
3.如果是微信插件（原企业号）没收到消息，请按以下两种路径进行确认：
1）进入所属的企业，点击右上角的 + ->设置->接收应用消息，检查是否有打开。
2）进入所属的企业，点击右上角的 + ->停用的应用，检查该应用是否在停用列表里，是的话可以重新启用。

应用

在微信插件（原企业号）中找不到应用

需要确认几点：
1.当前成员是否在应用的可见范围之内。
2.从微信的通讯录进入所属的企业，确认是否有该应用。
3.进入所属的企业，点击右上角的 + ->停用的应用，检查该应用是否在停用列表里，是的话可以重新启用。

访问链接提示“将要访问 URL”

被封的原因是由于此域名存放了违规的一些内容。请自行清理违规的内容，之后在拦截提示的页面上“申请恢复访问”即可。

如果需要收到页面被拦提醒，可以这样处理：
打开页面 https://urlsec.qq.com/wiki/#!md/BlackUrlPushHelp.md，并登记。一但有链接被微信拦截，就会立即收到通知。这样可以实时处理违规内容，避免整个域名被封。

对于服务商：

• 最好使用企业微信的mpnews来发布对外的信息。这样如果被拦，也只是拦某条消息，或者发内容的企业。
• 如果非要用自己的域名，不要用泛域名，并且最好固定一个路径来发布这种信息。这样被拦时，只拦这个路径，不会影响整个业务。注意，不要随便换路径，否则整个域名会被封掉。
• 也可以用一个单独的域名来发布这种信息。这个方案和第2种是一样的
• 自己搭建专业的审核团队，过滤掉所有的违规信息。信息想放哪都可以

应用链接无法打开、打开空白

尝试通过以下方式排查：

• 访问 https://ping.huatuo.qq.com，确认是否网络因素导致，正常网络延时不超过100ms
• 如果是https链接，确认是否证书已到期。证书过期的话，在移动端打开会白屏或报错提示证书过期或者错误），开发者可以自行用免费在线SSL证书检测平台检测，例如：https://www.ssllabs.com/ssltest/analyze.html 或 https://csr.chinassl.net/ssl-checker.html
• 使用 微信web开发者工具 调试页面。
  1) 登录web管理端，在微信插件（原企业号）中，打开 "开发者工具" 选项
  2) 下载 微信web开发者工具
  3) 登录web开发者工具，访问出问题的链接。在调试 - Network中观察数据返回
  页面返回数据正常。此时可定位为前端加载出错。
  页面未返回正确数据。此时需要在服务端日志，查看调用失败的原因。

打开页面提示“防欺诈盗号，请勿支付或输入账号密码”

满足以下几个条件，在微信打开页面可以去除该安全风险提示：

• 企业已经认证通过。
• 访问页面的域名需经过ICP备案。ICP备案可通过 工业和信息化部ICP/IP地址/域名信息备案管理系统 查询。
• 在管理端将页面域名设置为应用的可信域名。

顶级域名备案通过后，二级域名及其它域名也相应有备案记录。
域名通过ICP备案之后，在微信上需要24小时后才能生效

企业微信打开页面提示“请在微信客户端打开链接”

企业微信不支持打开需要带微信身份的链接。包括几种情况：

• 访问链接为oauth2链接，appid填写为公众号appid。这种情况，建议开发者更换链接，或者将原公众号服务迁移到企业微信服务。
• 公众平台发布的文章，点击“阅读原文”。这种只能在微信客户端才能访问。

页面展示出现广告

由于http协议不具备加密能力，访问链接容易被劫持。出现这种情况，建议向当前网络运营商反馈。
或者升级到https协议，从而避免该问题。

设置可信域名时，提示“校验域名所有权不通过”

请确保已经将系统生成的校验文件放在域名的根目录下并可以访问，可以在浏览器打开链接测试检查是否可以访问。
以wx.qq.com域名为例，假设系统生成的校验文件是WW_verify_7rG3kjVbXHngiald.txt，则下载该文件并放到wx.qq.com的根目录下，然后在浏览器打开以下链接检查是否能正常访问：https://wx.qq.com/WW_verify_7rG3kjVbXHngiald.txt 或 http://wx.qq.com/WW_verify_7rG3kjVbXHngiald.txt 。
若浏览器可以正常访问，但设置时仍然校验不通过，则有可能是dns未生效。注意，如果域名的dns是刚设置的，则一般不能马上生效，可以24小时后再登录管理端进行域名所有权的校验。

接口

企业微信的UA

以企业微信的UA既包含微信的user agent，也包含企业微信的user agent。这样做的原因，是为了兼容已有的系统。

其中wxwork是企业微信关键字，2.1.0为用户安装的微信版本号。MicroMessenger是微信的关键字。

调用接口报错，提示缺少参数

每个接口在文档说明中，会包含以下三部分：请求方式，请求地址及请求包体。
调用接口报缺少参数，常见的几个原因是：

• 请求方式错误。比如接口要求POST方式，但调用设置了GET请求
• 请求包体错误。比如请求包体，必须传json结构体，但调用以URL参数，或者form-data方式传递

jssdk

拉起电子发票列表

调用拉起电子发票列表显示暂无可用发票，常见原因如下：

• 微信卡包里面无可用发票
• 调用chooseInvoice接口的签名不正确，请开发者检查产生签名的参数是否正确。
  确认获取电子发票ticket是否是使用获取电子发票ticket 接口获取。
  确认卡券签名是否正确。可以使用卡券签名校验工具（选择拉取卡券列表jsapi，card_id跟location_id参数不填）进行卡券签名校验。

客户端调试

企业微信Windows版本调试

1. 把 devtools_resources.pak 放到企业微信的安装目录下（复制的文件名，要保证为 devtools_resources.pak），注意安装目录带有版本号（4.0.1304.400是浏览器内核的版本号）；

2. 关闭企业微信，重新启动；
3. 按快捷键 ctrl + alt + shift + D，进入调试模式；
4. 在需要调试的页面上点击右键，点“开发者工具”，进入调试模式。

企业微信Mac版本调试

1. 按下command+shift+control+D进入调试模式
   
2. 调试->浏览器、webView相关->开启webView元素审查
   
3. 内置浏览器右键

智慧硬件常见问题

1. 硬件设备上显示已连接，企业微信app侧显示未连接？

答：出现这个问题存在以下几种原因：
1) 所在网络环境受到限制，并没有真正的连接上企业微信；
2) 在服务商后台勾选的使用同一初始secretno，但设备第一次联网未调用getsecretno接口，直接发起注册网络；
3) 设备连接wifi频率与本身不支持。

2. 设备已注册网络，但发起激活设备时报错600014（设备未注册网络）？

答：需要检查下发起的链接是否是在原注册网络上链接建立的，如果是新建立的激活设备链接则会报错600014；

3. 扫码绑定二维码提示签名校验错误？

答：以下两种场景会导致签名校验错误：
1) 设备使用的动态二维码，设备处于长期断网状态，导致设备计算的签名与企业微信后台计算的签名不一致，提示签名校验错误，设备断网30分钟内扫描绑定是支持的；
2) 设备使用的同一初始secretno，在换取secretno的时候或者注册网络时候，设备签名排序不正确也会导设备签名计算错误。

4. 激活设备一直报错600004？

答：需要绑定企业获取到secret，才能激活设备成功。

5. 成员已打卡但管理端查询无记录？

答：以下两种场景会出现该问题：
1) 成员修改了userid，云端推送成员变更记录给设备，但设备并未同步云端最新数据，未删除旧userid更新新的userid，导致成员打卡上报时企业微信未识别到将该打卡数据丢弃，所以未上报。这里设备同步云端最新通讯录设备在线时，可以根据推送的成员变更，增量获取用户数据接口同步数据，当设备不在线时，可以根据获取历史推送记录接口（目前只有userid）。
2) 成员打卡时设备处于断网状态，一直未连接上，导致打卡记录一直未能上传。

6. 成员自助录入，手机端操作录入人脸，考勤机显示录入指纹界面？

答：出现这种情况是用户先选择录入指纹，然后退出选择开始录入人脸，云端已将该动作下发，但设备响应未及时，依旧卡在录入指纹界面。

7. 不在考勤机范围的人员也可以打卡并显人员的姓名，显示的人员不在考勤机可用范围？

答：以下两种原因会导致该问题：
1) 打卡热源指纹不清晰，指纹识别不好造成误判。
2) 下发录入信息时设备正在同步，未来得及通知同步到主业务进程。

8. 正常连接的情况下，企业微信app侧设备连接状态在已连接和未连接不断切换？

答：可能是设备发起一条连接订阅企业信息后，又发起了另一条链接订阅，两条链接相互登入，导致设备在已连接未连接跳转。

9. 设备触发全量拉取通讯录注意事项

1)不要先删除所有本地数据再进行通讯录拉取，全量拉取的过程失败会影响用户正常使用
2)设备空间不足时可以调用“检查userid合法性”接口判断可以清理哪些数据

10. 其他注意事项

1) 发送请求包体时，需按照文档中的json字符串格式，包体中的参数名必须与文档保持一致，不能加减转义符、单引号、双引号
2) 上传人脸数据时，当fa_list存在时，fa默认忽略
3) 上传人脸数据必须是人脸特征值，并且保证不可逆推出人脸原图。

11. 网络请求超时处理建议

目前建议除了下载接口，大量拉取数据的接口外，单个接口超时定义5~10s。超时没有响应可以重试请求。重试策略应为随机1~3s错峰重试（避免固定时间重试导致重试流量高峰）。
部分接口，如register subscribe_corp等，可能是调用成功，但是回包到设备端超时，此时重试会有特定报错引导，具体错误码和操作建议如下：
register接口返回600012（connection has registered），本链接已经register成功过，可以继续进行active或者subscribe_corp等操作。
register接口返回600053（connection has actived），本链接已经active成功过，可以继续进行subscribe_corp
register接口返回600054（connection has subscribed），本链接已经subscribe成功过，可以进行业务接口调用。
register接口返回600002（device has registered），本次请求的sn已经在另外一个ip建立长连接，不可新建连接，考虑ip变换或者sn密钥泄露可能。若旧链接还存在可以使用旧链接，若已丢失可以等待1~2分钟心跳超时服务端自然释放链接后重连。
subscribe接口返回600045（device already subscribe），同一sn已经被另一个ip建立长连接，或同一个ip在一分钟内subscribe超过5次，考虑ip变换、sn密钥泄露、程序死循环等。
active subscribe接口返回600014（device not registered），本条长连接没有调用register成功过，需要先调用register。

12. 请求失败重试

对于硬件接口，若请求发生错误（系统错误或逻辑错误）时，返回结果新增了suggestion和interval字段，给出处理本次请求失败的建议。

返回结果：

	{
		"headers": {
				"req_id" : "xxxx"
		},
		"errcode": 600004,
		"errmsg": "no device auth, hint:...",
		"suggestion":"retry",
		"interval":5
	}

参数说明：

13. 门禁设备是否需要同时适配普通企业和家校企业？

答: 是，门禁设备需要统一支持普通企业和家校企业，因此服务商在进行门禁设备固件开发时，需要注意门禁设备是否同时做好了企业成员和家校学生的适配。对于硬件终端识别的通信录列表中，人员类型分为三类：一、企业成员（user_type = 0）；二、访客成员（user_type = 1）；三、家校学生（user_type = 2）。硬件终端通过获取通讯录接口得到用户id（直连设备userid / 云对接设备userinfo.useritems.open_userid）和user_type， 终端/服务商云在调用企业微信云端接口时，如果不填写user_type字段（云端默认不填处理为0）或者错误填写user_type字段，使用学生userid/open_userid进行调用时则会失败，正确的调用方式是终端/服务商云在调用云端接口时，正确填入user_type字段。

14. 门禁设备实现了远程开门上报逻辑，在企业微信上操作后远程开门成功后，为什么没有产生门禁通行记录？

答：在硬件直连设备和云对接设备的远程开门实现流程中，上报远程开门结果接口（直连设备接口｜云对接设备接口）仅仅用于上报开门结果，不会产生门禁通行记录。远程开门成功后，服务商需要主动调用上报门禁通行记录接口（直连设备接口｜云对接设备接口）后才会产生门禁通行记录。

15. 硬件数据上报接口纷繁众多，上报考勤打卡，上报门禁通行，如何区分接口何时进行调用？我是否多调用了接口或者少调用了接口？

答：
直连设备的实现逻辑中，上报考勤和门禁通行是一个共用的接口：上报考勤打卡/门禁通行记录，此接口通过请求字段pass_type 来决定是否产生门禁通行记录，若终端设备仅有考勤能力没有门禁能力，则只需要进行考勤打卡记录上报，此时pass_type不填写或者填写为0即可。若考勤设备拥有门禁能力，pass_type根据接口文档填写说明进行正确填写即可同时产生考勤打卡和门禁通行记录。
云对接设备的实现逻辑中，上报考勤打卡记录和上报门禁通行记录根据能力进行了拆分，是两个独立的接口，因此服务商需要根据设备能力按需调用，如：设备仅有打卡考勤能力则只需要调用上报考勤打卡记录接口一次，因为没有门禁能力因此不需要调用上报门禁通行记录接口；设备同时拥有考勤和门禁能力，则需要分别调用上报考勤打卡记录接口和上报门禁通行记录接口一次。

16. 云端对接设备，我在服务商管理后台更改了设备型号参数，为什么没生效？

答：云端对接设备在同一个型号中存在两种类型：测试设备和正式设备
测试设备：添加入口位于：服务商管理后台->硬件管理->云端对接设备->选择一个具体型号进入->登记测试设备 SN。型号参数的修改对测试设备立即生效。
正式设备：添加入口位于：服务商管理后台->硬件管理->设备发布->选择一个具体型号进入->登记正式设备 SN。型号参数的修改不会对正式设备立即生效。需要在设备发布页对修改后的型号进行发布，才能对正式设备生效。