第三方应用接口说明
目录
第三方应用接口说明
接口概述
应用提供商拥有自己的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超时时间 |