开发前必读

最后更新：2023/10/19

目录

-   [开发文档阅读说明](https://developer.work.weixin.qq.com/document/path/90664/#%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3%E9%98%85%E8%AF%BB%E8%AF%B4%E6%98%8E)
-   [接口调用流程](https://developer.work.weixin.qq.com/document/path/90664/#%E6%8E%A5%E5%8F%A3%E8%B0%83%E7%94%A8%E6%B5%81%E7%A8%8B)
-   [基本调试方法](https://developer.work.weixin.qq.com/document/path/90664/#%E5%9F%BA%E6%9C%AC%E8%B0%83%E8%AF%95%E6%96%B9%E6%B3%95)
-   [调用频率限制](https://developer.work.weixin.qq.com/document/path/90664/#%E8%B0%83%E7%94%A8%E9%A2%91%E7%8E%87%E9%99%90%E5%88%B6)
-   [可信IP](https://developer.work.weixin.qq.com/document/path/90664/#%E5%8F%AF%E4%BF%A1ip)

## [](https://developer.work.weixin.qq.com/document/path/90664/#%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3%E9%98%85%E8%AF%BB%E8%AF%B4%E6%98%8E)开发文档阅读说明

1.  服务端API开放了丰富的能力接口，开发者可以借助接口能力，实现企业服务及企业微信的集成。支持的能力，通过目录导航可以快速预览，目录树按功能块聚合归类，如通讯录管理、消息推送等。  
    
2.  文档的阅读次序，建议先阅读一遍开发指南，以及接口access\_token获取。然后就可以独立查看各个功能块文档说明。  
    
3.  所有的接口需使用HTTPS协议、JSON数据格式、**UTF8编码**。接口说明格式如下：  
    
    ```javascript
    请求方式：GET/POST（HTTPS）
    请求地址：https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET
    请求包体：
    ...
    参数说明：
    ...
    权限说明：
    ...
    返回结果：
    ...
    参数说明：
    ...
    ```
    
      
    1) **请求方式**，标明接口调用的HTTP方法，区分HttpGet/HttpPost请求。所有的请求都为https协议。  
    2) **请求地址**，参数中标注**大写的单词**，表示为需要**替换的变量**。在上面的例子中 ID 及 SECRET 为需要替换的变量，根据实际获取值更新。假如，这里我们获取到的ID=wwabcddzxdkrsdv，SECRET=vQT\_03RDVA3uE6JDASDASDAiXUvccqV8mDgLdLI，那么上述的请求在发送时为：  
    
    ```javascript
    https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=wwabcddzxdkrsdv&corpsecret=vQT_03RDVA3uE6JDASDASDAiXUvccqV8mDgLdLI
    ```
    
      
    3) **请求包体/参数说明**，标明请求参数示例及说明，参数说明包括字段含义、取值范围，开发者在设计数据结构时，应参考该定义范围。  
    4) **权限说明**，标明接口的使用范围，开发者应特别**留意调用场景**。比如，同步通讯录的接口必须要用通讯录同步助手的access\_token，发送消息指定的范围必须是应用可见范围内的节点等。  
    5) **返回结果/参数说明**，标明返回参数示例及说明。特别留意，所有接口在调用失败时返回包里都有errcode、errmsg（部分接口在调用成功时没有返回errcode和errmsg）。开发者需**根据errcode存在且不为0判断为失败，否则为成功**（errcode意义请见[全局错误码](https://developer.work.weixin.qq.com/document/path/90664/#10649)）。而errmsg仅作参考，后续可能会有变动，因此不可作为是否调用成功的判据。

## [](https://developer.work.weixin.qq.com/document/path/90664/#%E6%8E%A5%E5%8F%A3%E8%B0%83%E7%94%A8%E6%B5%81%E7%A8%8B)接口调用流程

![](https://p.qpic.cn/pic_wework/3138313977/8187638d87c642e4dfdc5be2382183d41f1bc5e446580dbc/0)

1.  获取access\_token，参考 [文档说明](https://developer.work.weixin.qq.com/document/path/90664/#15074)。
2.  缓存和刷新access\_token。  
    开发者需要缓存access\_token，用于后续接口的调用（注意：不能频繁调用gettoken接口，否则会受到频率拦截）。当access\_token失效或过期时，需要重新获取。
3.  调用具体的业务接口

## [](https://developer.work.weixin.qq.com/document/path/90664/#%E5%9F%BA%E6%9C%AC%E8%B0%83%E8%AF%95%E6%96%B9%E6%B3%95)基本调试方法

企业微信提供了开发者工具，可以借助工具排查问题原因。参考说明：工具与资源 - [开发者工具](https://developer.work.weixin.qq.com/devtool/home)

## [](https://developer.work.weixin.qq.com/document/path/90664/#%E8%B0%83%E7%94%A8%E9%A2%91%E7%8E%87%E9%99%90%E5%88%B6)调用频率限制

出于系统保护的考虑，我们对接口的调用做了频率限制。参考说明：附录 - [主动调用频率限制](https://developer.work.weixin.qq.com/document/path/90664/#10785)

## [](https://developer.work.weixin.qq.com/document/path/90664/#%E5%8F%AF%E4%BF%A1ip)可信IP

为了企业的数据安全，从2022年6月20号20点之后，新开启的通讯录同步助手与新创建的自建应用必须在管理端配置可信IP，仅配置的可信IP能调用接口。