活动防刷API

更新时间：2024-06-27

概述

活动防刷是基于业务场景，结合IP画像、设备指纹、黑卡检测、威胁情报等多维度信息实时识别风险的专业防护产品，有效识别与解决黄牛党、羊毛党进行刷单刷水、抽奖作弊、恶意下单等营销作弊问题，降低企业经济损失。

如果您是初次调用百度智能云产品的API，可以观看API入门视频指南，快速掌握调用API的方法。

接口规范

URL

项目	解释
地址	https://afd.baidubce.com/rcs/sync-saas
说明	根据输入参数给出作弊风险；请求和响应中所有的文本都使用UTF-8编码
请求方式	Https POST

认证机制

所有API的安全认证一律采用Access Key与请求签名机制。 Access Key由Access Key ID和Secret Access Key组成，均为字符串。对于每个HTTP请求，使用下面所描述的算法生成一个认证字符串。提交认证字符串放在Authorization头域里。服务端根据生成算法验证认证字符串的正确性。认证字符串的格式为：
bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}

version是正整数。
timestamp是生成签名时的UTC时间。
expirationPeriodInSeconds表示签名有效期限。
signedHeaders是签名算法中涉及到的头域列表。头域名之间用分号（;）分隔，如host;x-bce-date。列表按照字典序排列。（本API签名仅使用host和x-bce-date两个header）
signature是256位签名的十六进制表示，由64个小写字母组成。

当百度智能云接收到用户的请求后，系统将使用相同的SK和同样的认证机制生成认证字符串，并与用户请求中包含的认证字符串进行比对。如果认证字符串相同，系统认为用户拥有指定的操作权限，并执行相关操作；如果认证字符串不同，系统将忽略该操作并返回错误码。

鉴权认证机制的详细内容请参见鉴权认证机制。

入参（JSON格式）

参数	说明	类型	是否必需
sc	业务场景标识，活动防刷场景为：bce_activity	String	必选
ts	用户发起请求的时间戳（单位毫秒）	String	必选
m	手机号（sha1密文）	String	必选
ip	用户的外网ip	String	必选
app	系统类型信息：android、ios、universe（其他）	String	必选
appid	应用app唯一标识，您可以在业务安全控制台-应用管理自行创建。测试应用可联系接口人线下颁发。	String	必选
aid	活动id ，您可以通过业务安全控制台-活动管理自行创建。测试活动id可联系接口人线下颁发	String	必选
ev	行为操作，用于标识当前调用环节，预先分配操作编码； page_enter进入活动页面； registered注册； login登录； share分享； liked点赞； vote投票 comment评论； cash_out提现； order下单/提单； pay支付； fee浏览feed； red_envelope领取红包； task做任务； sign签到； invite邀请； lottery抽奖；尽可能按照上述约定传递，如上述通用行为无法满足，您根据当前活动流程，可自行设置调用环节编码，为了能够保证风控服务的灵活性，希望您尽可能详细划分每个调用环节。	String	必选
z	百度昊天SDK获取的zid。为了达到更好的防刷效果，建议您集成。集成后此参数为必选	String	可选
i	imei号	String	可选
mac	MAC地址	String	可选
idfa	IDFA（IOS）	String	可选
idfv	IDFV（IOS）	String	可选
userid	业务方自有用户id	String	可选
ver	app版本号	String	可选
model	设备类型，型号（eg: Lenovo A850）	String	可选
ua	调用活动api使用的user_agent	String	可选
bssid	wifi_bassid base64加密	String	可选
ssid	wifi_ssid wifi名称，base64加密	String	可选
inviterid	邀请者id；师徒邀请关系、拼拆、裂变邀请关系环节，需要传递此关系	String	可选
likedid	此参数主要适用于点赞，投票场景，可传递被点赞、投票的内容id或者用户id	String	可选
cash	奖品金额（等价金额，人民币为币种，单位：元）	String	可选
ct	奖品类型（1：现金或等价物，2:优惠券，3:积分，4:实物，5:其他）	String	可选
lal	经度，纬度 34.234，45.223	String	可选
csr	新老客户：1、新客；2、老客；	String	可选
referer	调用活动api的 referer	String	可选
net	网络类型：3G/4G/5G/wifi等	String	可选
jt	如果接入风控JS SDK（H5版和小程序版），此字段为必选，由业务方前端在提交请求时主动上报给业务方后端，若业务方后端未取到该值必须设置为空字符串。jt 参数含特殊字符，建议业务方前端向业务方后端传参时约定编码解码。该值会随每次请求变化，不可缓存该值。复用同一值可能会校验不通过，请确认业务逻辑中没有重试机制。	String	必选
js_env	如果接入风控JS SDK（H5版和小程序版），此字段为必选，标识 JS 执行环境类型，可选值：h5/h5n/swan。若为端上接入（iOS/Android）则此字段留空；若接入小程序则取值 swan；app 字段为ios/android；若接入流量均来自端能力 h5，则取值为 h5n；app 字段为 ios/android否则取值为 h5，app 字段为 universe。	String	必选
header	如果接入风控JS SDK（H5版和小程序版），此字段为必选，业务方后端收到的完整 HTTP Header，格式为Map[String,String]，出于隐私合规考虑可以不包含 Cookie 字段。请务必提供否则可能校验不通过。	Map[String,String]	必选
extra	Map格式，用于针对一些特殊形式的活动需要增加扩展参数时可使用此预留字段，格式如下：{“key1”:”value1”,”key2”:”value2”,”key3”:”value3”}。如果当前活动有组队等形式，可以在extra中增加{“groupid”:”xxxxxxx”}	Map[String,String]	可选

接入参数举例

    { 
      "sc":"bce_activity",
      "ts": "1584871823371",
      "m": "3fae11dea7c6543266d1ce4183d7826e2d494afb",
      "ip": " 125.124.234.121",
      "app":"android",
      "appid":"1",
      "aid":"99xx",
      "z":"at8TermQ1qVdEokgqxb1LpiGdDDIHv258FKGKh9U3liFHWQhyC_1NsXRYV6avhrsfgeejvaAWmYs4agXcnG1T8jvMuA",
      "i": "863811016480000",
      "imsi": 460023192787105,
      "ev":"page_enter",
      "userId": "111111",
      "ver":"11.10.2",
      "ssid":"JXU2MjExJXU1QkI2JXU3Njg0d2lmaQ==",
      "bssid":"RkYlM0FGRiUzQUZGJTNBRkYlM0FGRiUzQUZG",
      "model":"SM-A8050",
      "ua":"Dalvik/2.1.0 (Linux; U; Android 9; Redmi Note 8 Pro MIUI/V10.4.6.0.PGGCNXM)",
      "mac": "34:17:EB:CE:A3:86",
      "net": "4G",
      "jt": "IzlmdIZpRRBTh9T6/KjRrs8PHFtTNvy9nduzqNQZdVE=……",
      "header": {
       "User-Agent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36(KHTML, like Gecko) Chrome/78.0.3144.128 Safari/537.37",
       "Accept": "application/json, text/javascript, */*; q=0.01",
       "Accept-Encoding": "gzip, deflate, br",
       "Accept-Language": "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7,zh-TW;q=0.6",
       "Connection": "keep-alive",
       "Host": "www.baidu.com",
       "Referer": "https://www.baidu.com/"
      },
       "extra": {"customer": "99324054", "bid": "54323943"}
      }

响应结果

正常返回结果（正常返回结果是一个json）

字段名	类型	描述
request_id	String	服务端请求ID
ret_code	String	0
ret_msg	String	操作成功
ret_data	Map	风险详情
level	String	1：高风险（建议拦截） 2：中风险（建议拦截、或做一些验证） 3：低风险（建议放行） 4：极低风险（建议放行）
t	Array	风险标签

正常返回示例：

 {
    "request_id": "f88150bf-9da1-41fc-a740-b896be20cc31",
    "ret_code": "0",
    "ret_data": {
        "level": "1",
        "t": [
            "XXXX"
        ]
    },
    "ret_msg": "操作成功"
}

异常返回结果

字段名	类型	描述
request_id	String	服务端请求ID
ret_code	String	错误码： 0-正常 1000-签名验证错误 1001-认证失败 1002-请求格式错误 2000-参数不合法 2001-消息体不正确 2002-服务超过最大QPS/服务超过最大调用次数/服务已过期 3000-系统内部错误其他错误码请参见：鉴权认证机制错误码
ret_msg	String	出错信息

异常返回示例：

 { 
    "request_id":"4017678614",
    "ret_code":"1001",
    "ret_msg":"认证失败"
}

超时建议

超时时间建议：当风控接口响应时间过长时，为保障业务顺利运行，业务需要默认放行该次请求，建议超时时间设为200-500ms；

超时重试频次建议：针对重要业务场景，可增加超时重试逻辑。依旧超时情况下放行处理，优先保障业务正常运行。

SDK调用指南

接入流程

注册保护API

百度智能云

业务安全风控 AFD