# Marketing API 接入说明

# 一、申请创建外部应用

接入Marketing API 申请步骤:

1、联系对应AM,提供需开通Marketing API 的“账户id”和“账户名称”

2、AM进行申请

3、申请通过后,AM提供appId、appKey等应用信息

# 二、token获取

# 1. token创建

接口:https://global.e.mi.com/foreign/token/createToken

请求方式: POST

Content-Type:application/json

请求参数:

字段
类型
是否必传
appId
String
appKey
String

返回值:

字段
类型
备注
accessToken
String
token
expireDate
String
token过期时间
refreshToken
String
更新token,只能用来置换token
refreshExpireDate
String
置换token过期时间
{ "code": 0, "message": "成功", "result": { "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcHBJZCI6Indtc2oiLCJhcHBLZXkiOiJhYmMxMjMiLCJleHAiOjE2NjU3NDMyODR9.PqIZJbQdrgWe-pseyhJo3sxsGZroIBiasaSmKkh9QCM", "expireDate": "2022-10-14T10:28:04.570Z", "refreshExpireDate": "2022-10-21T09:28:04.570Z", "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJncmFudF90eXBlIjoicmVmcmVzaCIsImFwcElkIjoid21zaiIsImFwcEtleSI6ImFiYzEyMyIsImV4cCI6MTY2NjM0NDQ4NH0.uD3TAbgU6X8ouX-Ra7A4LVKMgb_qi7btNagaG2_2ccY" } }

# 2. 更新token

接口:https://global.e.mi.com/foreign/token/refreshToken

请求方式: POST

Content-Type:application/json

请求参数:

字段
类型
是否必传
refreshToken
String

返回值:

字段
类型
备注
accessToken
String
token
expireDate
String
token过期时间
refreshToken
String
更新token,置换token
refreshExpireDate
String
置换token过期时间

# 三、设置公共参数

参数位置: Cookie

字段
类型
是否必填
备注
access_token
String
token
timestamp
Long
时间戳
uid
String
请求唯一id(每次请求均唯一)
ip
String
请求IP

# 四、广告接口介绍

# 1. 广告计划

# 1.1. 获取广告计划

接口/foreign/marketing/campaign/list

请求方式GET

Content-Type:application/json

请求参数:

字段
类型
描述
page
int
当前页码1
pageSize
int
页面大小 默认值:10
accountIds
List<Long>
账号id列表
campaignIds
List<Long>
计划id列表

返回值:

字段
类型
描述
accountId
long
账号id
campaignId
int
广告计划id
name
String
广告计划名称
dayBudget
long
日预算 单位:美元*100000
campaignType
int
1.应用下载 2. H5 3. 再营销

返回示例:

{ "code": 0, "message": "成功", "result": { "size": 10, "total": 2, "current": 1, "pages": 2, "records": [ { "accountId": 1, "campaignId": 100205030, "name": "广告组1", "dayBudget": 3000000, "campaignType": 1, }, { "accountId": 1, "campaignId": 100205031, "name": "广告组2", "dayBudget": 3000000, "campaignType": 2, } ] } }

# 1.2. 新增广告计划

接口/foreign/marketing/campaign/add

请求方式POST

Content-Type:application/json

请求参数:

字段
类型
是否必填
描述
accountId
Long
账号id
campaignName
String
计划名称(默认为M_推广目标_创建时间)
dayBudget
Long
日预算(单位:美元*100000)
campainType
Integer
计划类型(1.应用下载 3. 再营销)
uniKey
String
唯一字符串

请求示例:

[ { "accountId": "1420", "campaignName":"测试计划", "campainType": 1, "dayBudget": 3000000, "uniKey": "hNtN5LseHtaAAG0G" }, { "accountId": "1420", "campaignName":"测试计划1", "campainType": 1, "dayBudget": 10000000, "uniKey": "oCtdQktKeC6lsODu" } ]

返回示例:

{ "code": 0, "message": "成功", "result":[ {"uniKey": "oCtdQktKeC6lsODu", "id":75312748}, {"uniKey": "hNtN5LseHtaAAG0G", "id":93472403} ] }

# 2. 广告组

# 2.1. 获取广告组

接口/foreign/marketing/group/list

请求方式GET

Content-Type:application/json

请求参数:

字段
类型
描述
page
int
当前页码1
pageSize
int
页面大小 默认值:10
accountIds
List<Long>
账号id列表
campaignIds
List<Long>
计划id列表
groupIds
List<Long>
广告组id列表

返回值:

字段
类型
描述
accountId
long
账号id
groupId
int
广告组id
name
String
广告组名
dayBudget
long
日预算 单位:美元*100000
billingType
int
11. CPA 2. CPC
productType
int
1. GA 2. GP
bid
long
出价 单位:美元*100000
region
List<String>
区域
campaignId
long
广告计划id

返回示例:

{ "code": 0, "message": "成功", "result": { "size": 10, "total": 2, "current": 1, "pages": 2, "records": [ { "accountId": 1, "groupId": 100205030, "name": "广告组1", "dayBudget": 3000000, "billingType": 11, "productType": 1, "bid": 100000, "region": ["RU","afghanistan_badakhshan_new","616436"], "campaignId": 100205030 }, { "accountId": 1, "groupId": 100205031, "name": "广告组2", "dayBudget": 3000000, "billingType": 11, "productType": 1, "bid": 100000, "region": ["RU","afghanistan_badakhshan_new","616436"], "campaignId": 100205030 } ] } }

# 2.2. 新增广告组

接口/foreign/marketing/group/add

请求方式POST

Content-Type:application/json

请求参数:

字段
类型
是否必填
描述
accountId
Long
账号id
campaignId
Long
计划id
groupName
String
广告组名称(默认为M_推广目标_创建时间)
packageName
String
包名
productType
Integer
推广产品(1.GA 2.GP)
settlementType
Integer
结算方式(1. 小米 2. 第三方)
mediaAndTagIds
JSON
屏蔽媒体和广告位
regions
List<String>
投放国家/地区
billingType
Integer
出价类型(11.CPA 2.CPC 1.OCPC)
bid
Long
出价(单位:美元*100000)
dayBudget
Long
日预算(单位:美元*100000)
beginTime
Long
投放起始时间
endTime
Long
投放结束时间
uniKey
String
唯一字符串

请求示例:

[ { "accountId": 1420, "campaignId": 75312748, "groupName": "测试广告组1", "packageName": "a.b.c", "productType":1, "settlementType":1, "mediaAndTagIds":{ "all": false, "exclude": [ { "id": 1, "type": "mediaClass", "all": false, "subList": [ { "id": 386, "type": "media", "all": false, "subList": [ { "id": "1.386.1.1", "type": "tagId", "all": true, "subList": [] } ] } ] }, { "id": 4, "type": "mediaClass", "all": false, "subList": [] } ] }, "regions": ["IN","ID"], "billingType": 11, "dayBudget": 3000000, "bid": 10000, "timeZone": "+8", "beginTime": "", "endTime": "", "uniKey": "0ah0Ko2UCl48htsz" }, { "accountId": 1420, "campaignId": 93472403, "groupName": "测试广告组2", "packageName": "a.b.c", "productType":1, "settlementType":1, "mediaAndTagIds":{ "all": false, "exclude": [ { "id": 1, "type": "mediaClass", "all": false, "subList": [ { "id": 386, "type": "media", "all": false, "subList": [ { "id": "1.386.1.1", "type": "tagId", "all": true, "subList": [] } ] } ] }, { "id": 4, "type": "mediaClass", "all": false, "subList": [] } ] }, "regions": ["IN","ID"], "billingType": 11, "dayBudget": 3000000, "bid": 10000, "beginTime": "1711612800000", "endTime": "1711785600000", "uniKey": "yAHqxOaIIw4wnV13" } ]

返回示例:

{ "code": 0, "message": "成功", "result":[ {"uniKey": "oCtdQktKeC6lsODu", "id":39451985}, {"uniKey": "hNtN5LseHtaAAG0G", "id":98724407} ] }

# 2.3. 修改广告组

接口/foreign/marketing/group/update

请求方式POST

Content-Type:application/json

请求参数:

字段
类型
描述
groupIds
List<Long>
广告组id列表
regions
List<String>
投放国家/地区
dayBudget
Long
日预算(单位:美元*100000)
bid
Long
出价

请求示例:

{ "groupIds": [32434,2346], "regions": ["IN","ID"], "dayBudget": 500000, "bid": 100000 }

返回示例:

{ "code": 0, "message": "成功" }

# 2.4. 获取国家列表

接口/foreign/marketing/region/countryList

请求方式GET

Content-Type:application/json

返回示例:

{ "code": 0, "message": "成功", "result": [ { "geoType": "COUNTRY", "id": "AF", "name": "Afghanistan" }, { "geoType": "COUNTRY", "id": "AX", "name": "Aland islands" } ] }

# 2.5. 获取国家下地区

接口/foreign/marketing/region/getByCountry

请求方式GET

Content-Type:application/json

请求参数:

字段
类型
描述
country
String
国家

返回示例:

{ "code": 0, "message": "成功", "result": [ { "geoType": "PROVINCE", "id": "afghanistan_badakhshan_new", "name": "badakhshan", "subGeo":[ { "geoType": "CITY", "id": "616418", "name": "ab barek" }, { "geoType": "CITY", "id": "616436", "name": "ab chanar" } ] }, { "geoType": "PROVINCE", "id": "afghanistan_badghis_new", "name": "badghis" } ] }

# 2.6. 根据广告组ID获取媒体(修改时获取)

接口/foreign/marketing/group/getMediaList

请求方式GET

Content-Type:application/json

请求参数:

字段
类型
描述
groupIds
List<Long>
广告组id列表

返回示例:

优选版位:

[ { "groupId":123456, "desc": "优选版位", "description": "", "id": 1, "name": "优选版位", "subSelectOption": [ { "desc": "内部媒体", "description": "", "id": 1, "name": "内部媒体", "subSelectOption": [ { "desc": "海外负一屏(widget)", "description": "", "id": 386, "name": "海外负一屏(widget)", "subSelectOption": [ { "desc": "1.386.1.1", "description": "", "id": "1.386.1.1", "name": "1.386.1.1", "isSelected": true } ] } ] }, { "desc": "联盟媒体", "description": "", "id": 4, "name": "联盟媒体", "subSelectOption": [ { "desc": "Test App Android", "description": "", "id": 512, "name": "Test App Android", "subSelectOption": [ { "desc": "1.512.29.1", "description": "", "id": "1.512.29.1", "name": "1.512.29.1", "isSelected": false } ] } ] } ] } ]

or 自选版位:

[ { "groupId":123456, "desc": "自选版位", "description": "", "id": 2, "name": "自选版位", "subSelectOption": [ { "desc": "Banner", "description": "", "id": 6, "name": "Banner", "subSelectOption": [ { "desc": "内部媒体", "description": "", "id": 1, "name": "内部媒体", "subSelectOption": [ { "desc": "MSASDK_DEMO", "description": "", "id": 300, "name": "MSASDK_DEMO", "subSelectOption": [ { "desc": "1.300.2.5", "description": "", "id": "1.300.2.5", "name": "1.300.2.5", "isSelected": false } ] } ] }, { "desc": "联盟媒体", "description": "", "id": 4, "name": "联盟媒体", "subSelectOption": [ { "desc": "Word Search Block Puzzle Game", "description": "", "id": 511, "name": "Word Search Block Puzzle Game", "subSelectOption": [ { "desc": "1.511.2.1", "description": "", "id": "1.511.2.1", "name": "1.511.2.1", "isSelected": true } ] } ] } ] } ] } ]

# 2.7. 根据广告计划ID获取媒体(新增时获取)

接口/foreign/marketing/group/getMediaListByCampaign

请求方式GET

Content-Type:application/json

请求参数:

字段
类型
描述
campaignIds
List<Long>
计划id集合

返回示例:

优选版位:

[ { "desc": "优选版位", "description": "", "id": 1, "name": "优选版位", "campaignId": 13682, "subSelectOption": [ { "desc": "内部媒体", "description": "", "id": 1, "name": "内部媒体", "subSelectOption": [ { "desc": "海外负一屏(widget)", "description": "", "id": 386, "name": "海外负一屏(widget)", "subSelectOption": [ { "desc": "1.386.1.1", "description": "", "id": "1.386.1.1", "name": "1.386.1.1", "isSelected": true } ] } ] }, { "desc": "联盟媒体", "description": "", "id": 4, "name": "联盟媒体", "subSelectOption": [ { "desc": "Test App Android", "description": "", "id": 512, "name": "Test App Android", "subSelectOption": [ { "desc": "1.512.29.1", "description": "", "id": "1.512.29.1", "name": "1.512.29.1", "isSelected": false } ] } ] } ] } ]

# 2.8. 修改媒体

接口/foreign/marketing/group/media/update

请求方式POST

Content-Type:application/json

请求参数:

字段
类型
描述
groupIds
List<Long>
广告组id列表
mediaAndTagIds
JSON
媒体和广告位
all
boolean
是否全选
exclude
JSONARRAY
当广告组为优选版位时,必填
include
JSONARRAY
当广告组未自选版位时,必填
subList
JSONARRAY
子媒体/广告位

请求示例:

{ "groupIds": [12174], "mediaAndTagIds": { "all": false, "exclude": [{ "id": 1, "type": "mediaClass", "all": false, "subList": [{ "id": 386, "type": "media", "all": false, "subList": [{ "id": "1.386.1.1", "type": "tagId", "all": true, "subList": [] }, { "id": "1.386.1.4", "type": "tagId", "all": true, "subList": [] }, { "id": "1.386.4.1", "type": "tagId", "all": false, "subList": [] }, { "id": "1.386.1.3", "type": "tagId", "all": false, "subList": [] }, { "id": "1.386.1.22", "type": "tagId", "all": false, "subList": [] }, { "id": "1.386.4.10001", "type": "tagId", "all": false, "subList": [] } ] }, { "id": 665, "type": "media", "all": false, "subList": [] }, { "id": 666, "type": "media", "all": false, "subList": [] }, { "id": 668, "type": "media", "all": false, "subList": [] }, { "id": 670, "type": "media", "all": false, "subList": [] }, { "id": 673, "type": "media", "all": false, "subList": [] }, { "id": 674, "type": "media", "all": false, "subList": [] }, { "id": 676, "type": "media", "all": false, "subList": [] }, { "id": 678, "type": "media", "all": false, "subList": [] }, { "id": 301, "type": "media", "all": false, "subList": [] }, { "id": 302, "type": "media", "all": false, "subList": [] }, { "id": 303, "type": "media", "all": false, "subList": [] }, { "id": 304, "type": "media", "all": false, "subList": [] }, { "id": 305, "type": "media", "all": false, "subList": [] }, { "id": 433, "type": "media", "all": false, "subList": [] }, { "id": 306, "type": "media", "all": false, "subList": [] }, { "id": 307, "type": "media", "all": false, "subList": [] }, { "id": 308, "type": "media", "all": false, "subList": [] }, { "id": 309, "type": "media", "all": false, "subList": [] }, { "id": 310, "type": "media", "all": false, "subList": [] }, { "id": 311, "type": "media", "all": false, "subList": [] }, { "id": 312, "type": "media", "all": false, "subList": [] }, { "id": 313, "type": "media", "all": false, "subList": [] }, { "id": 314, "type": "media", "all": false, "subList": [] }, { "id": 315, "type": "media", "all": false, "subList": [] }, { "id": 317, "type": "media", "all": false, "subList": [] }, { "id": 319, "type": "media", "all": false, "subList": [] }, { "id": 323, "type": "media", "all": false, "subList": [] }, { "id": 324, "type": "media", "all": false, "subList": [] }, { "id": 325, "type": "media", "all": false, "subList": [] }, { "id": 328, "type": "media", "all": false, "subList": [] }, { "id": 329, "type": "media", "all": false, "subList": [] }, { "id": 330, "type": "media", "all": false, "subList": [] }, { "id": 460, "type": "media", "all": false, "subList": [] }, { "id": 332, "type": "media", "all": false, "subList": [] }, { "id": 333, "type": "media", "all": false, "subList": [] }, { "id": 334, "type": "media", "all": false, "subList": [] }, { "id": 335, "type": "media", "all": false, "subList": [] }, { "id": 336, "type": "media", "all": false, "subList": [] }, { "id": 337, "type": "media", "all": false, "subList": [] }, { "id": 338, "type": "media", "all": false, "subList": [] }, { "id": 339, "type": "media", "all": false, "subList": [] }, { "id": 340, "type": "media", "all": false, "subList": [] }, { "id": 343, "type": "media", "all": false, "subList": [] }, { "id": 344, "type": "media", "all": false, "subList": [] }, { "id": 347, "type": "media", "all": false, "subList": [] }, { "id": 349, "type": "media", "all": false, "subList": [] }, { "id": 350, "type": "media", "all": false, "subList": [] }, { "id": 351, "type": "media", "all": false, "subList": [] }, { "id": 352, "type": "media", "all": false, "subList": [] }, { "id": 353, "type": "media", "all": false, "subList": [] }, { "id": 354, "type": "media", "all": false, "subList": [] }, { "id": 355, "type": "media", "all": false, "subList": [] }, { "id": 356, "type": "media", "all": false, "subList": [] }, { "id": 357, "type": "media", "all": false, "subList": [] }, { "id": 358, "type": "media", "all": false, "subList": [] }, { "id": 359, "type": "media", "all": false, "subList": [] }, { "id": 360, "type": "media", "all": false, "subList": [] }, { "id": 361, "type": "media", "all": false, "subList": [] }, { "id": 362, "type": "media", "all": false, "subList": [] }, { "id": 363, "type": "media", "all": false, "subList": [] }, { "id": 364, "type": "media", "all": false, "subList": [] }, { "id": 365, "type": "media", "all": true, "subList": [] }, { "id": 366, "type": "media", "all": false, "subList": [] }, { "id": 367, "type": "media", "all": false, "subList": [] }, { "id": 368, "type": "media", "all": false, "subList": [] }, { "id": 369, "type": "media", "all": false, "subList": [] }, { "id": 370, "type": "media", "all": false, "subList": [] }, { "id": 371, "type": "media", "all": false, "subList": [] }, { "id": 628, "type": "media", "all": false, "subList": [] } ] }, { "id": 4, "type": "mediaClass", "all": false, "subList": [] } ] } }

返回示例:

{ "code": 0, "message": "成功" }

属性含义:

include:包含,用于自选版位 exclude:排除,用于优选版位 all:是否全选 subList:子列表,isAll为false时需要填写内容;isAll为true时,为空

# 3. 广告创意

# 3.1. 获取广告创意

接口/foreign/marketing/creative/list

请求方式GET

Content-Type:application/json

请求参数:

字段
类型
描述
page
int
当前页码1
pageSize
int
页面大小,默认值:10
groupIds
List<Long>
广告组id列表

返回值:

字段
类型
描述
accountId
long
账号id
groupId
long
广告组id
creativeId
long
广告创意id
name
String
创意名称
landingUrl
String
点击地址
exposeMonitorUrl
String
曝光监控

返回示例:

{ "code": 0, "message": "成功", "result": { "size": 10, "total": 2, "current": 1, "pages": 2, "records": [ { "accountId": 1, "groupId": 1234, "creativeId": 100205030, "name": "创意名称1", "landingUrl": "https://s.click.aliexpress.com/e/_DC4tkHX", "exposeMonitorUrl": "https://s.click.aliexpress.com/e/_DC4tkHX34" }, { "accountId": 1, "groupId": 1234, "creativeId": 100205031, "name": "创意名称2", "landingUrl": "https://s.click.aliexpress.com/e/_DC4tkHX", "exposeMonitorUrl": "https://s.click.aliexpress.com/e/_DC4tkHX34" } ] } }

# 3.2. 新增广告创意

接口/foreign/marketing/creative/add

请求方式POST

Content-Type:application/json

请求参数:

字段
类型
是否必填
描述
accountId
Long
账号id
groupId
Long
广告组id
creativeName
String
创意名称(M_GA/GP_国家/地区_投放开始日期)
imgUrls
JSONARRAY
创意图片
vedioUrls
JSONARRAY
创意视频
iconUrl
JSON
图标(首次必填)
title
String
广告标题
description
String
广告描述
button
String
按钮文字
landingUrl
String
点击地址
deeplinkUrl
String
deeplink
exposeMonitorUrl
String
曝光监测
uniKey
String
唯一字符串

请求示例:

[ { "accountId": 307, "groupId": 103038, "creativeName": "测试广告创意1", "imgUrls": [{"materialUrl":"https://t7.a.market.xiaomi.com/thumbnail/png/w1000/AdCenter/041d8edcec8cf4635bc3e805fa21a28d8c31844de/041d8edcec8cf4635bc3e805fa21a28d8c31844de.png","materialId":153188815,"width":600,"height":500},{"materialUrl":"https://t7.a.market.xiaomi.com/thumbnail/png/w1000/AdCenter/08e6d9c772e28432990b3e71a53d0a6367327cc7f/08e6d9c772e28432990b3e71a53d0a6367327cc7f.png","materialId":153188881,"width":600,"height":500}], "iconUrl": {"materialUrl":"https://t7.a.market.xiaomi.com/thumbnail/jpeg/w1000/AdCenter/00f663f09d257480f9cbc309f8d0742f4cce661f1/00f663f09d257480f9cbc309f8d0742f4cce661f1.jpeg","materialId":168227440,"width":84,"height":84}, "title": "标题", "description": "描述", "button": "Install", "landingUrl": "https://magnifier.sng.link/B0dnr/pj8j?_dl=com.mobileguru.fruitgardenblast.free%3A%2F%2F&aifa={gaid}&pcid={groupId}&cl={ext}&pcn={campaignId}&pshid={tagId}", "deeplinkUrl": "lazada://sg/web/www/marketing/gateway/index.html?null&dsource=sml&exlaz=e_DoiSug0NEP7Gip8qo24MCfU%252BqLKrZhcY%252BYT1MfH074zCXvTKdNAtBekmwronlsSBS2AvU1L%252BAVXJaw5ibSqRgt7gRm2qOE7bD3WnASIas1Y%253D&os=Android&gps_adid={gaid}&device_make=xiaomi&adtype=Push&sub_id1={ext}&rta_event_id={triggerId}", "uniKey": "QFHJU2Xpa00nC4Tr" } ]

返回示例:

{ "code": 0, "message": "成功", "result":[ {"uniKey": "QFHJU2Xpa00nC4Tr", "id":33858248} ] }

# 3.3. 修改广告创意

接口/foreign/marketing/creative/update

请求方式POST

Content-Type:application/json

请求参数:

字段
类型
描述
creativeIds
List<Long>
广告创意id列表
landingUrl
String
点击地址
exposeMonitorUrl
String
曝光检测

请求示例:

{ "creativeIds": [32434,2346], "landingUrl": "https://xxxx", "exposeMonitorUrl": "https://xxxx" }

返回示例:

{ "code": 0, "message": "成功" }

# 3.4. 文件上传

接口/foreign/marketing/upload

请求方式: POST

Content-Type:application/json

字段
类型
是否必填
描述
file
MultipleFile
上传的文件
accountId
Long
账号id
fileType
int
1. 图片 2. 视频 3. 图标

返回示例:

{ "code": 0, "message": "", "result": { "height": 261, "id": 41491554, "url": "https://t7.a.market.xiaomi.com/thumbnail/png/w1000/AdCenter/076eeb887cf3c41aa9e9f1d87d96ab372c716ecd3/076eeb887cf3c41aa9e9f1d87d96ab372c716ecd3.png", "width": 1080 } }

# code码对照表

code
备注
0
调用成功
10001
无效token
10002
无效appId或appKey
10003
无任何账户查询权限
10004
accountId未授权
20001
请求参数异常
20002
接口调用频率过高
100500
服务端异常