API文档下载      demo下载

当贝点金媒体对接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拼接如下:

  1. 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
appId int 媒体ID 应用ID,请参考应用列表
channel String 渠道定向 默认为0-不限,如果指定投放渠道,请参考渠道列表
city String 地区定向 默认为0-不限,如果指定投放城市,请参考城市列表
device 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 应用名称 应用名称
appType int 应用类型 参数说明:1.电视类  2.手机类  3.PC类
platform int 应用平台 参数说明:1.电视  2.手机

2.4. 系统参数通用字段

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

3. 接口说明

3.1. 公共字段

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

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

3.2. 获取签名

签名规则:

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

签名步骤:

  1. 所有参数按照名字进行升序排列
  2. 根据签名规则,构造被签名串
  3. 计算签名
    • 如果参数中出现空格,以“%20”代替
    • 使用HmacSHA256算法获取签名,加密秘钥APP_SECRET和appKey是唯一对应,联系后台申请获取
    • 将签名进行Base64编码,使用“+”替换其中的空格
    • 将编码后的结果进行Url编码,获取最终签名值
  4. 构造URL请求

例:获取应用列表接口:

https://eopenapi.dangbei.com/v1/application/list.do

参数列表:

  1. {
  2. "timestamp": 1489986317971,
  3. "appKey": "1887d011e00163e0",
  4. "pageIndex": 1,
  5. "pageSize": 5,
  6. "sort": "-id",
  7. "name": "影视快搜"
  8. }

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

  1. https://eopenapi.dangbei.com/v1/application/list.do\nappKey=1887d011e00163e0&name=影视快搜&pageIndex=1&pageSize=10&sort=id&timestamp=1489986317971

对上面字符串加密,获取签名:

  1. gQYtPAlYDIx%2F21kSutTMJbDYS3NRoiz6l12ey7NKi14%3D

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

  1. https://eopenapi.dangbei.com/v1/application/list.do?appKey=1887d011e00163e0&name=影视快搜&pageIndex=1&pageSize=10&sort=id&timestamp=1489986317971&signature=gQYtPAlYDIx%2F21kSutTMJbDYS3NRoiz6l12ey7NKi14%3D

3.3. 获取项目列表

参数名 类型 长度 属性 描述
pageIndex int - 选填 起始页码,默认为1
pageSize int - 选填 每页个数,默认为10
sort String 15 选填 排序字段,如id。前面加负号,代表倒序排列,如"-id",只能选择一个字段
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "totalRecordNo": 711,
  6. "totalPageNo": 143,
  7. "campaigns": [
  8. {
  9. "adType": 1,
  10. "endDate": "2017-05-28",
  11. "price": "1300",
  12. "clickable": 0,
  13. "name": "丝蕴",
  14. "id": 1291,
  15. "position": 1,
  16. "clickInfo": "",
  17. "startDate": "2017-04-08",
  18. "budget": "100000000",
  19. "status": 1
  20. },
  21. {
  22. "adType": 1,
  23. "endDate": "2017-04-25",
  24. "price": "1000",
  25. "clickable": 0,
  26. "name": "唯品会",
  27. "id": 1059,
  28. "position": 1,
  29. "clickInfo": "",
  30. "startDate": "2017-04-19",
  31. "budget": "50000000",
  32. "status": 1
  33. }
  34. ]
  35. }
  36. }
名称 类型 描述
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. 获取指定项目

参数名 类型 长度 属性 描述
id int - 必填 项目ID
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "adType": 1,
  6. "endDate": "2017-03-21",
  7. "price": 1500,
  8. "clickable": 1,
  9. "name": "佳沛奇异果",
  10. "id": 925,
  11. "position": 1,
  12. "clickInfo": "class:,actionName:com.tv.kuaisou.action.DetailActivity,packageName:com.tv.kuaisou,params:id:578549;from_ad:true,h5Name:,h5Prefix:,h5Url:,h5Suffix:",
  13. "startDate": "2017-03-20",
  14. "budget": 1000000,
  15. "status": 1,
  16. "materials":[
  17. "http://imge.dangbei.net/advertImage/20170617/8d6b4179fa5cc77072894471040f4f53.jpg",
  18. "http://imge.dangbei.net/advertImage/20170617/3af4a09617253742f663fb1bf3dda3ab.jpg"
  19. ]
  20. }
  21. }
名称 类型 描述
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. 创建项目

参数名 类型 长度 属性 描述
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)
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "campaignId": 123
  6. }
  7. }
名称 类型 描述
campaignId int 项目id

3.6. 修改项目

参数名 类型 长度 属性 描述
id int - 必填 项目ID
name String 30 选填 项目名称
startDate Date - 选填 开始时间需大于今天(yyyy-MM-dd),审核之后不能修改起始日期
endDate Date - 选填 结束时间需大于开始时间(yyyy-MM-dd)
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "campaignId": 123
  6. }
  7. }
名称 类型 描述
campaignId int 项目id

3.7. 上传广告素材

广告形式 单图(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。

  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "campaignId": 123
  6. }
  7. }
名称 类型 描述
campaignId int 项目id

3.8. 获取广告位列表

参数名 类型 长度 属性 描述
pageIndex int - 选填 起始页码,默认为1
pageSize int - 选填 每页个数,默认为10
sort String - 选填 排序字段,如placementId。前面加负号,代表倒序排列,如"-placementId "。只能选择一个字段排序
campaignId int - 必填 项目ID
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "totalRecordNo": 20,
  6. "totalPageNo": 1,
  7. "campaignId": 123,
  8. "placements": [
  9. {
  10. "placementId": 1000,
  11. "appId": 13,
  12. "medium": "影视快搜",
  13. "channel": "0",
  14. "device": "0",
  15. "city": "0",
  16. "dailyFreq": 8,
  17. "totalFreq": 0,
  18. "status": 0,
  19. "monitors": [
  20. {
  21. "clickUrl": "http://click11",
  22. "impUrl": "http://impl11",
  23. "monitorName": "MiaoZhen"
  24. },
  25. {
  26. "clickUrl": "http://click22",
  27. "impUrl": "http://impl22",
  28. "monitorName": "AdMaster"
  29. }
  30. ]
  31. },
  32. {
  33. "placementId": 1000,
  34. "appId": 48,
  35. "medium": "当贝市场",
  36. "channel": "0",
  37. "device": "0",
  38. "city": "0",
  39. "dailyFreq": 8,
  40. "totalFreq": 0,
  41. "status": 0,
  42. "monitors": []
  43. }
  44. ]
  45. }
  46. }
名称 类型 描述
totalRecordNo int 总记录数
totalPageNo int 总页数
campaignId int 项目id
placements Arrays 广告位信息

广告位placements参数:

名称 类型 描述
placementId int 广告位id
appId int 媒体ID
medium String 媒体名称
channel String 投放渠道
device String 投放设备
city String 投放城市
status int 广告位状态
dailyFreq int 每日频控
totalFreq int 周期频控
monitors Arrays 第三方监控

监控者monitors参数:

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

3.9. 创建广告位

参数名 类型 长度 属性 描述
campaignId int - 必填 项目ID
appId String - 必填 应用ID,详见参数接口。0代表不限应用投放,同时指定多个应用时以英文逗号隔开
channel String 1000 必填 渠道定向,多个渠道时以英文逗号隔开,0代表不限
device String 1000 必填 设备定向,0代表不限
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

组合方式如下:

  1. [
  2. {
  3. "monitorName": "MiaoZhen",
  4. "implUrl": "http://impl1",
  5. "clickUrl": "http://click1"
  6. },
  7. {
  8. "monitorName": "AdMaster",
  9. "implUrl": "http://impl2",
  10. "clickUrl": "http://click2"
  11. }
  12. ]
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "placementId": "1000,1001,1002"
  6. }
  7. }
名称 类型 描述
placementId int 创建成功的广告位id

3.10. 修改广告位

参数名 类型 长度 属性 描述
placementId int - 必填 广告位ID
channel String - 选填 渠道定向,填写渠道编号,多个渠道时以英文逗号隔开,获取渠道列表
city String - 选填 城市定向,填写城市编号,多个城市时以英文逗号隔开,获取城市列表
device String - 选填 设备定向,填写设备编号,多个设备时以英文逗号隔开,获取设备列表
dailyFreq int - 选填 每日频控,0-不限,最大值255
totalFreq int - 选填 周期频控,0-不限,最大值255
status int - 选填 状态,0上线,1暂停
  1. {
  2. "code": 0,
  3. "message": "success"
  4. }

3.11. 获取广告项目数据

参数名 类型 长度 属性 描述
campaignId int - 必填 项目ID
type int - 必填 类别:0.按天  1.按小时
createDate Date - 选填 查询日期,格式yyyy-MM-dd
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": [
  5. {
  6. "createDate": "2017-08-16",
  7. "imps": 0,
  8. "clicks": 0,
  9. "createTime": "00:00:00"
  10. },
  11. {
  12. "createDate": "2017-08-16",
  13. "imps": 0,
  14. "clicks": 0,
  15. "createTime": "01:00:00"
  16. },
  17. {
  18. "createDate": "2017-08-16",
  19. "imps": 0,
  20. "clicks": 0,
  21. "createTime": "02:00:00"
  22. }
  23. ]
  24. }
名称 类型 描述
createDate Date 日期
createTime Time 时间点
imps int 展现量
clicks int 点击量

3.12. 获取广告位数据

参数名 类型 长度 属性 描述
campaignId int - 必填 项目ID
placementId int - 必填 广告位ID
type int - 必填 类别: 0.按天  1.按小时
createDate Date - 选填 查询日期,格式yyyy-MM-dd
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": [
  5. {
  6. "createDate": "2017-08-16",
  7. "imps": 0,
  8. "clicks": 0,
  9. "createTime": "00:00:00"
  10. },
  11. {
  12. "createDate": "2017-08-16",
  13. "imps": 0,
  14. "clicks": 0,
  15. "createTime": "01:00:00"
  16. },
  17. {
  18. "createDate": "2017-08-16",
  19. "imps": 0,
  20. "clicks": 0,
  21. "createTime": "02:00:00"
  22. }
  23. ]
  24. }
名称 类型 描述
createDate Date 日期
createTime Time 时间点
imps int 展现量
clicks int 点击量

3.13. 获取应用列表

参数名 类型 长度 属性 描述
pageIndex int - 选填 起始页码,默认为1
pageSize int - 选填 每页个数,默认为10
name String 15 选填 应用名称,支持模糊查询
sort String 10 选填 排序字段,如id。前面加负号,代表倒序排列,如"-id",只能选择一个字段
  1. {
  2. "code": 0,
  3. "message": "success"
  4. "result": {
  5. "totalRecordNo": 2,
  6. "totalPageNo": 1,
  7. "apps": [
  8. {
  9. "appType": 1,
  10. "name": "测试apk",
  11. "id": 1,
  12. "platform": 1
  13. },
  14. {
  15. "appType": 1,
  16. "name": "测试apk2",
  17. "id": 2,
  18. "platform": 1
  19. }
  20. ]
  21. }
  22. }
名称 类型 描述
totalRecordNo int 总应用数
totalPageNo int 总页数
apps Arrays 应用集合
id int 应用ID
name String 应用名称
appType int 应用类型
platform int 应用平台

3.14. 获取指定应用

参数名 类型 长度 属性 描述
id int - 选填 应用ID
name String 25 选填 应用名称,不支持模糊查询
  1. {
  2. "code": 0,
  3. "message": "success"
  4. "result": {
  5. "appType": 1,
  6. "name": "测试apk",
  7. "id": 1,
  8. "platform": 1
  9. }
  10. }
名称 类型 描述
id int 应用ID
name String 应用名称
appType int 应用类型
platform int 应用平台

3.15. 获取渠道列表

参数名 类型 长度 属性 描述
pageIndex int - 选填 起始页码,默认为1
pageSize int - 选填 每页个数,默认为10
name String 15 选填 渠道名称,支持模糊查询
sort String 10 选填 排序字段,如id。前面加负号,代表倒序排列,如"-id",只能选择一个字段
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "totalRecordNo": 179,
  6. "totalPageNo": 60,
  7. "params": [
  8. {
  9. "name": "aijia",
  10. "id": 1
  11. },
  12. {
  13. "name": "baofeng",
  14. "id": 2
  15. },
  16. {
  17. "name": "bestv",
  18. "id": 3
  19. }
  20. ]
  21. }
  22. }
名称 类型 描述
totalRecordNo int 总数
totalPageNo int 总页数
params Arrays 参数集合
id int 编号
name String 名称

3.16. 获取指定渠道

参数名 类型 长度 属性 描述
id int - 选填 渠道ID
name String 25 选填 渠道名称,不支持模糊查询
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "name": "dangbei",
  6. "id": 7
  7. }
  8. }
名称 类型 描述
id int 渠道ID
name String 渠道名称

3.17. 获取城市列表

参数名 类型 长度 属性 描述
pageIndex int - 选填 起始页码,默认为1
pageSize int - 选填 每页个数,默认为10
name String 15 选填 城市名称,支持模糊查询
sort String 10 选填 排序字段,如id。前面加负号,代表倒序排列,如"-id",只能选择一个字段
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "totalRecordNo": 369,
  6. "totalPageNo": 37,
  7. "params": [
  8. {
  9. "name": "北京市",
  10. "id": 1156110000
  11. },
  12. {
  13. "name": "张家口市",
  14. "id": 1156130700
  15. },
  16. //...
  17. ]
  18. }
  19. }
名称 类型 描述
totalRecordNo int 总数
totalPageNo int 总页数
params Arrays 参数集合
id int 城市编号
name String 城市名称

3.18. 获取指定城市

参数名 类型 长度 属性 描述
id int - 选填 渠道ID
name String 25 选填 城市名称,不支持模糊查询
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "name": "北京市",
  6. "id": 1156110000
  7. }
  8. }
名称 类型 描述
id int 城市ID
name String 城市名称

3.19. 获取设备列表

参数名 类型 长度 属性 描述
pageIndex int - 选填 起始页码,默认为1
pageSize int - 选填 每页个数,默认为10
name String 15 选填 设备名称,支持模糊查询
sort String 10 选填 排序字段,如id。前面加负号,代表倒序排列,如"-id",只能选择一个字段
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "totalRecordNo": 11,
  6. "totalPageNo": 3,
  7. "params": [
  8. {
  9. "name": "小米电视",
  10. "id": 2
  11. },
  12. {
  13. "name": "乐视电视",
  14. "id": 3
  15. },
  16. //...
  17. ]
  18. }
  19. }
名称 类型 描述
totalRecordNo int 总数
totalPageNo int 总页数
params Arrays 参数集合
id int 设备编号
name String 设备名称

3.20. 获取指定设备

参数名 类型 长度 属性 描述
id int - 选填 设备ID
name String 25 选填 设备名称,不支持模糊查询
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "result": {
  5. "name": "乐视电视",
  6. "id": 3
  7. }
  8. }
名称 类型 描述
id int 设备编号
name String 设备名称

4. 注意事项

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.修改素材上传接口,新增上传视频封面。