一.准备工作

概述

本文是H5本机号校验 v1.0.1版本的接入文档,用于指导WEB应用开发人员接入,并详细描述接入流程和使用方法,默认读者已经具有一定的编程知识基础。

快速体验DEMO

请用手机浏览器上访问链接:http://test.login.253.com/demo/demo.html

创建应用

开发者使用账号登录控制台,进入控制台页面创建应用。然后进入“闪验认证-应用版本”中创建应用版本,填写登录页面地址和域名后提交,等待闪验运营人员审核。开发者可以在应用版本列表中查看当前应用版本的APPID和APPKEY。APPID是闪验的应用标识,APPKEY是闪验的应用秘钥,用作于调用闪验接口时的签名算法秘钥。

二.集成SDK

//在页面中引入闪验WEB-SDK的JS文件:
<script src="./shanyan.min.js"></script>;
//在页面中实例化SDK对象:
var login = new OneKeyLoginManager();

1.调用预签名

//调用SDK方法获取预签名:
var preSign = login.getPreSign();
//将preSign传到客户后台服务中,生签名成sign:

客户后台准备三个参数:

参与签名字段 类型 说明
appId string 闪验应用appId
appKey string 闪验应用appKey
preSign string 闪验SDK返回的pres
timestamp string 服务器当期时间戳(到毫秒)

注:客户后台将参数字段名和字段值一起拼接为字符串使用Hmac-SHA256算法以appKey为   秘钥加密生成签名sign的值。算法伪代码:

var sign = Hmac_SHA256(
  "appId12345678preSignxxxxxxxxxxxxxxxxxxxxtimestamp13511112312312",
  appKey
);

//客户后台返回appId、sign、timestamp三个参数到WEB端。

2.调用初始化

Web端调用WEB-SDK init方法。

login.init({
  appId: yourAppId,
  timestamp: yourTimestamp,
  sign: yourSign,
  // timeout: 5,
  // mobile: 18xxxxxxxxx,
  callback: yourCallback,
});
//appId,timestamp,sign三个都是客户后台返回的参数,非空,字符串类型。
//timeout为超时参数,单位(秒),本方法设置调用运营商接口的超时,可以为空(默认5s) ,数字类型 。
//mobile为用户在页面输入的手机号码,如果前端页面没有输入项,可以为空,用来辅助判断运营商, 字符串类型。
//callback为回调函数,回调函数中会返回运营商token值,非空,函数类型。
//callback示例:
function cb(info) {
  if (1000 === info.code) {
    // 初始化成功,获取token
    var token = info.extra.token;
  } else {
    // 初始化失败逻辑,根据业务需求自行实现
  }
}

获取token后将token和手机号码传入到客户后台,用于调用本机号校验接口,校验此token与手机号码是否匹配。如匹配则表示此号码是当前手机流量卡的手机号码,否则不是当前手机流量卡卡号。

ps:闪验支持手机号隐式校验,所以手机号码可以为用户在前端页面的输入值,也可以为客户后台保存的手机号码。

3.调用本机号校验接口

3.1.协议说明

名称 说明
协议 HTTPS  POST
编码格式 UTF8
返回类型 application/json
URL https://api.253.com/open/flashsdk/mobile-validate-web

3.2.请求参数

注:请求参数Body以application/x-www-form-urlencoded方式提交。

参数名 说明
appId 当前APP对应的appid,非空
token 运营商token, SDK返回,非空
mobile 需校验的手机号码,非空
sign 签名,非空 ,签名算法 hmacSHA256(所有传入参数按字段名排序后拼接的字符串,应用appKey) 后再16进制字符串转换 ,例:hmacSHA256(“appIdxxxxxxmobile11111111111outIdxxxxtokenxxxxxxxxxxxxxxxxx”,”xxxxxxx”)后的值:767123065B9CF379C86789650D10BDBE5D5C45830B79FC02F7DB83C131AD4AA1
outId 客户方流水号,可为空。

3.3.响应内容

注:响应body数据为JSON格式。

字段名 类型 说明
code String 响应code码。200000:成功,其他失败。见附录响应code码
message String 响应code码解释
chargeStatus String 是否收费,枚举值:1 :收费 0:不收费
data Object
data >isVerify String 手机号是否校验通过。值: 1此号码是本机号码 ,  0此号码不是本机号码。
data >tradeNo String 交易流水号

3.4.返回示例

{
  code: "200000",
  chargeStatus: 1,
  message: "成功",
  data: {
    tradeNo: "18112115031414011",
    isVerify: "1",
  },
}

三.本机号校验接口响应code码

状态码 描述
200000 请求成功
400001 参数校验异常
403000 用户校验失败
415000 请求数据转换异常
500000 系统异常
500002 数据处理异常
500003 业务操作失败
500004 远程调用失败
500005 账户余额异常
500006 请求外部系统失败
504000 系统超时
400101 在下游系统中的商户信息不存在
403101 账户被下游系统禁用
403102 账户在下游系统中没有被激活
510101 在下游系统中的用户产品可用数量不足
400102 商户IP地址在下游系统中不合法
400200 黑名单列表
400201 手机号码不能为空
400901 账户信息不存在
400902 应用类型信息不存在
500901 邮箱未设置
500902 账户信息已存在
500903 账户相关能力已激活


 

四.常见问题

1.本机号校验接口错误:appId不能为空
{“message”:“请求非法,appId不能为空”,“code”:“403000”}
问题排查方案:
检查是否传入appId字段。请求数据格式是否正确,本接口不支持发送JSON格式数据。
问题解决方案:
首先,请核对字段名称无误,使用正确的字段名。
其次,请确保请求使用POST方法,参数放到RequestBody中以application/x-www-form-urlencoded或multipart/form-data提交。
 
2.本机号校验接口错误:请求非法,签名验证不通过
{“message”:“请求非法,签名验证不通过”,“code”:“403000”}
问题排查方案:
请确保签名生成方式无误。
问题解决方案:
1、首先确保使用了正确的应用对应的appKey。
2、其次请确保签名方式正确,签名字段的值由客户服务端生成,签名算法hmacSHA256(所有传入参数按字段名排序后拼接的字符串,应用appKey)后再进行16进制字符串转换的值。