广告微商 开发者工具
![](http://419ai.oss-cn-beijing.aliyuncs.com/2023/07/20230726191152761.png)
授权认证
本节将为您介绍如何进行 API 的授权认证。
API目前支持基于QQ和微信两种账号进行授权鉴权。所有接口均通过请求参数中传递的 (授权令牌)来进行身份认证和鉴权,系统会在校验 有效、接口调用配额未用完、接口调用频次未超限3个条件符合后接受此次请求进行具体业务处理并做出响应。
1. 如何通过 OAuth 2.0 获得
客户需要通过您的应用进行推广操作时,您的应用需要先引导客户完成至少一次 OAuth 2.0 认证操作,以便获得调用接口操作的客户的推广帐号所必须的 。 API的 OAuth 2.0 遵循业界通用的规范和流程,完成 OAuth 2.0 认证(当前只支持 -side 模式)需要完成以下步骤:
详细描述如下:
步骤1:引导客户完成OAuth 2.0认证获得
获得 需要引导客户完成 OAuth 2.0 的认证。调用 OAuth 2.0 授权页面的URL形如:
%3a%2f%2f%%3da%%3db&state=&scope=&=
其中:
OAuth 2.0 授权页面如下图所示:
其中页面右侧为应用程序信息,左侧为请求授权的帐号信息,客户可以切换选择是用QQ号还是用微信号,推荐开发者直接在引导客户进入授权页时通过指定要授权的账号类型。
右侧显示的是应用程序的logo、名称、以及可授权的权限组分类。
左侧是提供给授权客户进行身份验证的入口。如客户同意授权,需要登录其对应的 帐号或者用微信号扫码,并点击同意授权。
登录后,页面将会显示请求授权的 账号信息。
值得注意的是,请求授权的 帐号需要是商务管家、代理商或直客广告主的开户 QQ,或者是子客户的自理管理 QQ,微信账号需要是微信广告账号对应的公众号管理员微信,或者微信广告代理商的管理员微信,否则将会授权失败。
不同类型的帐号在同意授权后,应用可操作的推广帐号不同,具体规则如下:
当引导客户在上述登录界面完成登录身份验证后,系统会携带 (有效期5分钟)和state两个参数在浏览器端发出GET请求,形如:
当上述请求完成或请求链接超出3秒时,系统会自动跳转到刚才定义的回调地址中。您的应用程序在收到上述返回后,应当在 有效期内,利用 获得 (详见下一步),并在跳转后的页面对客户给出相应的提示或跳转指引。
步骤2:使用 获得 和
用 获得 和 的接口地址为 ,接口输入参数如下表所示:
名称
类型
描述
应用 id,在开发者官网创建应用后获得,可通过 [应用程序管理页面] 查看
应用 ,在开发者官网创建应用后获得,可通过 [应用程序管理页面] 查看
字段长度最小 1 字节,长度最大 256 字节
请求的类型,可选值: (授权码方式获取 token )、 (刷新 token )
字段长度最小 1 字节,长度最大 64 字节
OAuth 认证 code,可通过获取 Code 接口获取,当 = 时必填
字段长度最小 1 字节,长度最大 64 字节
应用 token,当 = 时必填
字段长度最小 1 字节,长度最大 256 字节
应用回调地址,当 = 时, 为必传参数,仅支持 http 和 https,不支持指定端口号,且传入的地址需要与获取 时,传入的回调地址保持一致
字段长度最小 1 字节,长度最大 1024 字节
请求示例:
curl -G 'https://api.e.qq.com/oauth/token'
-d 'client_id='
-d 'client_secret='
-d 'grant_type=authorization_code'
-d 'authorization_code='
-d 'redirect_uri=https://www.example.com'
返回示例:
{
code: 0,
message: ,
data: {
access_token: 228bd56b7ee039540953352f766b40d31651487e,
refresh_token: 854e744a1f4c6fc20f498e366b9aabd2c4b971fd,
access_token_expires_in: 86400,
refresh_token_expires_in: 2592000
}
}
获得 后,您可用此调用接口对相关的推广帐号进行操作,如果发起 API请求可通过发起请求章节进行了解。
值得注意的是,一旦 失效,您将无法调用接口。 和 的有效期可以通过 oauth/token 接口的返回字段获取,默认情况下 和 的有效期如下:
2. 如何更新
在有效期内,您可以用 通过 auth/token 接口刷新 。请求示意如下:
curl -G 'https://api.e.qq.com/oauth/token'
-d 'client_id='
-d 'client_secret='
-d 'grant_type=refresh_token'
-d 'refresh_token='
特别注意,每次刷新时, 会自动续期。
3. 如何更新
如果 失效,您需要重新通过 OAuth 2.0 获得新的 和 。 关于 OAuth 2.0 相关接口说明,可以参考接口清单中的 OAuth 相关接口。
![](http://419ai.oss-cn-beijing.aliyuncs.com/2023/07/20230726191152761.png)