开始开发

[TOC]

术语介绍

corpid

每个企业都拥有唯一的corpid,获取此信息可在管理后台“我的企业”-“企业信息”下查看“企业ID”(需要有管理员权限)

userid

每个成员都有唯一的userid,即所谓“帐号”。在管理后台->“通讯录”->点进某个成员的详情页,可以看到。

部门id

每个部门都有唯一的id,在管理后台->“通讯录”->“组织架构”->点击某个部门右边的小圆点可以看到

tagid

每个标签都有唯一的标签id,在管理后台->“通讯录”->“标签”,选中某个标签,在右上角会有“标签详情”按钮,点击即可看到

agentid

每个应用都有唯一的agentid。在管理后台->“应用与小程序”->“应用”,点进某个应用,即可看到agentid。

secret

secret是企业应用里面用于保障数据安全的“钥匙”,每一个应用都有一个独立的访问密钥,为了保证数据的安全,secret务必不能泄漏。
目前secret有:

  • 自建应用secret。在管理后台->“应用与小程序”->“应用”->“自建”,点进某个应用,即可看到。
  • 基础应用secret。某些基础应用(如“审批”“打卡”应用),支持通过API进行操作。在管理后台->“应用与小程序”->“应用->”“基础”,点进某个应用,点开“API”小按钮,即可看到。
  • 通讯录管理secret。在“管理工具”-“通讯录同步”里面查看(需开启“API接口同步”);
  • 客户联系管理secret。在“客户联系”栏,点开“API”小按钮,即可看到。

access_token

access_token是企业后台去企业微信的后台获取信息时的重要票据,由corpid和secret产生。所有接口在通信时都需要携带此信息用于验证接口的访问权限

开发步骤

你可以通过以下步骤,使用access_token来访问企业微信的接口。需要注意的是,所有的接口需使用Https协议、Json数据格式、UTF8编码。
注:查看接口说明中,参数中标注大写的单词,表示为需要替换的变量。

第一步:获取secret

  • 通讯录管理、外部联系人管理、审批、打卡等基础应用是企业微信默认集成的应用,可以直接开启并拿到secret。参考上文secret的介绍。
  • 如果企业需要开发自定义的应用,进入“企业应用”页面,在“自建应用”栏点击“创建应用”,完成应用的添加和配置,详细步骤请参见应用概述

第二步:开启接收消息模式

开启接收消息模式并不是必须步骤,但是如果在你的企业应用中需要用到如下功能时需提前开启接收消息模式。

  • 获取企业成员的地理位置信息
  • 动态调整企业应用的信息
  • 获取企业成员点击事件类型的应用菜单行为
  • 获取企业成员通过应用给企业后台发送的消息

关于如何开启接收消息模式,请阅读接收消息配置章节。

第三步:获取access_token

请求方式:GET(HTTPS
请求URL:https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET
注:此处标注大写的单词ID和SECRET,为需要替换的变量,根据实际获取值更新。其它接口也采用相同的标注,不再说明。

若企业安装了第三方应用,该服务商可通过“获取企业access_token”获得此调用凭证。

参数说明:

参数 必须 说明
corpid 企业ID
corpsecret 应用的凭证密钥

权限说明:

每个应用有独立的secret,所以每个应用的access_token应该分开来获取

返回结果:

{
   "errcode":0,
   "errmsg":"",
   "access_token": "accesstoken000001",
   "expires_in": 7200
}
参数 说明
access_token 获取到的凭证,最长为512字节
expires_in 凭证的有效时间(秒)

出错返回示例:

{
   "errcode":40091,
   "errmsg":"secret is invalid"
}

特别说明:

企业微信所有接口,返回包里都有errcode、errmsg。开发者需根据errcode是否为0判断是否调用成功(errcode意义请见全局错误码)。
而errmsg仅作参考,后续可能会有变动,因此不可作为是否调用成功的判据。
后面不再赘述。

第四步:缓存和刷新access_token

开发者需要缓存access_token,用于后续接口的调用(注意:不能频繁调用gettoken接口,否则会受到频率拦截)。当access_token失效或过期时,需要重新获取。

  • access_token的有效期通过返回的expires_in来传达,正常情况下为7200秒(2小时),有效期内重复获取返回相同结果,过期后获取会返回新的access_token。
  • 由于企业微信每个应用的access_token是彼此独立的,所以进行缓存时需要区分应用来进行存储。
  • access_token至少保留512字节的存储空间。
  • 企业微信可能会出于运营需要,提前使access_token失效,开发者应实现access_token失效时重新获取的逻辑。

第五步:开发应用逻辑

到这里,准备工作已经就绪,你可以继续阅读下面的接口文档了解更多关于企业微信提供的开放能力,并将这些能力与你的应用进行结合。
如果你面对这些接口一时不知如何下手,欢迎下载我们开源的示例代码进行参考 : php版python版

关于频率限制

出于系统保护的考虑,我们对接口的调用做了频率限制。请参见“主动调用频率限制

© 1998 - 2021 Tencent Inc. All Rights Reserved