SaaS版本回调API

一. 功能介绍

我们的在线SaaS版本提供了一个回调API功能，专门针对用户的历史查询需求进行设计。该功能会将用户之前查询过的手机号设置一个7天的监控周期，在用户查询后的7天内，系统会持续监控这些手机号的风险状况。如果在这个时间窗口内，任何被查询的手机号出现了risk风险等级的变更，我们的回调API会将这些手机号记录下来，客户可实时调用回调API，知道哪些手机号发生了变更，确保获取到的数据是最新的，无需手动重新查询，从而节省了宝贵的时间和资源。

二. RESTful API交付方式

手机号画像数据部署在云端，通过HTTPS的RESTful接口查询使用。每个注册客户会分配一个【snuser】和【snkey】（可在控制台-配置 (opens new window)页面中可以查看），在后续接口调用过程中，作为安全认证。

手机号画像库服务端对查询请求实行IP白名单机制（客户可以在的“控制台-配置 (opens new window)”页面添加自己的IP地址白名单），只有白名单中IP地址才会被允许查询。

（注：需要先申请获取产品使用权限后，才能成功添加IP，IP白名单生效时间为5分钟）

三. 接口设计

3.1 接口查询说明

请求详情	说明
请求地址	https://api.yazx.com/phone/check/v3/callback
请求方式	POST
请求频率	建议5min一次，每次调用都会返回上次调用到这次调用这段时间内风险发生变更的号码，第一次调用会返回7天内所有有变更的号码，每次调用都不会有重复数据，所以建议每次调用都保存好返回数据
延时情况	华南节点<=500ms；华东/华北节点<=600ms

3.1.1 请求数据说明

请求字段	类型	说明
snuser	String	用户识别id（控制台-配置 (opens new window)页面中可以查看）

请求示例如下:

{'snuser': 'test'}

3.1.2 返回数据说明

返回参数	说明
status	状态码
data	由AES的CFB加密的json数组
errmsg	对应状态码返回提示信息

响应示例如下：

{
 'status': 200,
 'data': 'MDEyMzQ1Njc4OWFiY2RlZmYgMJwdXnb9y7fkBR+M/5XFSfehCNg+UvY+HyB7YVCVSyS2ERyH2BKeZfCHFqjzUErw8KVu6QexH+t4u40IPKuM6qXct5lj/ihQ1D1UmGfnT9mrf5GAkKI8i+BWxG0irS6pkH9zcNNKIMXtlrcfd3+KoMeVZQSbjLaD0+oilFZGfWiK0HAm/6srKSAOIMhsCe2+Bf/mvIChCt809wiWWhckXeL/Gb9qqe6KWdZucYZxRi5Awluj5XcPGIILIqfckGvdGMbkOy29JzQDPNvkqlMJ8UY43hTb9o6xmeD+Wjq0CFZEGx9neLc9faDEZSsPM6LRdf5gHWSVkfJ494be4GH+Dw==',
 'errmsg': 'OK'
}

错误码表

Code	说明
200	OK
10000	服务内部错误，请联系管理员
10001	请求体解析错误
10002	请求参数错误
10003	用户或密钥错误
10004	IP不在白名单，请登录控制台添加IP白名单，5分钟生效,可在配置管理 (opens new window)页面添加白名单）
10005	服务不存在
10006	账号已过期
10007	请求次数不足
10008	请求频率过快

data解密后内容示例如下：

[{"phone":"13000000000","last_catch_time":"2022-09-04 20:15:37","risk":9,"risk_tag":1}]

具体参数说明：

参数	参数名称	参数类型	参数说明
phone	手机号	string	返回参数示例"13000000000"
risk	风险分数	integer	基于捕获号码来源渠道、号码状态检测等方式，对手机号的风险程度进行打分，分数范围为【0-9】，分数越大，手机号风险值越高
risk_tag	风险标签	integer	0【无风险】未发现风险 1【猫池卡】 从接码平台或发卡平台直接捕获到黑产持有并使用的手机号 2【沉默卡】通过对手机号的属性，行为，活跃度等多个角度进行综合策略评判，符合黑卡不活跃特征号码 3【账号卡】从发卡平台中捕获黑产出售的业务注册账号对应的手机号 4【拦截卡】黑产通过病毒木马劫持手机短信收发权限，从而控制的手机号码，号码主人为正常用户 5【隐私小号】手机号码租赁平台出售的手机号，容易被黑产购买使用 6【历史风险卡】历史从接码平台或发卡平台直接捕获到黑产持有并使用的手机号，但超过90天未再次捕获，且号码状态发现变化，可能流入正常用户手中 7【网络电话】海外使用基于IP完成语音传输的网络电话号码，如Google Voice 8【疑似猫池卡】手机号码特征符合猫池卡特征的手机号码 9【疑似新号】 疑似新入网的手机号 10【疑似真人作弊】 手机号关联的设备上安装了多款真人众包软件，疑似真人众包兼职群体使用的手机号
last_catch_time	最近活跃时间	datetime	该黑卡最近被监控活跃时间 示例“2018-07-10 08:23:14”

注： risk与risk_tag后期会有新增，使用上请做好冗余。

risk与risk_tag对应说明

risk	对应的risk_tag
risk9	risk_tag=1(猫池卡)、 risk_tag=8(疑似猫池卡)
risk8
risk7	risk_tag=4(拦截卡)
risk6	risk_tag=2(沉默卡)
risk5	risk_tag=6(历史风险卡)
risk4	risk_tag=10(疑似真人作弊)
risk3	risk_tag=9(疑似新号)
risk2	risk_tag=3(账号卡)、 risk_tag=5(隐私小号)、 risk_tag=7(网络电话)
risk1
risk0	risk_tag=0(无风险)

四. DEMO示例

• Go
• Java
• Python