当贝点金媒体对接API文档

1. 概述

本文档主要是介绍当贝点金的开放接口，目的是满足传媒类公司的广告系统对接当贝点金系统的需求。如果对接过程中出现问题，请参照最后的异常说明检查数据或联系我们及时处理。如您有新的需求和建议，请告知我方，我们将根据自身情况完善服务。

2. 字段说明

2.1. 项目

参数名	类型	描述	说明
id	int	项目编号
name	String	项目名称
position	int	项目类型	参数：1.开屏广告　2.屏保广告　3.贴片广告　4.暂停广告　5.角标广告
adType	int	素材类型	参数：1.图片　 2.视频　 3.GIF
clickable	int	是否可点击	默认为0-不可点击。如果为点击跳转广告，值为1，同时填写clickInfo，详见下面表格
price	int	CPM单价	单位（分）
budget	int	总预算	单位（分）
status	int	广告状态	参数说明： 0.运行中　1.已结束　2.暂停中　3.待审核　4.未通过审核
materials	Array	素材地址	广告物料的地址
startDate	Date	开始日期	格式yyyy-MM-dd
endDate	Date	结束日期	格式yyyy-MM-dd

clickInfo参数如下：

参数名	类型	属性	描述	说明
class	String	选填	类名	和actionName、h5Name互斥，三者必选一
actionName	String	选填	android action	和class、h5Name互斥，三者必选一
packageName	String	必填	应用包名
params	String	选填	参数	参数之间用引文分号隔开，最后一个不加分号。例id:402878;from_ad:true
h5Name	String	选填	H5页面名称	和class、actionName互斥，三者必选一
h5Prefix	String	选填	H5URL前缀
h5Url	String	选填	H5的URL	需要加密处理
h5Suffix	String	选填	H5URL后缀

clickInfo拼接如下：

class:,actionName:com.tv.kuaisou.action.DetailActivity,packageName:com.tv.kuaisou,params:id:578549;from_ad:true,h5Name:,h5Prefix:,h5Url:,h5Suffix:

2.2. 广告位

参数名	类型	描述	说明
campaignId	int	项目ID	广告位所在项目ID
placementId	int	广告位ID	广告位ID
city	String	地区定向	默认为0-不限，如果指定投放城市，请参考城市列表
freqType	int	频控类型	默认为0-不限，1-app频控，2-设备维度频控。同一个广告项目下所有的广告位，只能有一种频控类型。
dailyFreq	int	每日最大展示频率	默认为0-不限，不能和totalFreq共同设置
totalFreq	int	周期最大展示频率	默认为0-不限。不能和dailyFreq共同设置
status	int	广告位状态	0上线 1暂停
monitorName	String	第三方监控者名称	例：MiaoZhen，Admaster，XiuShi
impUrl	String	曝光监控URL	第三方曝光监控代码
clickUrl	String	点击监控URL	第三方点击监控代码

2.3. 应用信息

参数名	类型	描述	说明
id	int	应用ID	应用ID
name	String	应用名称	应用名称

2.4. 系统参数通用字段

参数名	类型	描述	说明
id	int	参数ID	系统参数编号
name	String	参数名称	系统参数名称

3. 接口说明

3.1. 公共字段

在所有接口的请求过程中，除了接口要求的参数之外，下面表格中的参数也都必须携带，否则无法通过校验。

参数名	类型	描述	说明
appKey	String	必填	申请获取的key
timestamp	String	必填	发起请求时的系统时间戳，如1489980371111
signature	String	必填	计算获得的签名

3.2. 获取签名

签名规则：

                        URL  + 方法路径 +  "\n"  + 排序后的参数

签名步骤：

所有参数按照名字进行升序排列

根据签名规则，构造被签名串

计算签名

如果参数中出现空格，以“%20”代替

使用HmacSHA256算法获取签名，加密秘钥APP_SECRET和appKey是唯一对应，联系后台申请获取

将签名进行Base64编码，使用“+”替换其中的空格

将编码后的结果进行Url编码，获取最终签名值

构造URL请求

例：获取指定项目信息：

https://eopenapi.dangbei.com/v2/campaign/info.do

参数列表：

{
    "timestamp": 1489986317971,
    "appKey": "1887d011e00163e0",
    "id": 2019,
}

按参数名进行升序排序，构造参与加密字符串，结果如下：

https://eopenapi.dangbei.com/v2/campaign/info.do\nappKey=1887d011e0016ae1&id=2190&timestamp=1518052373456

对上面字符串加密，获取签名：

gQYtPAlYDIx%2F21kSutTMJbDYS3NRoiz6l12ey7NKi14%3D

根据上面获取到的签名，生成最终的URL:

https://eopenapi.dangbei.com/v2/campaign/info.do\nappKey=1887d011e0016ae1&id=2190&timestamp=15180523734561&signature=gQYtPAlYDIx%2F21kSutTMJbDYS3NRoiz6l12ey7NKi14%3D

3.3. 获取项目列表

访问地址

https://eopenapi.dangbei.com/v2/campaign/list.do
请求方式
GET
　　
功能描述
获取账户下所有项目的列表
　　
请求参数

参数名	类型	长度	属性	描述
pageIndex	int	-	选填	起始页码，默认为1
pageSize	int	-	选填	每页个数，默认为10
sort	String	15	选填	排序字段，如id。前面加负号，代表倒序排列，如"-id"，只能选择一个字段

返回结构

{
    "code": 0,
    "message": "success",
    "result": {
        "totalRecordNo": 711,
        "totalPageNo": 143,
        "campaigns": [
            {
                "adType": 1,
                "endDate": "2017-05-28",
                "price": "1300",
                "clickable": 0,
                "name": "丝蕴",
                "id": 1291,
                "position": 1,
                "clickInfo": "",
                "startDate": "2017-04-08",
                "budget": "100000000",
                "status": 1
            },
            {
                "adType": 1,
                "endDate": "2017-04-25",
                "price": "1000",
                "clickable": 0,
                "name": "唯品会",
                "id": 1059,
                "position": 1,
                "clickInfo": "",
                "startDate": "2017-04-19",
                "budget": "50000000",
                "status": 1
            } 
        ]
    }
}

返回值说明

名称	类型	描述
totalRecordNo	int	总记录数
totalPageNo	int	总页数
id	int	活动id
name	String	活动名称
position	int	广告位置
adType	int	物料类型
price	int	CPM单价（分）
budget	int	总预算（分）
clickable	int	是否可点击
clickInfo	String	跳转信息
status	int	广告状态
startDate	String	开始日期
endDate	String	结束日期

3.4. 获取指定项目

访问地址

https://eopenapi.dangbei.com/v2/campaign/info.do
请求方式
GET
　　
功能描述
获取指定ID的项目基本信息和该项目下的广告位信息
　　
请求参数

参数名	类型	长度	属性	描述
id	int	-	必填	项目ID

返回结构

{
    "code": 0,
    "message": "success",
    "result": {
        "adType": 1,
        "endDate": "2017-03-21",
        "price": 1500,
        "clickable": 1,
        "name": "佳沛奇异果",
        "id": 925,
        "position": 1,
        "clickInfo": "class:,actionName:com.tv.kuaisou.action.DetailActivity,packageName:com.tv.kuaisou,params:id:578549;from_ad:true,h5Name:,h5Prefix:,h5Url:,h5Suffix:",
        "startDate": "2017-03-20",
        "budget": 1000000,
        "status": 1,
        "materials":[
            "http://imge.dangbei.net/advertImage/20170617/8d6b4179fa5cc77072894471040f4f53.jpg",
            "http://imge.dangbei.net/advertImage/20170617/3af4a09617253742f663fb1bf3dda3ab.jpg"
        ]
    }
}

返回值说明

名称	类型	描述
id	int	活动id
name	String	活动名称
position	int	广告位置
adType	int	广告类型
price	int	CPM单价
budget	int	总预算
clickable	int	是否可点击
clickInfo	String	跳转参数
status	int	广告状态
materials	Array	广告素材地址
startDate	String	开始日期
endDate	String	结束日期

3.5. 创建项目

访问地址

https://eopenapi.dangbei.com/v2/campaign/create.do
请求方式
POST
　　
功能描述
用户创建广告项目
　　
请求参数

参数名	类型	长度	属性	描述
name	String	30	必填	项目名称
position	int	-	必填	项目类型
adType	int	-	必填	素材类型
price	int	-	必填	CPM单价，单位（分）
budget	int	-	必填	总预算，单位（分）
clickable	int	-	必填	是否可点击
clickInfo	String	-	选填	跳转参数
startDate	Date	-	必填	开始时间需大于今天（yyyy-MM-dd）
endDate	Date	-	必填	结束时间需大于开始时间（yyyy-MM-dd）

返回结构

{
    "code": 0,
    "message": "success",
    "result": {
            "campaignId": 123
    }
}

返回值说明

名称	类型	描述
campaignId	int	项目id

3.6. 修改项目

访问地址

https://eopenapi.dangbei.com/v2/campaign/update.do
请求方式
POST
　　
功能描述
修改项目信息，项目上线之后不能修改起始展现日期，结束日期不能小于当前时间。
　　　
请求参数

参数名	类型	长度	属性	描述
id	int	-	必填	项目ID
name	String	30	选填	项目名称
startDate	Date	-	选填	开始时间需大于今天（yyyy-MM-dd），审核之后不能修改起始日期
endDate	Date	-	选填	结束时间需大于开始时间（yyyy-MM-dd）

返回结构

{
    "code": 0,
    "message": "success",
    "result": {
            "campaignId": 123
    }
}

返回值说明

名称	类型	描述
campaignId	int	项目id

3.7. 上传广告素材

访问地址

https://eopenapi.dangbei.com/v2/material/upload.do
请求方式
POST
功能描述
为创建的广告项目上传素材。如果项目已有素材，就不能再上传。暂不支持接口修改素材。目前仅开屏广告支持多张素材，且素材必须为静态图片。其他类型广告只能上传一个素材，不同类型广告支持的素材类型格式如下表。

广告形式	单图（png/jpg/gif）	多图（png/jpg）	视频（mp4）
开屏广告	√	√	√
屏保广告	√
贴片广告	√		√
暂停广告	√
角标广告	√

图片最大为500KB，尺寸1920*1080px，GIF最大为5M，视频最大为20M。

请求参数

参数名	属性	描述
campaignId	必填	项目id
timestamp	必填	时间戳
material[i].data	必填	素材文件
material[i].dataMd5	必填	素材文件MD5
material[i].cover	必填	视频素材封面
material[i].coverMd5	必填	视频素材封面MD5

参数详细说明：参数名中i表示表示素材次序，i为正整数。各part header必须包含Content-Disposition（描述），描述中指定name为参数名、filename为文件名；header必须包含Content-Type（类型），类型为part body的MIME类型，避免乱码请指定part body的编码格式charset=UTF-8。

举例说明

传输项目id的header，参数名称：campaignId
Content-Disposition: form-data; name="campaignId",
Content-Type: text/plain; charset=UTF-8

传输第二个素材文件的header，参数名称：material[2].data，文件名：开机视频2.mp4
Content-Disposition: form-data; name="material[2].data"; filename="开机视频2.mp4",
Content-Type: video/mp4

传输第二个素材文件MD5的header，参数名称：material[2].dataMd5
Content-Disposition: form-data; name="material[2].dataMd5"
Content-Type: videotext/plain; charset=UTF-8

传输第二个素材文件封面的header，参数名称：material[2].cover，文件名：开机视频2封面.png
Content-Disposition: form-data; name="material[2].cover"; filename="开机视频2封面.png"
Content-Type: image/png
　　
返回结构

{
    "code": 0,
    "message": "success",
    "result": {
            "campaignId": 123
    }
}

返回值说明

名称	类型	描述
campaignId	int	项目id

3.8. 上传H5开屏广告图标

访问地址

https://eopenapi.dangbei.com/v2/h5Icon/upload.do
请求方式
POST
功能描述
功能描述为创建的广告项目上传素材。如果项目已有素材，就不能再上传。暂不支持接口修改素材。图标包括启动页提示图（选填）和H5页面提示图（选填）。不上传提示图的H5广告使用默认的提示图片。

请求参数

参数名	属性	描述
campaignId	必填	项目id
timestamp	必填	时间戳
homeGuide	必填	启动页提示图文件
homeGuideMd5	必填	启动页提示图文件MD5
h5Guide	必填	H5页面提示图文件
h5GuideMd5	必填	H5页面提示图文件MD5

各part header必须包含Content-Disposition（描述），描述中指定name为参数名、filename为文件名；header必须包含Content-Type（类型），类型为part body的MIME类型，避免乱码请指定part body的编码格式charset=UTF-8。

返回结构

{
    "code": 0,
    "message": "success",
    "result": {
            "campaignId": 123
    }
}

返回值说明

名称	类型	描述
campaignId	int	项目id

3.9. 获取广告位列表

访问地址

https://eopenapi.dangbei.com/v2/placement/list.do
请求方式
GET
　　
功能描述
根据项目ID，分页获取该项目下广告位的信息。
　　
请求参数

参数名	类型	长度	属性	描述
pageIndex	int	-	选填	起始页码，默认为1
pageSize	int	-	选填	每页个数，默认为10
sort	String	-	选填	排序字段，如placementId。前面加负号，代表倒序排列，如"-placementId "。只能选择一个字段排序
campaignId	int	-	必填	项目ID

返回结构

{
    "code": 0,
    "message": "success",
    "result": {
        "totalRecordNo": 20,
        "totalPageNo": 1,
        "campaignId": 123,  
        "placements": [
            {
                "placementId": 1000,
                "city": "0",
                "dailyFreq": 8,
                "totalFreq": 0,
                "status": 0,
                "monitors": [
                    {
                         "clickUrl": "http://click11",
                         "impUrl": "http://impl11",
                         "monitorName": "MiaoZhen"
                    },
                    {
                         "clickUrl": "http://click22",
                         "impUrl": "http://impl22",
                         "monitorName": "AdMaster"
                    }
                ]
            },
            {
                "placementId": 1000,
                "city": "0",
                "dailyFreq": 8,
                "totalFreq": 0,
                "status": 0,
                "monitors": []
            }
        ]
    }
}

返回值说明

名称	类型	描述
totalRecordNo	int	总记录数
totalPageNo	int	总页数
campaignId	int	项目id
placements	Arrays	广告位信息

广告位placements参数：

名称	类型	描述
placementId	int	广告位id
city	String	投放城市
status	int	广告位状态
dailyFreq	int	每日频控
totalFreq	int	周期频控
monitors	Arrays	第三方监控

监控者monitors参数：

名称	类型	描述
monitorName	String	监控者名称
impUrl	String	曝光监控代码
clickUrl	String	点击监控代码

3.10. 创建广告位

访问地址

https://eopenapi.dangbei.com/v2/placement/create.do
请求方式
POST
　　
功能描述
用户创建广告位，并添加监控代码。广告位创建之后，不能修改或添加监测代码。如果需要第三个监控，请在创建广告位之前准备好第三方监控代码，创建时同时加上代码。不支持广告位的删除。如果要设置广告位频控类型（freqType）为设备维度，则所有广告位的频控类型都将统一为设备维度，并且频控类型设定之后无法修改。如果选择admaster监控，请填写admaster为当贝媒体生成的专属监控代码，否则监控无效。
　　
请求参数

参数名	类型	长度	属性	描述
campaignId	int	-	必填	项目ID
city	String	5000	必填	城市定向，多个城市时以英文逗号隔开，0代表不限。例如投放北京和上海两个城市，则传入值为"1156110000,1156310000"，城市编码获取详见参数接口
freqType	int	-	必填	频控类型，0代表不限频控，1代表按app频控，2代表按设备频控。同一个广告项目下的广告位，不能同时设置两种频控类型
dailyFreq	int	-	必填	每日最大展示频率，0代表不限次数
totalFreq	int	-	必填	周期最大展示频率，0代表不限次数
monitors	Arrays	-	选填	监控集合

monitors中的字段信息：

参数名	类型	长度	属性	描述
monitorName	String	15	必填	第三方监控者名称
impUrl	String	500	必填	曝光监控URL
clickUrl	String	500	必填	点击监控URL，如果没有请填写impUrl

组合方式如下：

[
    {
        "monitorName": "MiaoZhen",
        "implUrl": "http://impl1",
        "clickUrl": "http://click1"
    },
    {
        "monitorName": "AdMaster",
        "implUrl": "http://impl2",
        "clickUrl": "http://click2"
    }
]

返回结构

{
    "code": 0,
    "message": "success",
    "result": {
            "placementId": "1000,1001,1002"
    }
}

返回值说明

名称	类型	描述
placementId	int	创建成功的广告位id

3.11. 修改广告位

访问地址

https://eopenapi.dangbei.com/v2/placement/update.do
请求方式
POST
　　
功能描述
修改广告位相关信息
　　
请求参数

参数名	类型	长度	属性	描述
placementId	int	-	必填	广告位ID
freqType	int	-	选填	频控类型，0代表不限频控，1代表按app频控，2代表按设备频控。同一个广告项目下的广告位，不能同时设置两种频控类型
dailyFreq	int	-	选填	每日频控，0-不限，最大值255
totalFreq	int	-	选填	周期频控，0-不限，最大值255
status	int	-	选填	状态，0上线，1暂停

返回结构

{
    "code": 0,
    "message": "success"
}

3.12. 获取广告项目数据

访问地址

https://eopenapi.dangbei.com/v2/statistics/campaign.do
请求方式
GET
　　
功能描述
获取指定广告项目的数据，可分为按天或按小时维度查询
　　
请求参数

参数名	类型	长度	属性	描述
campaignId	int	-	必填	项目ID
type	int	-	必填	类别：0.按天　　1.按小时
createDate	Date	-	选填	查询日期，格式yyyy-MM-dd

返回结构

{
    "code": 0,
    "message": "success",
    "result": [
        {
            "createDate": "2017-08-16",
            "imps": 0,
            "clicks": 0,
            "createTime": "00:00:00"
        },
        {
            "createDate": "2017-08-16",
            "imps": 0,
            "clicks": 0,
            "createTime": "01:00:00"
        },
        {
            "createDate": "2017-08-16",
            "imps": 0,
            "clicks": 0,
            "createTime": "02:00:00"
        }
    ]
}

返回值说明

名称	类型	描述
createDate	Date	日期
createTime	Time	时间点
imps	int	展现量
clicks	int	点击量

3.13. 获取广告位数据

访问地址

https://eopenapi.dangbei.com/v2/statistics/placement.do
请求方式
GET
　　
功能描述
获取指定广告位的数据，可分为按天或按小时维度查询
　　
请求参数

参数名	类型	长度	属性	描述
campaignId	int	-	必填	项目ID
placementId	int	-	必填	广告位ID
type	int	-	必填	类别： 0.按天　　1.按小时
createDate	Date	-	选填	查询日期，格式yyyy-MM-dd

返回结构

{
    "code": 0,
    "message": "success",
    "result": [
        {
            "createDate": "2017-08-16",
            "imps": 0,
            "clicks": 0,
            "createTime": "00:00:00"
        },
        {
            "createDate": "2017-08-16",
            "imps": 0,
            "clicks": 0,
            "createTime": "01:00:00"
        },
        {
            "createDate": "2017-08-16",
            "imps": 0,
            "clicks": 0,
            "createTime": "02:00:00"
        }
    ]
}

返回值说明

名称	类型	描述
createDate	Date	日期
createTime	Time	时间点
imps	int	展现量
clicks	int	点击量

3.14. 获取城市列表

访问地址

https://eopenapi.dangbei.com/v2/params/cityList.do
请求方式
GET
　　
功能描述
获取系统中城市参数列表
　　
请求参数

参数名	类型	长度	属性	描述
pageIndex	int	-	选填	起始页码，默认为1
pageSize	int	-	选填	每页个数，默认为10
name	String	15	选填	城市名称，支持模糊查询
sort	String	10	选填	排序字段，如id。前面加负号，代表倒序排列，如"-id"，只能选择一个字段

返回结构

{
    "code": 0,
    "message": "success",
    "result": {
        "totalRecordNo": 369,
        "totalPageNo": 37,
        "params": [
             {
                "name": "北京市",
                "id": 1156110000
            },
            {
                "name": "张家口市",
                "id": 1156130700
            },
            //...
        ]
    }
}

返回值说明

名称	类型	描述
totalRecordNo	int	总数
totalPageNo	int	总页数
params	Arrays	参数集合
id	int	城市编号
name	String	城市名称

3.15. 获取指定城市

访问地址

https://eopenapi.dangbei.com/v2/params/cityInfo.do
请求方式
GET
　　
功能描述
获取系统中指定城市信息
　　
请求参数

参数名	类型	长度	属性	描述
id	int	-	选填	城市ID
name	String	25	选填	城市名称，不支持模糊查询

返回结构

{
    "code": 0,
    "message": "success",
    "result": {
        "name": "北京市",
        "id": 1156110000
    }
}

返回值说明

名称	类型	描述
id	int	城市ID
name	String	城市名称

4. 注意事项

为了能让广告获得最大的覆盖量，请提前上线广告。
考虑广告一般会提前上线，客户端会提前缓存广告。为避免这种影响造成展现量的误差，所以广告位仅支持新增，不支持删除和修改。
项目上线之后，不能修改素材。
如果广告位需要第三方监控，请在创建广告位的时候，一起加上监控代码。广告位创建之后，不能再修改和添加监控代码。
目前当贝点金已经适配的第三方监控包括秒针、AdMaster和秀视。鉴于各个第三方监控的监控链接宏替换参数各不相同，如果您选择的第三方监控非以上三家，投放前请联系我们先做测试，否则造成第三方统计不准的情况，将以当贝点金统计为结算依据。
由于AdMaster针对各个投放平台生成的专属代码各不相同，其他平台专属的监控代码可能无法在当贝点金上使用，所以请选择生成当贝专属监控代码。
appKey和秘钥都是唯一对应，请妥善保管。

5. 异常说明

错误码	错误信息	解释	描述
400	Bad Request	请求错误	非法请求
401	Unauthorized	未授权	请求没有携带身份验证，或者身份验证失败
404	Not Found	未找到	请求的资源不存在
405	Method Not Allowed	请求方式错误	发送的请求方式不匹配
408	Require Timeout	请求超时	发起请求的时间和服务器接受到请求时间相差大于±1分钟
412	Parameter Deficiency	参数缺失	缺少必要的参数
422	Unprocessable Entity	无法处理的实体	传递至接口的内容验证不通过
428	Signature Error	签名认证失败	签名和加密字符串不符合
429	Too Many Requests	请求次数太多	请求次数达到频控限制
435	Parameter Error	参数值有误	传递的参数值不符合规定
436	File Md5 Error	上传文件有误	上传文件的MD5和服务端接受到文件的MD5不一致
500	Internal Server Error	服务器内部错误	遇到这种情况，请及时联系我们
502	Bad Gateway	网关错误	API 服务临时关闭，或在升级中
503	Service Unavailable	服务不可用	API 服务器在运行，请求太多，请稍后重试
504	Gateway Timeout	网关超时	API 服务器在运行，请求不能被响应，请稍后重试

6. 更新说明

版本号	日期	更改内容
V1.0	2017-03-09	起稿
V2.0	2017-06-06	1.去除广告位中第三方监控项目ID和广告位ID字段； 2.新增获取广告位列表和修改广告位功能； 3.新增设备列表和查询单个设备功能。
V2.1	2017-08-21	1.新增获取广告项目数据接口； 2.新增获取广告位数据接口； 3.修改素材上传接口，新增上传视频封面。
V2.2	2019-05-18	1.新增H5广告提示图素材上传； 2.修改广告位相关接口。