# 在线API
# 一. RESTful API交付方式
手机号画像数据部署在云端，通过HTTPS的RESTful接口查询使用。每个注册客户会分配一个【snuser】和【snkey】（可在控制台-配置 (opens new window)页面中可以查看），在后续接口调用过程中，作为安全认证。
手机号画像库服务端对查询请求实行IP白名单机制（客户可以在的“控制台-配置 (opens new window)”页面添加自己的IP地址白名单），只有白名单中IP地址才会被允许查询。
（注：需要先申请获取产品使用权限后，才能成功添加IP，IP白名单生效时间为5分钟）
# 二. 接口设计
# 2.1 接口查询说明
| 请求详情 | 说明 |
|---|---|
| 请求地址 | https://api.yazx.com/zhbpro/phone_no_check/v2 (opens new window) |
| 请求方式 | POST |
| 并发 | 200 |
| 默认QPS | 1000 |
| 延时情况 | <=100ms |
# 2.1.1 请求数据说明
| 请求字 段 | 类型 | 说明 |
|---|---|---|
| snuser | String | 用户识别id（控制台-配置 (opens new window)页面中可以查看）； |
| data | List<String> | 将手机号经过sha1加密得到user值组成的json数组再经过AES的CFB加密组成，密钥是snkey（控制台-配置页面中可以查看）。一次性请求手机号最高100个。 |
手机号格式说明
| 国家地区 | 示例 |
|---|---|
| 中国大陆手机号 | 13911112222 |
| 非中国大陆手机号 | +14123521111，+[国家代码][手机号] |
[
{"user": "10bd9f6956a58aebed6ec453ed12e6dacf1ab63f"},
{"user": "cf764873e2e4da2f1ced8cdc68f15e15de74edd0"},
{"user": "8e74aa14c3ed5777711b05d2facfb68ef929748f"}
]
请求示例如下:
{
'snuser': 'test',
'data':'RG/yb3B0sxFbJyvGCHnHVutkcZ3l2MhShhMKu3hvxH1Kwc/7CJgy0uXrSZ2+SPz5X/iPRNZwznsorzZ2pJu/bxjMObTpOik3DiN2M3TQNspSZjon1M/0UlJpoxiqb+2kvhQmsaoqK3Qkry6U0NMs9GlHXKIP4aj1igG3oXQezgRJhKAGQ7ELvLCjQk47ha4oUHCJaYuHye44lN11XkDFax1fJljMsGWEPbP1AcZPpxZH/A=='
}
# 2.1.2 返回数据说明
| 返回参数 | 说明 |
|---|---|
| snuser | 用户识别id |
| status | 状态码 |
| data | 由AES的CFB加密的json数组 |
| errmsg | 对应状态码返回提示信息 |
请求示例如下：
{
u'snuser': u'test',
u'status': 200,
u'data': u'MDEyMzQ1Njc4OWFiY2RlZmYgMJwdXnb9y7fkBR+M/5XFSfehCNg+UvY+HyB7YVCVSyS2ERyH2BKeZfCHFqjzUErw8KVu6QexH+t4u40IPKuM6qXct5lj/ihQ1D1UmGfnT9mrf5GAkKI8i+BWxG0irS6pkH9zcNNKIMXtlrcfd3+KoMeVZQSbjLaD0+oilFZGfWiK0HAm/6srKSAOIMhsCe2+Bf/mvIChCt809wiWWhckXeL/Gb9qqe6KWdZucYZxRi5Awluj5XcPGIILIqfckGvdGMbkOy29JzQDPNvkqlMJ8UY43hTb9o6xmeD+Wjq0CFZEGx9neLc9faDEZSsPM6LRdf5gHWSVkfJ494be4GH+Dw==',
u'errmsg': u'OK'
}
错误码表
| Code | 说明 |
|---|---|
| 200 | 正常状态 |
| 501 | 请求参数错误（请检查请求参数以及aes加密实现） |
| 502 | 错误的请求类型 |
| 503 | 无权限 |
| 504 | 账号额度不足 |
| 505 | 当前请求IP不在白名单中 可在配置管理 (opens new window)页面添加白名单） |
| 506 | 未开通服务 |
| 507 | 账号不可用 |
| 508 | 账号已过期 |
| 511 | 请求的json格式错误 |
data解密后内容示例如下：
[{"user":"10bd9f6956a58aebed6ec453ed12e6dacf1ab63f","uptime":"2017-04-26 17:16:59","risk":9,"ctime":"2017-02-06 12:15:29","location":"广东 深圳 联通","attribute":0,"card_type":1,"p_name_price":"国内微信注册(发短信注册)/3.5"},
{"user":"cf764873e2e4da2f1ced8cdc68f15e15de74edd0","uptime":"2017-04-26 17:16:59","risk":2,"ctime":"2017-04-12 10:21:20","location":"江苏 南京 移动","attribute":0,"card_type":1,"p_name_price":"国内微信注册(发短信注册)/3.5"}]
具体参数说明：
| 参数 | 参数名称 | 参数类型 | 参数说明 |
|---|---|---|---|
| user | 加密手机号(SHA1) | string | 返回参数示例"10bd9f6956a58aebed6ec453ed12e6dacf1ab63f" |
| risk | 风险标签 | integer | 9【高风险】黑产曾使用过号码，近期仍活跃 6【中高风险】号码属性和行为特征异常 5【中风险】黑产曾使用过号码, 近期未被捕获 2【低风险】虚拟小号 0【无风险】正常号码 |
| location | 归属地 | string | 大陆精确到市国外卡只展示归属国家 示例 “南京 联通， 美国” |
| attribute | 卡属性 | integer | 0 基础运营商（移动、联通和电信） 1 虚拟运营商 -1 海外以及港澳台号码 |
| card_type | 卡类型 | integer | 0 普通卡 1 虚拟小号 2 VoIP网络电话 3 拦截卡（解释详情见表下注释） |
| p_name_price | 最近黑卡项目/价格 | string | 该黑卡用于注册xxx平台，验证码价格为0.1元/个 |
| uptime | 最近活跃时间 | datetime | 该黑卡最近被监控活跃时间 示例“2018-07-10 08:23:14” |
| ctime | 发现时间 | datetime | 该号码首次被发现的时间 |
card_type注释说明：
- 普通卡：常见的普通实体手机卡；
- 虚拟小号：无实体SIM卡的附属手机号，需绑定一张实体SIM卡且实名认证，如阿里小号；
- VoIP网络电话：使用基于IP完成语音传输的网络电话，如Google Voice；
- 拦截卡：被黑产控制用于收发验证码的真实用户手机号。
# 三. 使用建议
针对不同的风险等级及手机卡属性我们梳理成以下分类，并建议客户针对不同类型的手机卡来综合风控系统来关联风控处置方法。
高危号码：risk返回值为”9“ 。
该类号码是我们在近期明确发现其被黑产用来做恶意注册等行为，而非被自然人所持有的号码。该风险标签产生的误判概率极小，在一些场景下可以考虑通过单一策略直接拦截该类请求，出现误判的概率低于万分之一。
中高危号码：risk返回值为”6“。
该类号码数据来源为国内手机号码活跃号段的遍历结果，和永安在线历史捕获疑似黑产使用手机号码，经过检测此类号码属性及行为被判定为异常，存在较大作恶可能。建议综合IP、行为特征等多维度进行判别；或采取柔性阻断策略，例如执行敏感操作需通过图形验证码完成人机识别。
中危号码：risk返回值为”5“。
该类号码是我们曾经发现其参与恶意注册等行为，但近期不活跃的号码。这类号码我们建议客户结合风控系统中标记该类手机号并做相关的阈值管理。
虚拟小号：risk返回值为”2“。
该类号码是明确的虚拟小号号码，是从卡本身的属性上给予定性，客户需要结合自身业务来做综合处置判断。
拦截卡：risk返回值为“0”且card_type 为“3”。
该类号码是被黑产控制的真实用户的手机号，多为海外卡。平台可以进行语音验证码，确认当前操作是否是机主本人完成。