API
企业内部开发

常见问题 - FAQ

[TOC]

发消息

无法接收消息

需要确认几点：
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备案之后，在微信上需要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。这样做的原因，是为了兼容已有的系统。

手机系统 示例
iPhone Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_2 like Mac OS X) AppleWebKit/603.2.4 (KHTML, like Gecko) Mobile/14F89 wxwork/2.2.0 MicroMessenger/6.3.2
Android Mozilla/5.0 (Linux; Android 7.1.2; g3ds Build/NJH47F; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/53.0.2785.49 Mobile MQQBrowser/6.2 TBS/043508 Safari/537.36 wxwork/2.2.0 MicroMessenger/6.3.22 NetType/WIFI Language/zh
Windows Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.110 Safari/537.36 wxwork/2.1.3 (MicroMessenger/6.2) WindowsWechat QBCore/3.43.644.400 QQBrowser/9.0.2524.400
Mac Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/603.3.8 (KHTML, like Gecko) wxwork/2.2.0 (MicroMessenger/6.2) WeChat/2.0.4

其中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是浏览器内核的版本号）；

devtools_resources.pak存储路径

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

企业微信Mac版本调试

  1. 按下command+shift+control+D进入调试模式
    Mac打开调试模式
  2. 帮助->开发调试选项->开启webView元素审查
    Mac开启元素审查
  3. 内置浏览器右键
    Mac检查页面元素

智慧硬件常见问题

  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
}

    参数说明：

参数名 描述
req_id 透传请求的req_id
errcode 错误码
errmsg 错误码描述
suggestion 请求出现错误后的建议，值：retry或reconnect，retry表示重试，reconnect表示设备断开后重连
interval 距离本次请求后可进行 重试/重连 操作的时间间隔，单位：秒。当值为-1时，代表不可重试/重连
上一篇
企业规模与行业信息
下一篇
与企业号接口差异
© 1998 - 2021 Tencent Inc. All Rights Reserved