快速入门

本节将为您介绍如何成为Marketing API开发者，开启您的智能化营销体验生活。

在调用Marketing API接口前，您必须先注册成为开发者并创建应用申请对应的接口权限。以下将分别为您介绍开发者注册以及应用创建的具体流程。请您重点关注文档中加粗、变色部分的描述。

1. 如何注册成为开发者？

当您决定开始使用Marketing API进行接口调用，您需要首先注册成为开发者：

Step 1：进入注册页面。点击开发者官网右上角注册按钮即可进入；

Step 2：关联QQ号作为开发者登录凭证。进入注册页面后，如果当前电脑已经登录QQ客户端，则默认显示以当前登录QQ号作为快捷登录，您也可以点击“帐号密码登录”换用其他QQ号；
Tips:

1. 关联QQ号是开发者登录的唯一凭证，且不能进行修改。对于企业开发者，建议使用公用QQ帐号进行注册，并妥善保管。

2. 如果您已经是腾讯广告的客户（代理商或广告主），建议您直接用代理商帐号或广告主帐号的开户QQ进行注册。

Step 3：完善开发者资料。将资料填写完整并通过手机验证码验证通过后，即完成开发者注册。

2. 如何创建应用程序并申请权限？

2.1 开发者应用的分类及作用

通过腾讯广告开发者专区创建的应用程序是指基于Marketing API开发的应用，比如管理广告的投放平台、广告数据分析工具、自动化营销的脚本等。创建应用程序的目的是为了获取所需接口在正式环境的调用权限。在获取正式环境的接口权限前，建议您先通过沙箱环境进行接口调试。

开发者应用按注册者类型和权限范围，可以分为私有应用及第三方应用两类（每一类应用最多可申请20个）。下面将介绍这两类应用的适用场景及具体差异。

私有应用

当您的开发者注册QQ同时是代理商、广告主、商务管家等身份的开户QQ时，您可创建私有应用，通过该应用，您可以直接操作注册QQ对应的账号名下的广告身份（如代理商可操作代理商本人及其子客信息，商务管家账号可以操作商务管家账号下认领的广告账号信息）。

Tips:

• 私有应用仅能管理注册QQ对应的账号身份，不可以进行第三方授权（oAuth授权）管理其他账号。
• 与第三方应用相比，私有应用在权限审核、令牌获取等场景门槛较低。

第三方应用

当您希望通过Marketing API管理多广告账号、或为广告行业提供第三方技术服务时，您可以通过创建第三方应用来实现。

Tips:

• 无论开发者注册QQ是否拥有广告业务身份，您均可以注册第三方应用
• 该QQ身份为开发者身份的唯一凭证，建议使用公司公共QQ注册，避免后续人员变动导致的账号权限问题。
• 支持第三方授权（oAuth授权），因此为了保证数据安全性，第三方应用的权限审核相较私有应用会更加严格

2.2 应用的申请及创建

Step1: 注册成为开发者后，在开发者官网进行登陆并进入应用程序管理看板，可选择创建私有应用或第三方应用（私有应用的前置条件是您的开发者注册QQ账号同时为代理商、广告主、商务管家等身份的开户QQ），则界面会显示相应的创建入口如下图：

Step 2：点击“创建新应用”进入创建应用程序界面，填写应用名称、应用介绍信息等。请注意，私有应用需要填写的内容比第三方应用少，但仅可管理该QQ号对应的广告账号。

• 应用图标：360 x 360 px 的应用图标。
  • 显示在OAuth 2.0 授权页面中，作为推广客户（服务商/广告主）识别应用的标识
• 应用名称：应用程序的名称，多个应用程序不允许重名。
  • 显示在OAuth 2.0 授权页面中，作为推广客户（服务商/广告主）识别应用的标识
• 应用介绍：介绍您的应用程序希望基于Marketing API实现的功能及您需要功能通过审核的原因。
• 回调地址将用于OAuth 2.0授权完成后的跳转及信息返回到您指定地址，供您获取相关返回信息,详情可参考发起请求。
• Access Token有效期：该应用下access token的有效时长，默认为24小时
• Refresh Token有效期：该应用下refresh token的有效时长，默认为30天，refresh token有效期需大于access token。
• 注：access token 和 refresh token详细介绍见授权认证。

Step 3：您可根据使用需要选择对应的权限组分类，权限组分类的详细介绍可通过权限等级进一步了解 – 创建后，私有应用自动审核通过，您可以立即开始相关能力的搭建。第三方应用则会在2-3个工作日内进行审核。

• 如您的应用还未开发完成，建议先使用沙箱环境进行调试。

• 第三方应用的开发者可根据获取到的应用程序id（client_id）及client_secret，以此发起OAuth 2.0 授权获得指定推广帐号的操作权限，详情参考授权认证。

  

3. 发起请求，开启智能化营销体验

3.1 授权认证{ #auth }

Token是在Marketing API操作指定账号的身份凭证，当您需要操作特定广告账号时，您需要使用该广告账号对您的开发者应用进行授权，以获取access_token和refresh_token，所有接口均通过请求参数中传递的 access_token（授权令牌）来进行身份认证和鉴权，系统会在校验 access_token有效、接口调用配额未用完、接口调用频次未超限3个条件符合后接受此次请求进行具体业务处理并做出响应。

Marketing API目前支持代理商/商务管家/广告主等账号类型进行授权鉴权。

本节将为您介绍如何进行 Marketing API 的授权认证 。

该环节您可以获取指定账号的access_token和refresh_token，其中：

• access_token是您调用接口时，操作指定广告账号的身份凭证，默认有效期24小时。您可以通过开发者应用管理页面，修改该token的有效时长
• refresh_token是用于刷新access_token的凭证，用于向系统获取新的access_token(具体操作方法见后文），默认有效期30自然日，每次刷新access_token的操作可自动刷新refresh_token有效期的起始计算时间

• 大量使用错误的token操作账号的行为可能导致您的IP被封停，请您关注并监控错误信息

  

3.1.1 私有应用如何获取access_token和refresh_token

进入应用详情界面

1. 首先选择您要操作的账户身份：如广告主、服务商、商务管家、T1等（因同一个QQ可以同时具有多个身份，不同的身份的token是不同的）。

2. 点击“获取或重置”即可获取或者重置您的token

• token信息获取时仅展示一次，请妥善保存
• token生成后10分钟后生效

• 重置token，该身份下在该应用上的旧 refresh_token 和 access_token 会立即失效

  

  

3.1.2 第三方应用如何通过 OAuth 2.0 获得 access_token

客户需要通过您的应用进行推广操作时，您的应用需要先引导客户完成至少一次 OAuth 2.0 认证操作，以便获得调用接口操作的客户的推广帐号所必须的 access_token 。Marketing API的 OAuth 2.0 遵循业界通用的规范和流程，完成 OAuth 2.0 认证（当前只支持 server-side 模式）需要完成以下步骤：

• A、引导客户进入 OAuth 2.0 登录界面；
• B、客户用推广帐号登录；
• C、登录成功并确认授权后广点通向您的应用程序返回一个授权码（Authorization Code）；
• D、应用程序调用接口用授权码（Authorization Code）获得 access_token，同时获得一个用于刷新 access_token 的 refresh_token；

• E、在 access_token 过期后，使用 refresh_token 获得新的 access_token（可选）。

  

详细描述如下：

Step 1：引导客户完成OAuth 2.0认证获得authorization_code，获得 authorization_code 需要引导客户完成 OAuth 2.0 的认证。调用 OAuth 2.0 授权页面的URL形如：https://developers.e.qq.com/oauth/authorize?client_id=123456&redirect_uri=https%3a%2f%2fwww.example.com%3fpara1%3da%26para2%3db&state=&scope=ads_management&account_type=ACCOUNT_TYPE_QQ 。其中：

• client_id：开发者创建的应用程序的唯一标识id，必填，可通过应用程序管理页面查看；

• redirect_uri：回调地址，由开发者自行提供和定义（地址主域需与开发者创建应用程序时登记的回调主域一致），用于跳转并接收回调信息，必填，该字段需要做UrlEncode，确保后续跳转正常；

• state：开发者自定义参数，可用于验证请求有效性或者传递其他自定义信息，回调的时候会原样带回，可选；

• scope：授权的能力范围，可选，不传时表示授权范围为当前应用程序所拥有的所有全部权限；

• account_type：授权用的账号类型，可选，包括QQ号和微信号，不传时默认为QQ号

• OAuth 2.0 授权页面如下图所示：

  

• 其中页面右侧为应用程序信息，左侧为请求授权的帐号信息，客户可以切换选择是用QQ号还是用微信号，推荐开发者直接在引导客户进入授权页时通过account_type指定要授权的账号类型。

• 右侧显示的是应用程序的logo、名称、以及可授权的权限组分类。

• 其中logo、名称是创建应用程序时开发者自行上传的信息，可授权的权限组分类是根据开发者调用oauth/authorize接口同步的scope生成的权限组信息；

• 授权客户可通过列表选择授权给开发者的操作权限。

• 左侧是提供给授权客户进行身份验证的入口。如客户同意授权，需要登录其对应的QQ帐号或者用微信号扫码，并点击同意授权。登录后，页面将会显示请求授权的账号信息。不同类型的帐号在同意授权后，应用可操作的推广帐号不同，具体规则如下：

• 当引导客户在上述登录界面完成登录身份验证后，系统会携带 authorization_code（有效期5分钟）和state两个参数在浏览器端发出GET请求，形如：http://www.example.com/response?authorization_code=6a6b6c6d&state=112233

• 当上述请求完成或请求链接超出3秒时，系统会自动跳转到刚才定义的回调地址中。您的应用程序在收到上述返回后，应当在 authorization_code 有效期内，利用 authorization_code 获得 access_token（详见下一步），并在跳转后的页面对客户给出相应的提示或跳转指引。

Step 2：使用 authorization_code 获得 access_token 和 refresh_token。用 authorization_code 获得 access_token 和 refresh_token 的接口地址为https://api.e.qq.com/oauth/token ，接口输入参数如下表所示：

请求参数：

请求示例：

curl -G 'https://api.e.qq.com/oauth/token' \
    -d 'client_id=<CLIENT_ID>' \
    -d 'client_secret=<CLIENT_SECRET>' \
    -d 'grant_type=authorization_code' \ 
    -d 'authorization_code=<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 
    }
}

获得 access_token 后，您可用此调用接口对相关的推广帐号进行操作，如果发起Marketing API请求可通过发起请求章节进行了解。

值得注意的是，一旦 access_token 失效，您将无法调用接口。access_token 和 refresh_token 的有效期可以通过 oauth/token 接口的返回字段获取，默认情况下 access_token 和 refresh_token 的有效期如下：

• access_token默认有效期为24小时
• refresh_token默认有效期为30天

3.1.3 如何刷新access_token

在refresh_token有效期内，您可以用 refresh_token 通过 auth/token 接口刷新 access_token。请求示意如下：

curl -G 'https://api.e.qq.com/oauth/token' \
    -d 'client_id=<CLIENT_ID>' \
    -d 'client_secret=<CLIENT_SECRET>' \
    -d 'grant_type=refresh_token' \
    -d 'refresh_token=<REFRESH_TOKEN>'

特别注意，每次刷新access_token时， refresh_token会自动续期。

3.1.4 如何刷新refresh_token

如果 refresh_token 失效，您需要重新通过 OAuth 2.0 获得新的 access_token 和 refresh_token 。

关于 OAuth 2.0 相关接口说明，可以参考接口清单中的 OAuth 相关接口。

4. 常见问题

1. 开发者官网的应用程序与推广的应用程序有什么关系？

开发者官网的应用程序是指基于Marketing API开发的应用，比如管理广告的投放平台、广告数据分析工具、自动化营销的脚本等等，而推广的应用程序是指广告主推广的目标应用。两者之前并无任何关联。

2. 我需要为多个应用上报行为数据，需要分别创建应用程序么？

不需要。您只需创建一个应用程序，并申请数据上报的权限即可。一个应用可以获得多个推广帐号的授权，从而帮多个推广帐号上报数据。

3. 应用程序审核通过后，是否就可以操作推广帐号了？

应用程序的审核是指给应用程序分配相应的接口权限，但是应用程序能操作哪些推广帐号，需要通过OAuth 2.0向指定的推广帐号发起授权申请，当指定的推广帐号同意授权后，应用程序即可调用接口对该帐号进行操作。