第三方应用接口说明

来自企业号开发者接口文档
跳转至: 导航搜索

第三方应用接口说明


接口概述

应用提供商拥有自己的API集合,主要用于完成授权流程以及实现授权后的相关功能。 套件API(即接口)如下:

功能 API名称
获取应用套件令牌 get_suite_token
获取预授权码 get_pre_auth_code
获取企业号的永久授权码 get_permanent_code
获取企业号access_token get_corp_token
获取企业授权信息 get_auth_info

应用套件在获得企业号授权后,应用提供商可以获取企业号access_token,调用企业号相关的API进行发消息、管理通讯录和应用等操作。

特别注意,所有API(包括第三方API及通讯录、发消息等所有API)调用需要验证来源IP。只有在应用套件申请信息中填写的合法IP列表内才能合法调用,其他一律拒绝。


获取应用套件令牌

该API用于获取应用套件令牌(suite_access_token)。

注1:由于应用提供商可能托管了大量的企业号,其安全问题造成的影响会更加严重,故API中除了合法来源IP校验之外,还额外增加了1项安全策略:

获取suite_access_token时,还额外需要suite_ticket参数(请永远使用最新接收到的suite_ticket)。suite_ticket由企业号后台定时推送给应用套件,并每十分钟更新。

注2:通过本接口获取的accesstoken不会自动续期,每次获取都会自动更新。


接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_suite_token

POST数据示例

{
	"suite_id":"id_value" ,
	"suite_secret": "secret_value", 
	"suite_ticket": "ticket_value" 
}

请求参数说明

参数 说明
suite_id 应用套件id
suite_secret 应用套件secret
suite_ticket 微信后台推送的ticket

返回结果示例

{
	"suite_access_token":"61W3mEpU66027wgNZ_MhGHNQDHnFATkDa9-2llqrMBjUwxRSNPbVsMmyD-yq8wZETSoE5NQgecigDrSHkPtIYA",
	"expires_in":7200
}

结果参数说明

参数 说明
suite_access_token 应用套件access_token. 长度为64至512个字节
expires_in 有效期


获取预授权码

该API用于获取预授权码。预授权码用于企业号授权时的应用提供商安全验证。

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_pre_auth_code?suite_access_token=SUITE_ACCESS_TOKEN

POST数据示例

{
	"suite_id":"id_value"
}

请求参数说明

参数 说明
suite_id 应用套件id

返回结果示例

{
	"errcode":0 ,
	"errmsg":"ok" ,
	"pre_auth_code":"Cx_Dk6qiBE0Dmx4EmlT3oRfArPvwSQ-oa3NL_fwHM7VI08r52wazoZX2Rhpz1dEw",
	"expires_in":1200
}

结果参数说明

参数 说明
pre_auth_code 预授权码。长度为64至512个字节
expires_in 有效期


设置授权配置

如果需要对某次授权进行配置,则调用本接口,目前仅可以设置哪些应用可以授权,不调用则默认允许所有应用进行授权。

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/set_session_info?suite_access_token=SUITE_ACCESS_TOKEN

POST数据示例

{
	"pre_auth_code":"xxxxx",
	"session_info":
	{
	 	"appid":[1,2,3],
               "auth_type":1
	}
}

请求参数说明

参数 必须 说明
suite_access_token 应用套件access_token
pre_auth_code 预授权码
session_info 本次授权过程中需要用到的会话信息
appid 允许进行授权的应用id,如1、2、3, 不填或者填空数组都表示允许授权套件内所有应用
auth_type 授权类型:0 正式授权, 1 测试授权, 默认值为0

返回结果示例

{
	"errcode": 0,
	"errmsg": "ok"
}

结果参数说明

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容


获取企业号的永久授权码

该API用于使用临时授权码换取授权方的永久授权码,并换取授权信息、企业access_token。

注:临时授权码使用一次后即失效

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_permanent_code?suite_access_token=SUITE_ACCESS_TOKEN

POST数据示例

{
	"suite_id":"id_value" ,
	"auth_code": "auth_code_value"
}

请求参数说明

参数 说明
suite_id 应用套件id
auth_code 临时授权码,会在授权成功时附加在redirect_uri中跳转回应用提供商网站。长度为64至512个字节

返回结果示例

{
	"access_token": "xxxxxx", 
	"expires_in": 7200, 
	"permanent_code": "xxxx", 
	"auth_corp_info": 
	{
		"corpid": "xxxx",
		"corp_name": "name",
		"corp_type": "verified",
		"corp_round_logo_url": "xxxxxx",
		"corp_square_logo_url": "yyyyy",
		"corp_user_max": 50,
		"corp_agent_max": 30,
               "corp_full_name":"full_name",
               "verified_end_time":1431775834,
               "subject_type": 1,
               "corp_wxqrcode": "zzzzz"
	},
	 "auth_info": {
               "is_new_auth":true,
                "agent" : [
                {
                     "agentid":1,
                     "name":"NAME",
                     "round_logo_url":"xxxxxx",
                     "square_logo_url":"yyyyyy",
                     "appid":1,
                     "privilege":{
                          "level":1,
                          "allow_party":[1,2,3],
                          "allow_user":["zhansan","lisi"],
                          "allow_tag":[1,2,3],
                          "extra_party":[4,5,6],
                          "extra_user":["wangwu"],
                          "extra_tag":[4,5,6]
                     }
                },
                {
                     "agentid":2,
                     "name":"NAME2",
                     "round_logo_url":"xxxxxx",
                     "square_logo_url":"yyyyyy",
                     "appid":5
                }
                ]
        },
       "auth_user_info":
       {
               "email":"xxxx@aaa.com",
               "mobile":"1234567890",
               "userid":"aa"
       }
}

结果参数说明

参数 说明
access_token 授权方(企业)access_token
expires_in 授权方(企业)access_token超时时间
permanent_code 企业号永久授权码。长度为64至512个字节
corp_info 授权方企业信息
corpid 授权方企业号id
corp_name 授权方企业号名称
corp_type 授权方企业号类型,认证号:verified, 注册号:unverified,体验号:test
corp_round_logo_url 授权方企业号圆形头像
corp_square_logo_url 授权方企业号方形头像
corp_user_max 授权方企业号用户规模
corp_full_name 所绑定的企业号主体名称
subject_type 企业类型,1. 企业; 2. 政府以及事业单位; 3. 其他组织, 4.团队号
verified_end_time 认证到期时间
corp_wxqrcode 授权方企业号二维码
auth_info 授权信息
is_new_auth 是否采用了新的授权,没有该字段或者该字段为false表示是旧授权,true表示是新授权。目前所有授权均为true。
agent 授权的应用信息
agentid 授权方应用id
agent:name 授权方应用名字
square_logo_url 授权方应用方形头像
round_logo_url 授权方应用圆形头像
appid 服务商套件中的对应应用id
privilege 应用对应的权限
allow_party 应用可见范围(部门)
allow_tag 应用可见范围(标签)
allow_user 应用可见范围(成员)
extra_party 额外通讯录(部门)
extra_user 额外通讯录(成员)
extra_tag 额外通讯录(标签)
level 权限等级。1:通讯录基本信息只读,2:通讯录全部信息只读,3:通讯录全部信息读写,4:单个基本信息只读,5:通讯录全部信息只写
auth_user_info 授权管理员的信息
auth_user_info:email 授权管理员的邮箱,可能为空(管理员通讯录中邮箱被清空)
auth_user_info:mobile 授权管理员的手机号,可能为空(管理员在通讯录中未设置手机号)
auth_user_info:userid 授权管理员的userid,可能为空(管理员不在通讯录中)


获取企业号的授权信息

该API用于通过永久授权码换取企业号的授权信息。 永久code的获取,是通过临时授权码使用get_permanent_code 接口获取到的permanent_code。

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_auth_info?suite_access_token=SUITE_ACCESS_TOKEN

POST数据示例

{
 	"suite_id":"suite_id_value",
	"auth_corpid": "auth_corpid_value",
	"permanent_code": "code_value"
}

请求参数说明

参数 说明
suite_id 应用套件id
auth_corpid 授权方corpid
permanent_code 永久授权码,通过get_permanent_code获取

返回结果示例

{
	"auth_corp_info": {
		"corpid": "xxxx",
		"corp_name": "name",
		"corp_type": "verified",
		"corp_round_logo_url": "xxxxxx",
		"corp_square_logo_url": "yyyyy",
		"corp_user_max": 50,
		"corp_agent_max": 30,
               "corp_full_name":"full_name",
               "verified_end_time":1431775834,
               "subject_type": 1,
               "corp_wxqrcode": "zzzzz"
	},
	 "auth_info": {
               "is_new_auth":true,
                "agent" : [
                {
                     "agentid":1,
                     "name":"NAME",
                     "round_logo_url":"xxxxxx",
                     "square_logo_url":"yyyyyy",
                     "appid":1,
                     "privilege":{
                          "level":1,
                          "allow_party":[1,2,3],
                          "allow_user":["zhansan","lisi"],
                          "allow_tag":[1,2,3],
                          "extra_party":[4,5,6],
                          "extra_user":["wangwu"],
                          "extra_tag":[4,5,6]
                     }
                },
                {
                     "agentid":2,
                     "name":"NAME2",
                     "round_logo_url":"xxxxxx",
                     "square_logo_url":"yyyyyy",
                     "appid":5
                }
                ]
        }
}

结果参数说明

参数 说明
auth_corp_info 授权方企业信息
corpid 授权方企业号id
corp_name 授权方企业号名称
corp_type 授权方企业号类型,认证号:verified, 注册号:unverified,体验号:test
corp_round_logo_url 授权方企业号圆形头像
corp_square_logo_url 授权方企业号方形头像
corp_user_max 授权方企业号用户规模
corp_agent_max 授权方企业号应用规模
corp_wxqrcode 授权方企业号二维码
auth_info 授权信息
is_new_auth 是否采用了新的授权,没有该字段或者该字段为false表示是旧授权,true表示是新授权。目前所有授权均为true。
agent 授权的应用信息
agentid 授权方应用id
agent:name 授权方应用名字
square_logo_url 授权方应用方形头像
round_logo_url 授权方应用圆形头像
corp_full_name 所绑定的企业号主体名称
subject_type 企业类型,1. 企业; 2. 政府以及事业单位; 3. 其他组织, 4.团队号
verified_end_time 认证到期时间
appid 服务商套件中的对应应用id
privilege 应用对应的权限
allow_party 应用可见范围(部门)
allow_tag 应用可见范围(标签)
allow_user 应用可见范围(成员)
extra_party 额外通讯录(部门)
extra_user 额外通讯录(成员)
extra_tag 额外通讯录(标签)
level 权限等级。权限等级。1:通讯录基本信息只读,2:通讯录全部信息只读,3:通讯录全部信息读写,4:单个基本信息只读,5:通讯录全部信息只写


获取企业号access_token

应用提供商在取得企业号的永久授权码并完成对企业号应用的设置之后,便可以开始通过调用企业接口(详见企业接口文档)来运营这些应用。其中,调用企业接口所需的access_token获取方法如下。

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_corp_token?suite_access_token=SUITE_ACCESS_TOKEN

POST数据示例

{
	"suite_id":"suite_id_value",
	"auth_corpid": "auth_corpid_value",
	"permanent_code": "code_value"
}

请求参数说明

参数 说明
suite_id 应用套件id
auth_corpid 授权方corpid
permanent_code 永久授权码,通过get_permanent_code获取

返回结果示例

{
	"access_token": "xxxxxx", 
	"expires_in": 7200, 
}

结果参数说明

参数 说明
access_token 授权方(企业)access_token
expires_in 授权方(企业)access_token超时时间