企业微信对接

基本概念

1. corpid 每个企业都拥有唯一的corpid，获取此信息可在管理后台“我的企业”－“企业信息”下查看“企业ID”（需要有管理员权限）
2. userid 每个成员都有唯一的userid，即所谓“账号”。在管理后台->“通讯录”->点进某个成员的详情页，可以看到。
3. 部门id 每个部门都有唯一的id，在管理后台->“通讯录”->“组织架构”->点击某个部门右边的小圆点可以看到
4. tagid 每个标签都有唯一的标签id，在管理后台->“通讯录”->“标签”，选中某个标签，在右上角会有“标签详情”按钮，点击即可看到
5. external_userid 企业外部联系人的id，可能是微信用户，也可能是企业微信用户。同一个客户在企业的不同自建应用，获取到的external_userid是相同的。。
6. agentid 每个应用都有唯一的agentid。在管理后台->“应用管理”->“应用”，点进某个应用，即可看到agentid。
7. secret 每一个应用都有一个独立的访问密钥，为了保证数据的安全，secret务必不能泄漏。secret查看方法：在管理后台->“应用管理”->“应用”->“自建”，点进某个应用，即可看到。
8. access_token access_token是企业后台去企业微信的后台获取信息时的重要票据，由corpid和secret产生。所有接口在通信时都需要携带此信息用于验证接口的访问权限
   通讯录同步助手不需要配置可见范围，其权限范围默认是全公司（即根部门）。

获取access_token
请求方式： GET（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET
权限说明：
每个应用有独立的secret，获取到的access_token只能本应用使用，所以每个应用的access_token应该分开来获取
注意事项：
开发者需要缓存access_token，当access_token失效或过期时，需要重新获取。access_token的有效期通过返回的expires_in来传达，正常情况下为7200秒（2小时）。

获取部门列表
请求方式：GET（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/department/list?access_token=ACCESS_TOKEN&id=ID
ID为部门id。获取指定部门及其下的子部门（以及子部门的子部门等等，递归）。 如果不填，默认获取全量组织架构

获取成员ID列表
请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/user/list_id?access_token=ACCESS_TOKEN

userid转openid
请求方式：POST（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/user/convert_to_openid?access_token=ACCESS_TOKEN

openid转userid
请求方式：POST（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/user/convert_to_userid?access_token=ACCESS_TOKEN

发送应用消息
请求方式：POST（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN

文本消息
请求示例：

{"touser" : "UserID1|UserID2|UserID3","toparty" : "PartyID1|PartyID2","totag" : "TagID1 | TagID2","msgtype" : "text","agentid" : 1,"text" : {"content" : "你的快递已到，请携带工卡前往邮件中心领取。\n出发前可查看<a href=\"http://work.weixin.qq.com\">邮件中心视频实况</a>，聪明避开排队。"},"safe":0,"enable_id_trans": 0,"enable_duplicate_check": 0,"duplicate_check_interval": 1800
}

参数说明：

参数	是否必须	说明
touser 否 指定接收消息的成员，成员ID列表（多个接收者用‘	’分隔，最多支持1000个）。
特殊情况：指定为"@all"，则向该企业应用的全部成员发送
toparty 否 指定接收消息的部门，部门ID列表，多个接收者用‘	’分隔，最多支持100个。
当touser为"@all"时忽略本参数
totag 否 指定接收消息的标签，标签ID列表，多个接收者用‘	’分隔，最多支持100个。
当touser为"@all"时忽略本参数
msgtype 是 消息类型，此时固定为：text
agentid 是 企业应用的id，整型。企业内部开发，可在应用的设置页面查看；第三方服务商，可通过接口 获取企业授权信息 获取该参数值
content 是 消息内容，最长不超过2048个字节，超过将截断（支持id转译）
safe 否 表示是否是保密消息，0表示可对外分享，1表示不能分享且内容显示水印，默认为0
enable_id_trans 否 表示是否开启id转译，0表示否，1表示是，默认0。仅第三方应用需要用到，企业自建应用可以忽略。
enable_duplicate_check 否 表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval 否 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时

文本消息展现：

特殊说明：
其中text参数的content字段可以支持换行、以及A标签，即可打开自定义的网页（可参考以上示例代码）(注意：换行符请用转义过的\n)

文本卡片消息
请求示例：

{"touser" : "UserID1|UserID2|UserID3","toparty" : "PartyID1 | PartyID2","totag" : "TagID1 | TagID2","msgtype" : "textcard","agentid" : 1,"textcard" : {"title" : "领奖通知","description" : "<div class=\"gray\">2016年9月26日</div> <div class=\"normal\">恭喜你抽中iPhone 7一台，领奖码：xxxx</div><div class=\"highlight\">请于2016年10月10日前联系行政同事领取</div>","url" : "URL","btntxt":"更多"},"enable_id_trans": 0,"enable_duplicate_check": 0,"duplicate_check_interval": 1800
}

参数说明：

参数	是否必须	说明
touser 否 成员ID列表（消息接收者，多个接收者用‘	’分隔，最多支持1000个）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
toparty 否 部门ID列表，多个接收者用‘	’分隔，最多支持100个。当touser为@all时忽略本参数
totag 否 标签ID列表，多个接收者用‘	’分隔，最多支持100个。当touser为@all时忽略本参数
msgtype 是 消息类型，此时固定为：textcard
agentid 是 企业应用的id，整型。企业内部开发，可在应用的设置页面查看；第三方服务商，可通过接口 获取企业授权信息 获取该参数值
title 是 标题，不超过128个字节，超过会自动截断（支持id转译）
description 是 描述，不超过512个字节，超过会自动截断（支持id转译）
url 是 点击后跳转的链接。最长2048字节，请确保包含了协议头(http/https)
btntxt 否 按钮文字。 默认为“详情”， 不超过4个文字，超过自动截断。
enable_id_trans 否 表示是否开启id转译，0表示否，1表示是，默认0
enable_duplicate_check 否 表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval 否 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时

文本卡片消息展现 ：

特殊说明：
卡片消息的展现形式非常灵活，支持使用br标签或者空格来进行换行处理，也支持使用div标签来使用不同的字体颜色，目前内置了3种文字颜色：灰色(gray)、高亮(highlight)、默认黑色(normal)，将其作为div标签的class属性即可，具体用法请参考上面的示例。

markdown消息
请求示例：

{"touser" : "UserID1|UserID2|UserID3","toparty" : "PartyID1|PartyID2","totag" : "TagID1 | TagID2","msgtype": "markdown","agentid" : 1,"markdown": {"content": "您的会议室已经预定，稍后会同步到`邮箱`  \n>**事项详情**  \n>事　项：<font color=\"info\">开会</font>  \n>组织者：@miglioguan  \n>参与者：@miglioguan、@kunliu、@jamdeezhou、@kanexiong、@kisonwang  \n>  \n>会议室：<font color=\"info\">广州TIT 1楼 301</font>  \n>日　期：<font color=\"warning\">2018年5月18日</font>  \n>时　间：<font color=\"comment\">上午9:00-11:00</font>  \n>  \n>请准时参加会议。  \n>  \n>如需修改会议信息，请点击：[修改会议信息](https://work.weixin.qq.com)"},"enable_duplicate_check": 0,"duplicate_check_interval": 1800
}

示例效果：

参数说明：

参数	是否必须	说明
touser	否	成员ID列表（消息接收者，多个接收者用‘
toparty	否	部门ID列表，多个接收者用‘
totag	否	标签ID列表，多个接收者用‘
msgtype	是	消息类型，此时固定为：markdown
agentid	是	企业应用的id，整型。企业内部开发，可在应用的设置页面查看；第三方服务商，可通过接口 获取企业授权信息 获取该参数值
content	是	markdown内容，最长不超过2048个字节，必须是utf8编码
enable_duplicate_check	否	表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval	否	表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时

网页授权登录

REDIRECT_URL中的域名，需要先配置至应用的“可信域名”，否则跳转时会提示“redirect_uri参数错误”。
要求配置的可信域名，必须与访问链接的域名完全一致；若访问链接URL带了端口号，端口号也需要登记到可信域名中。

如果企业需要在打开的网页里面携带用户的身份信息，第一步需要构造如下的链接来获取code参数：

https://open.weixin.qq.com/connect/oauth2/authorize?appid=CORPID&redirect_uri=REDIRECT_URI&response_type=code&scope=snsapi_base&state=STATE&agentid=AGENTID#wechat_redirect

参数说明：

参数	是否必须	说明
appid	是	企业的CorpID
redirect_uri	是	授权后重定向的回调链接地址，请使用urlencode对链接进行处理
response_type	是	返回类型，此时固定为：code
scope	是	应用授权作用域。snsapi_base：静默授权，可获取成员的基础信息（UserId）；snsapi_privateinfo：手动授权，可获取成员的详细信息，包含头像、二维码等敏感信息。
state	否	重定向后会带上state参数，企业可以填写a-zA-Z0-9的参数值，长度不可超过128个字节
agentid	是	应用agentid，建议填上该参数（对于第三方应用和代开发自建应用，在填写该参数的情况下或者在工作台、聊天工具栏、应用会话内发起oauth2请求的场景中，会触发接口许可的自动激活）。snsapi_privateinfo时必填否则报错；
#wechat_redirect	是	终端使用此参数判断是否需要带上身份信息

员工点击后，页面将跳转至 redirect_uri?code=CODE&state=STATE，企业可根据code参数获得员工的userid。code长度最大为512字节。

获取访问用户身份

该接口用于根据code获取成员信息，适用于自建应用与代开发应用

请求方式：GET（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/auth/getuserinfo?access_token=ACCESS_TOKEN&code=CODE

参数说明：

参数	必须	说明
access_token	是	调用接口凭证
code	是	通过成员授权获取到的code，最大为512字节。每次成员授权带上的code将不一样，code只能使用一次，5分钟未被使用自动过期。

权限说明：
跳转的域名须完全匹配access_token对应应用的可信域名，否则会返回50001错误。

返回结果：
a) 当用户为企业成员时（无论是否在应用可见范围之内）返回示例如下：

{"errcode": 0,"errmsg": "ok","userid":"USERID","user_ticket": "USER_TICKET"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
userid	成员UserID。若需要获得用户详情信息，可调用通讯录接口：读取成员。如果是互联企业/企业互联/上下游，则返回的UserId格式如：CorpId/userid
user_ticket	成员票据，最大为512字节，有效期为1800s。scope为snsapi_privateinfo，且用户在应用可见范围之内时返回此参数。后续利用该参数可以获取用户信息或敏感信息，参见"获取访问用户敏感信息"。暂时不支持上下游或/企业互联场景

b) 非企业成员时，返回示例如下：

{"errcode": 0,"errmsg": "ok","openid":"OPENID","external_userid":"EXTERNAL_USERID"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
openid	非企业成员的标识，对当前企业唯一。不超过64字节
external_userid	外部联系人id，当且仅当用户是企业的客户，且跟进人在应用的可见范围内时返回。如果是第三方应用调用，针对同一个客户，同一个服务商不同应用获取到的id相同

获取访问用户敏感信息

请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/auth/getuserdetail?access_token=ACCESS_TOKEN

参数说明：

参数	必须	说明
access_token	是	调用接口凭证
user_ticket	是	成员票据

权限说明：
成员必须在应用的可见范围内。

返回结果：

{"errcode": 0,"errmsg": "ok","userid":"lisi","gender":"1","avatar":"http://shp.qpic.cn/bizmp/xxxxxxxxxxx/0","qr_code":"https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=vcfc13b01dfs78e981c","mobile": "13800000000","email": "zhangsan@gzdev.com","biz_mail":"zhangsan@qyycs2.wecom.work","address": "广州市海珠区新港中路"
}

参数说明：

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
userid	成员UserID
gender	性别。0表示未定义，1表示男性，2表示女性。仅在用户同意snsapi_privateinfo授权时返回真实值，否则返回0.
avatar	头像url。仅在用户同意snsapi_privateinfo授权时返回真实头像，否则返回默认头像
qr_code	员工个人二维码（扫描可添加为外部联系人），仅在用户同意snsapi_privateinfo授权时返回
mobile	手机，仅在用户同意snsapi_privateinfo授权时返回，第三方应用不可获取
email	邮箱，仅在用户同意snsapi_privateinfo授权时返回，第三方应用不可获取
biz_mail	企业邮箱，仅在用户同意snsapi_privateinfo授权时返回，第三方应用不可获取
address	仅在用户同意snsapi_privateinfo授权时返回，第三方应用不可获取

注：对于自建应用与代开发应用，敏感字段需要管理员在应用详情里选择，且成员oauth2授权时确认后才返回。敏感字段包括：性别、头像、员工个人二维码、手机、邮箱、企业邮箱、地址。