MW Logo

活动API说明



一、安全机制

1、获取access_token

用户可以使用account_key和secret_code调用本接口来获取access_token。account_key和secret_code可在魔窗后台【应用管理】->【企业配置】->【数据接口参数信息】中获得。

注意:调用所有魔窗接口时均需使用http协议。
请求说明:

http请求方式:GET

http://api.magicwindow.cn/api/auth/token?account_key=ACCOUNT_KEY&secret_code=SECRET_CODE

参数说明:
参数 是否必填 说明
account_key 用户KEY
secret_code 魔窗后台提供的secret code进行MD5加密(32位,大小写皆可)后的值。
返回说明:

正常情况下,魔窗会返回下述JSON数据包给用户:

{"access_token":"ACCESS_TOKEN","expires_in":1866}

参数 说明
access_token 获取到的凭证
expires_in 凭证剩余有效时间,单位:秒

错误时魔窗会返回错误码等信息,JSON数据包示例如下(该示例为AppID无效错误):

{"error_code":400101,"error_message":"account key is required"}

access_token是魔窗活动数据API的全局唯一凭证,调用各接口时都需使用access_token。开发者需要进行妥善保存。access_token的存储至少要保留512个字节空间。access_token的有效期目前为2个小时,需定时刷新,重复获取将导致上次获取的access_token失效。

2、access_token生成方式

a、为了保密secret,魔窗用户需要一个access_token获取和刷新的中控服务器。而其他业务逻辑服务器所使用的access_token均来自于该中控服务器,不应该各自去刷新,否则会造成access_token覆盖而影响业务;

b、目前access_token的有效期通过返回的expires_in来传达,表示到目前此access_token到失效还有多长时间(秒)。中控服务器需要根据这个有效时间提前去刷新新access_token。在刷新过程中,中控服务器对外输出的依然是老access_token,此时公众平台后台会保证在刷新短时间内,新老access_token都可用,这保证了第三方业务的平滑过渡;


如果第三方不使用中控服务器,而是选择各个业务逻辑点各自去刷新access_token,那么就可能会产生冲突,导致服务不稳定。



二、批量活动数据接口

1、活动列表

返回类型 活动类型type值 活动名 活动ID UUID(手机号) 数据1 数据2 数据3
类型1 1 红包 活动Key uuid money - -
砍价 活动Key uuid money - -
类型2 2 签到 活动Key uuid 固定值1 - -
联合推广 活动Key uuid 活动Key - -
邀请码 活动Key uuid 邀请码 - -
大转盘 活动Key uuid 奖项key - -
分享送优惠券 活动Key uuid 优惠券key - -
团购 活动Key uuid 邀请码 - -
类型3 3 用户反馈 活动Key uuid 活动Key 调研值一 调研值二

2、各类活动数据接口API

协议 : HTTP/HTTPs

支持方法:GET

Content-Type(Mime-Type) :application/json

数据格式:标准JSON

返回:HTTP 200, 其他返回客户端作对应处理

2.1 获取活动数据接口调用说明

http请求方式: GET

a.获取所有ACTIVITY_KEY列表

http://api.magicwindow.cn/api/activity/data/list?account_key=ACCOUNT_KEY&access_token=ACCESS_TOKEN

b.每个ACTIVITY_KEY获得活动数据

http://api.magicwindow.cn/api/activity/data/batch?account_key=ACCOUNT_KEY&access_token=ACCESS_TOKEN&activity_key=ACTIVITY_KEY&page=PAGE&page_size=PAGE_SIZE&is_increment=IS_INCREMENT

2.2 获取某个活动请求接口(批量接口)

a.获取活动列表信息

请求参数列表

字段 说明 字段类型 是否必填 示例 备注
account_key Account key String Y 847eaab767d543ff894dc9e81e536de23
access_token Access Token String Y 50ff17451833ff8b32e7b98d92101efee5e81a2d7aaf4629338365f2ed5fabee 64位字符串,参考【一、安全机制

返回参数列表

字段 说明 字段类型 示例 备注
status 返回状态 Int 0 0 - 正常;非0 - 不正常
msg String 在status为非0时,返回具体错误信息或代码
data JSON Object
count 此次请求返回记录数量 Int 66
records Array
activity_key 活动唯一键值 String DJ5SLS3I 用于步骤2中查询活动数据的参数
activity_name 活动名称 String 测试活动
activity_status 活动状态 Int 0 0-关闭, 1-开启

b.根据ACTIVITY_KEY获取活动数据

请求参数列表

字段 说明 字段类型 是否必填 示例 备注
account_key Account key String Y 847eaab767d543ff894dc9e81e536de23
access_token Access Token String Y 50ff17451833ff8b32e7b98d92101efee5e81a2d7aaf4629338365f2ed5fabee 64位字符串,参考【一、安全机制
activity_key 具体活动的编码 String Y DJ5SLS3I 活动对应Key
page 请求数据的页数 Int N 1 默认值1,从1开始算
page_size 每次请求数量 Int N 100 默认100,最大值为200,超过200,按照200计算
is_increment 是否只是发送增量数据 Int N 0 默认值0,发送全部相关数据,参数值为1时,将只发送增量数据

返回参数列表

字段 说明 字段类型 示例 不同活动类型返回对应字段 备注
status 返回状态 Int 0 * 0 - 正常;非0 - 不正常
msg String * 在status为非0时,返回具体错误信息或代码
data Array *
activity_key 活动唯一键值 String DJ5SLS3I * 为了方便用户校验结果
type 活动类型 Int 1 * 请参考【1、活动列表】中列出活动类型对应Type值,决定records中返回字段
next_page 是否还有更多活动数据 Int 0 * 0-数据已经全部被请求,1-还有数据,可以加大参数page继续请求活动数据
count 此次请求返回记录数量 Int 66 * 返回结果中records的数量
records Array *
mwd_id magic window 参考ID,对该设备唯一 String * 客户那里没有映射关系的话,这个字段请忽略,当活动用户在非APP内参与活动,此字段为空
uuid 用户唯一的标志 String 13666666666 * 现阶段我们会传回用户参与活动时填写的手机号
date_created 参与时间 Long 140239402394 * 长整型,北京时间 ,距1970年的时间戳,单位:毫秒
amount 金额 Double 98.66 1 单位RMB,精度00.00
item_key 活动物品KEY String KD787SDFS 2 在后台配置活动时候输入物品对应的KEY

三、实时活动数据推送接

1、流程说明

对于活动产生的每条数据,在存储数据库之后,将会从数据库取出发送到用户指定的URL地址。

回调URL可在【应用设置】->【企业配置】->【活动数据回调接口设置】进行配置

2、传输说明

协议 : HTTP/HTTPs

支持方法: POST

Content-Type(Mime-Type) :application/json

数据格式:标准JSON

返回:HTTP 200, 其他返回客户端作对应处理

3、API说明

3.1 现有活动分类

返回类型 活动类型Type值 活动名 活动ID UUID(手机号码) 数据1 数据2 数据3
类型一 0 APP宣传 NA - - - -
节假日
加油
个人成就
NA - - - -
类型二 2 签到 活动KEY uuid 活动物KEY - -
联合campaign 活动KEY uuid 活动物KEY - -
老带新 活动KEY uuid 活动物KEY - -
大转盘抽奖 活动KEY uuid 活动物KEY - -
分享送优惠券 活动KEY uuid 活动物KEY - -
团购 活动KEY uuid 邀请码 - -
类型三 3 用户反馈 活动KEY uuid 活动物KEY 调研值1 调研值2
类型四 1 红包 活动KEY uuid MONEY - -
砍价 活动KEY uuid MONEY - -

3.2 配置说明

用户需要配置好自己接受数据的URL。

HTTP Method Endpoint URL 备注
POST 活动配置中指定

3.3 发送格式(amount和item_key只会同时一个有意义)

字段名称 字段描述 字段类型
activity_key 活动唯一键值 string
type 活动类型 int
count 此次发送数据的条目数,固定为1 int
records array
mw_id magic window 参考ID,对该设备唯一 string
uuid 用户唯一的标志 string
date_created 参与时间 long
amount 数值,可以使价格或数量(无意义值为0) double/INT
item_key 活动物品KEY(无意义则为空) string

3.4 返回数据格式

字段 描述 备注
status 0 成功接收并处理 对于其他情况的出现,因现在不支持重发,以后再作指定

四、返回码说明

返回码 错误码描述 说明
400101 account key is required 缺失account key
400102 secret code is required 缺失secret code
400103 activity key is required 缺失activity key
400104 access token is required 缺失access token
400105 app key is required 缺失app key
400106 uuid is required 缺失uuid
400201 account key is not exist 不合法的account key
400202 secret code is not matched with the account passed 不合法的secret code
400203 invalid access token 不合法的调用凭证access token
400204 activity key is not exist for the account you passed 不合法的activity key
400205 app key is not exist for the account you passed 不合法的调用凭证app key

五、返回数据实例

数值型实例:

下面的砍价代表手机号为13816555435的用户于XXX时间一共砍了9503元,而用户13566666666一分钱都没砍到

key型实例:

下面代表有七个用户抽取了优惠券,其中手机号为13585896555的用户于XXX时间获得一张九折券