# 基本信息
# 法律声明
客户在与麦晗签署了《商业合作保密协议》后，麦晗将开通客户调⽤API的权限并向客户提供本⽂文档，作为其与mAX广告平台对接的指引⽂文档。未经麦晗书⾯许可，不得以任何形式向第三⽅披露、泄露有关本⽂文档的任何内容。麦晗拥有修改、调整、增补本⽂文件的权利，并在法律允许范围内对本⽂文档拥有最终解释权。
# 1. 关于文档
本文档作为DSP与麦晗程序化广告交易平台（以下简称“mAX”）进行对接的指引文档。主要包括三个部分：
对接流程：阅读对象为DSP的商务人员。该部分说明了DSP与mAX对接的流程和步骤。
Buyer API： 阅读对象为DSP的产品和开发人员。该部分详细描述了DSP向mAX上传/修改广告主/素材信息以及查询广告主/素材审核状态的接口。
实时竞价RTB接口： 阅读对象为DSP的产品和开发人员。该部分详细描述了DSP参与mAX实时竞价的接口协议。
# 2. 背景知识
本API文档所涉及接口均遵循HTTP协议，请求和响应数据格式如无特殊说明均为JSON，您可以使用任何支持HTTP协议和JSON格式的编程语言开发应用程序。
有关标准HTTP协议，可参考 RFC2616 (opens new window) 或 维基百科 (opens new window)-HTTP (opens new window) 相关介绍。有关JSON数据格式，可参考 JSON.ORG (opens new window) 或 维基百科–JSON (opens new window) 相关介绍。
# 3. 对接流程
1、申请并签署协议； 2、开通API: 按要求︎提供需要的相关信息后获得相应的API测试授权; 3、开发对接: 对接过程中如果遇到疑问，可联系运营接⼝人安排相关的产品和技术答疑;
4、测试联调: 在开发完成后，mAX提供测试环境与外部DSP进行测试环境联调，包括Buyer API和实时竞价RTB接口两部分的测试，测试过程中将会向DSP提供测试环境DSPID及授权令牌（TOKEN）；
5、正式环境上线: 测试环境联调通过后，向运营接⼝⼈申请线上正式的授权,正式环境对接完成
# 4. Buyer API
本章节将详细介绍DSP如何使用Buyer API 与mAX进行交互，提交/修改广告主/素材信息，查询广告主/广告审核状态。为确保广告内容的有效性与合法性，所有参与mAX竞价的DSP平台必须将广告主和素材信息提前上传到mAX进行审核，审核通过后方可正常投放，如果DSP返回未经审核通过的广告，将直接被过滤不会被展现。
# 4.1 通用声明
# 4.1.1 权限认证
API 通过授权令牌（TOKEN）和dsp_id进行权限控制。dsp_id和token需要在每次请求时通过请求头传入。
# 4.1.2 编码方式
若无特殊说明或响应头中的Content-Type未指定编码，请求和响应中的字节编码均使用 UTF-8（无 BOM 头）。
# 4.1.3 URL定义
请求URL参考RESTful风格，约定了使用的协议、模块、版本、资源及动作，详细定义如下：
https://{myhayo.max.domain}/<MODULE>/<SUBMODULE>/<API_VERSION>/<RESOURCE_NAME>/<RESOURCE_ACTION>
其中：
- 协议：使用HTTPS
- MODULE: dsp
- SUBMODULE: api
- API_VERSION：版本号，当前版本号码为 v1
- RESOURCE_NAME：表示要操作的资源，如creative
- RESOURCE_ACTION：表示对资源的动作，如add
RESOURCE_NAME支持的资源示例如下：
| 资源 | 描述 |
|---|---|
| advertiser | 广告主 |
| creative | 素材 |
RESOURCE_ACTION支持的基本动作示例如下：
| 操作 | 描述 |
|---|---|
| add | 新增 |
| edit | 修改 |
| get_review_status | 获取审核状态 |
# 4.1.4 API请求
HTTP Method
调用方应设置HTTP Method为 POST/GET。
HTTP Header
调用方应遵循HTTP协议设置相应的 Header，目前支持的Header有：dsp_id、Authorization、Content-Type。dsp_id用于传递mAX为调用发分配的dspid，Authorization用于传递授权令牌（TOKEN），Content-Type用于指定数据格式。本章节中Content-Type应为application/json。
HTTP Header示例
dsp_id: 10001
Authorization: Bearer <TOKEN>
Content-Type: application/json
# 4.1.5 API响应
HTTP状态码
支持HTTP标准状态码，具体如下：
| 状态码 | 名称 | 描述 |
|---|---|---|
| 200 | 成功 | 当 API 请求被正确处理，且能按设计获取结果时，返回该状态码；亦适用于批量接口返回部分结果 |
| 3xx | 跳转 | 在特定情况下，API 可能会返回这些状态码，建议调用方按照 HTTP 标准来处理 |
| 4xx | 客户端错误 | 由客户端原因造成的错误 |
| 5xx | 服务器端错误 | API 或其下层服务发生内部错误 |
其中，4xx 和 5xx 的状态码仅用于辅助调用方快速识别问题，不作为包含实际语义的错误码，若有调整也不另行通知，实际操作结果以API返回的数据为准。调用方也应能够识别和处理由于网络异常等因素导致的，由非API 服务返回的 HTTP 状态码，如 504 Gateway Timeout 等。
HTTP Header
响应会根据接口要求设置Content-Type。本章节中Content-Type均设置为application/json。
HTTP Body
响应的JSON数据中包含三部分内容，分别为返回码、返回信息和数据，如下表所示：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| code | int | 是 | 返回码： 200表示成功，其他表示失败。具体见返回码列表 |
| msg | string | 否 | 返回信息：若有错误，此字段为详细的错误信息。 |
| data | json array 或 json object | 否 | 返回结果 |
# 4.2 广告主
使用接口进行广告主上传需要先获取由麦晗分配的dsp_id与token，该dsp_id与token同样适用于素材上传接口。
目前提供三个接口：广告主上传接口、广告主更新接口、广告主审核状态查询接口。
# 4.2.1 广告主上传接口
DSP通过http post请求广告主上传接口，进行信息及文件上传。广告主上传信息参数包括广告主ID，广告主名称，行业信息及资质相关附件。
接口地址：http://{myhayo.max.domain}/dsp/api/v1/advertiser/add
请求方法：POST
请求字段：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| advertiser_id | String | 是 | 广告主唯一id |
| name | String | 是 | 广告主名称。请确保此名称与客户营业执照上的名称一致，否则会影响该广告主的审核。 |
| industry_id | String | 是 | 行业分类id，见附录【广告主行业分类】 |
| qualifices | JsonArray | 是 | 广告主资质，图片链接 |
请求示例：
{
"advertiser_id": "11",
"name": "这是一个测试的广告主",
"industry_id": "2353",
"qualifices": [{
"name": "DSP广告业务承揽函",
"file_url": "http://www.test.com/_163288776155e56ad34a50e95b3cfd02e812d7955f.png"
},
{
"name": "营业资质",
"file_url": "http://www.test.com/_1629885437d1ab2a4d1e1cf434c016973b39ae5d8c.jpg"
}]
}
返回结果：
| 名称 | 类型 | 描述 |
|---|---|---|
| advertiser_id | String | 创建成功返回广告主id |
返回示例：
{
"msg": "操作成功",
"trace_id": "cf909b5b3553492e841347b33ff8da45",
"code": 200,
"data": {
"advertiser_id": "17"
}
}
# 4.2.2 广告主修改接口
接口地址：http://{myhayo.max.domain}/dsp/api/v1/advertiser/edit
请求方法：POST
请求字段：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| advertiser_id | String | 是 | 广告主id，不可修改 |
| name | String | 否 | 广告主名称 |
| industry_id | String | 否 | 行业分类 |
| qualifices | JsonArray | 是 | 覆盖之前所有资质 |
请求示例：
{
"advertiser_id": "17",
"qualifices": [{
"name": "DSP广告业务承揽函",
"file_url": "http://www.test.com/_163288776155e56ad34a50e95b3cfd02e812d7955f.png"
},
{
"name": "营业资质",
"file_url": "http://www.test.com/_1629885437d1ab2a4d1e1cf434c016973b39ae5d8c.jpg"
}]
}
返回结果：
| 名称 | 类型 | 描述 |
|---|---|---|
| advertiser_id | int | 创建成功返回广告主id |
返回示例：
{
"msg": "操作成功",
"trace_id": "cf909b5b3553492e841347b33ff8da45",
"code": 200,
"data": {
"advertiser_id": 17
}
}
# 4.2.3 广告主审核状态查询接口
通过http get请求进行查询。广告主上传成功后即可通过该广告主ID进行审核状态查询，审核通过后即可使用该广告主进行素材上传。
接口地址：http://{myhayo.max.domain}/dsp/api/v1/advertiser/get_review_status
请求方法：GET
请求字段：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| advertiser_id | int | 是 | 上传广告主成功后返回的advertiser_id |
请求示例：
http://{myhayo.max.domain}/dsp/api/v1/advertiser/get_review_status?advertiser_id=17
返回结果：
| 名称 | 类型 | 描述 |
|---|---|---|
| advertiser_id | int | 上传广告主返回的广告主id |
| status | String | 审核结果见附录【广告主审核状态】 |
| reason | String | 拒绝原因，状态为拒绝时返回 |
返回示例：
{
"msg": "操作成功",
"trace_id": "83a777b8c68945e58eae71604cdd34bc",
"code": 200,
"data": {
"advertiser_id": 17,
"status": "APPROVED"
}
}
# 4.3 素材
目前提供三个接口：素材上传接口、素材更新接口、素材审核状态查询接口。
# 4.3.1 素材上传接口
接口地址：http://{myhayo.max.domain}/dsp/api/v1/creative/add
请求方法：POST
请求字段：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| advertiser_id | String | 是 | 广告主id |
| creative_id | String | 是 | 素材唯一id，请确保该id为DSP层级下唯一，不会出现不同的广告主有相同的creative_id |
| click_url | String | 是 | 点击广告后着陆地址 |
| detail_page | String | 否 | 详情页，点击非交互按钮区域，跳转到产品详情页。信息流(图文& 视频)、猜你喜欢、视频关联位小图文 广告、焦点图(大 图&视频)以及开机屏 android 端下载情况下必填(否则会出现点击后无反应的情况)。 投放 Android 端不允许填 app 下载地址。 |
| ad_form | int | 是 | 创意类型，目前支持的创意类型见附录【创意类型】 |
| creative_type | int | 是 | 广告形式，1:展示广告，2:视频广告 |
| type | int | 否 | 目前仅支持RTB。1：RTB，默认1 |
| platform | int | 是 | 1:PC， 2: Mobile，3:PAD，4:OTT，21:IOS， 22:Android |
| product_type | int | 是 | 链接类型，0: H5，1: 下载，2: 小程序，3: Deeplink， 4: Universal Link |
| cl_monitor_url | array | 否 | 点击监测，最多支持2条 |
| im_monitor_url | array | 否 | 曝光监测，最多支持2条 |
| deeplink | String | 否 | deeplink |
| template_id | int | 是 | 模版id |
| start_date | datetime | 否 | 开始时间，如：2021-11-18 |
| end_date | datetime | 否 | 结束时间，如：2021-11-18 |
| ad_content | json object | 是 | 素材内容，具体内容视广告样式而定，每种样式要求字段不同 ，根据template_id选填 |
ad_content:
| 名称 | 类型 | 描述 |
|---|---|---|
| title | String | 标题 |
| description | String | 描述 |
| account | String | 品牌名称 |
| apple_id | String | 应用 ID:iPhone 客户端 APP 在苹果 应用商店的 APP id |
| app_name | String | APP名称 |
| button | int | 按钮文案。如：1-查看详情; 2-立即下载; 3-立即咨询; 4-立即抢购。 |
| position | String | 广告展示位置。当上传通用浮 层-角标广告创意时，可填写该字段。备选项为 left、right，默认为 left |
| xapp_id | String | 小程序id |
| xapp_path | String | 小程序路径 |
| video1 | String | 素材视频url。如果有多个，分别为video1，video2，video3... |
| image1 | String | 素材图片url。如果有多个，分别为image1，image2，image3... |
| logo | String | Logo |
| cover_pic1 | String | 封面图（背景图） |
| detail_pic1 | String | 应用详情图。如果有多个，分别为detail_pic1，detail_pic2，detail_pic3... |
| splash_type | int | 开屏类型。1：普通，2：摇一摇 |
请求示例：
{
"advertiser_id": "17",
"creative_id": "16",
"click_url": "https://www.test.com/",
"detail_page": "https://www.test.com/v_2baf6bkf2s8.html?vfrm=pcw_home&vfrmblk=&vfrmrst=709181_%E4%BC%9A%E5%91%98%E7%89%B9%E6%9D%83_%E5%A4%A7%E5%89%A7%E6%8A%A2%E5%85%88%E7%9C%8B_area2",
"ad_form": 13,
"creative_type": 1,
"type": 1,
"platform": 21,
"product_type": 0,
"cl_monitor_url": ["http://cl.monitor.com"],
"im_monitor_url": ["http://im.monitor.com"],
"deeplink": "http://deeplink.com",
"template_id": 111,
"start_date": "2021-11-18",
"end_date": "2021-11-20",
"ad_content": {
"title":"麦晗品牌会员日",
"description ": "老客尊享买一送一 新客低至63元",
"image1": "http://www.test.com/163520570_720x1280_11708301.jpg",
"logo ": "http://www.test.com/1630195338_720x1280_40158301.jpg"
}
}
返回结果：
| 名称 | 类型 | 描述 |
|---|---|---|
| creative_id | int | 创建成功返回素材id |
返回示例：
{
"msg": "操作成功",
"trace_id": "cf909b5b3553492e841347b33ff8da45",
"code": 200,
"data": {
"creative_id": 17
}
}
# 4.3.2 素材修改接口
接口地址：http://{myhayo.max.domain}/dsp/api/v1/creative/edit
请求方法：POST
请求字段：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| advertiser_id | String | 是 | 广告主id |
| creative_id | String | 是 | 素材id |
| click_url | String | 否 | 落地页 |
| detail_page | String | 否 | 详情页 |
| platform | int | 否 | 1:PC， 2: Mobile，3:PAD，4:OTT，21:IOS， 22:Android |
| cl_monitor_url | array | 否 | 点击监测，最多支持2条 |
| im_monitor_url | array | 否 | 曝光监测，最多支持2条 |
| deeplink | String | 否 | deeplink |
| start_date | datetime | 否 | 开始时间，如：2021-11-18 |
| end_date | datetime | 否 | 结束时间，如：2021-11-18 |
| ad_content | json object | 否 | 素材内容，具体内容视广告样式而定，每种样式要求字段不同 |
请求示例：
{
"advertiser_id": 17,
"creative_id": 11,
"click_url": "https://www.test.com/",
"detail_page": "https://www.test.com/v_2baf6bkf2s8.html?vfrm=pcw_home&vfrmblk=&vfrmrst=709181_%E4%BC%9A%E5%91%98%E7%89%B9%E6%9D%83_%E5%A4%A7%E5%89%A7%E6%8A%A2%E5%85%88%E7%9C%8B_area2",
"cl_monitor_url": ["http://cl.monitor.com"],
"im_monitor_url": ["http://im.monitor.com"],
"deeplink": "http://deeplink.com",
"ad_content": {
"title":"麦晗品牌会员日",
"description ": "老客尊享买一送一 新客低至63元",
"image1": "http://www.test.com/163520570_720x1280_11708301.jpg",
"logo ": "http://www.test.com/1630195338_720x1280_40158301.jpg"
}
}
返回结果：
| 名称 | 类型 | 描述 |
|---|---|---|
| creative_id | int | 创建成功返回素材id |
返回示例：
{
"msg": "操作成功",
"trace_id": "cf909b5b3553492e841347b33ff8da45",
"code": 200,
"data": {
"creative_id": 17
}
}
# 4.3.3 素材审核状态查询
通过http get请求进行查询。素材上传成功后即可通过该广告主ID和素材ID进行审核状态查询，审核通过后即可投放。
接口地址：http://{myhayo.max.domain}/dsp/api/v1/creative/get_review_status
请求方法：GET
请求字段：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| advertiser_id | String | 是 | 广告主id |
| creative_id | String | 是 | 上传素材成功后返回的creative_id |
请求示例：
http://{myhayo.max.domain}/dsp/api/v1/creative/get_review_status?advertiser_id=17&creative_id=29
返回结果：
| 名称 | 类型 | 描述 |
|---|---|---|
| creative_id | int | 素材id |
| status | String | 审核结果见附录【素材审核状态】 |
| reason | String | 拒绝原因，状态为拒绝时返回 |
返回示例：
{
"msg": "操作成功",
"trace_id": "841ac88bb6b047b19bebdc0a08171039",
"code": 200,
"data": {
"creative_id": 29,
"status": "PENDING"
}
}
# 5 附录
# 【广告主行业分类】
| 值 | 描述 |
|---|---|
| 2 | 交通航空 |
| 3 | 电子商务 |
| 4 | 房地产 |
| 5 | 时装 |
| 6 | 化妆品 |
| 7 | 家居用品 |
| 8 | 教育 |
| 9 | 保险 |
| 10 | 投资理财 |
| 11 | 高级消费品 |
| 12 | 专业服务 |
| 13 | 纤体美容 |
| 14 | 娱乐 |
| 15 | 电脑 |
| 16 | 汽车 |
| 17 | 饮食 |
| 19 | 医疗保健 |
| 21 | 家具 |
| 22 | 组织 |
| 23 | 电子产品 |
| 24 | 外汇 |
| 25 | 黄金贸易 |
| 27 | 钟表珠宝 |
| 28 | 酒店 |
| 29 | 物流 |
| 30 | 制造 |
| 32 | 第三方支付平台 |
| 33 | 住宅服务 |
| 35 | 餐馆 |
| 36 | 证券 |
| 37 | 电讯 |
| 38 | 运动用品 |
| 39 | 贵金属贸易 |
| 40 | 其他 |
| 41 | 零食百货 |
| 42 | 旅游 |
# 【创意类型】
| 值 | 描述 |
|---|---|
| 1 | 横幅 |
| 2 | 暂停 |
| 3 | 浮层 |
| 4 | 信息流 |
| 5 | 开屏 |
| 6 | 插屏 |
| 7 | 焦点图 |
| 8 | 贴片 |
| 9 | 激励视频 |
| 10 | 屏保图片 |
| 11 | 开机视频 |
| 12 | 前贴 |
| 13 | 视频关联位 |
| 14 | 猜你喜欢 |
# 【广告形式】
| 值 | 描述 |
|---|---|
| 1 | 展示广告 |
| 2 | 视频广告 |
# 【投放平台】
| 值 | 描述 |
|---|---|
| 1 | PC |
| 2 | MOBILE |
| 3 | PAD |
| 4 | OTT |
| 21 | IOS |
| 22 | Android |
# 【链接类型】
| 值 | 描述 |
|---|---|
| 0 | H5 |
| 1 | 下载 |
| 2 | 小程序 |
| 3 | Deeplink |
| 4 | Universal Link |
# 【广告主审核状态】
| 值 | 描述 |
|---|---|
| APPROVED | 审核通过 |
| PENDING | 待审核 |
| REJECTED | 拒绝 |
# 【素材审核状态】
| 值 | 描述 |
|---|---|
| APPROVED | 审核通过 |
| PENDING | 待审核 |
| REJECTED | 拒绝 |
| OFF | 下线 |
# 【错误码】
| 值 | 描述 |
|---|---|
| 200 | 成功 |
| 400 | 错误的请求 |
| 401 | 未授权 |
| 403 | 访问受限 |
| 429 | 超出频次限制 |
| 500 | 系统异常 |
| 10000 | 系统繁忙，请稍后重试 |
| 10004 | 认证失败，请检查参数是否正确 |
| 20002 | 参数错误 |
| 20003 | 数据保存失败 |
| 20005 | 字段必填 |
| 30001 | 广告主不存在 |
| 30009 | 图片或视频地址无法访问 |
| 30021 | 素材不存在 |
| 30022 | 图片大小超出限制 |
| 30023 | 图片分辨率不正确 |
| 30024 | 图片类型不正确 |
| 30025 | 文案长度超出限制 |
| 30026 | 对应的广告位不存在，请检查参数是否正确或联系运营人员 |
| 30034 | 视频大小超出限制 |
| 30035 | 视频类型不正确 |
| 30036 | 视频时长不正确 |
| 30039 | 字段值有误，请查看文档 |
| 30040 | 视频分辨率不正确 |
| 30042 | 无效的platform |
版本信息 →