3、能力对接

3.1 交互流程

合作方app：对接方的app，用户通过对接方的app使用移动网络向平台获取网络数据；

天翼账号平台：服务主要提供方，提供手机号码取号服务；

合作方平台：基于安全考虑，手机号码取号服务必须由合作方平台发起；

运营商网关认证平台：协助天翼账号平台向app提供网络数据。

注：红色字体是由合作方去实现的功能

步骤说明：

(1)客户端每次调用接口时都需要生成一个随机的对称加密(例如AES)的秘钥(AES-KEY)，app提前配置好账号平台公钥(RSA-PUBLIC-KEY)；

(2)合作方app采用对称加密方式向天翼账号平台请求，获取授权码，具体详见第一步：从手机端调用获取授权码接口

(3)账号平台最后将返回报文通过AES-KEY加密返回给客户端(双向加密)；

(4)客户端拿到AES-KEY加密的返回报文，通过本地保存的AES-KEY秘钥解密。拿到返回报文明文，提交给合作方平台。

(5)【调用此接口计费】合作方平台调用手机号校验接口(verifyMobile.do)，具体详见第二步合作方平台调用手机号校验接口。

(6)流程结束。

3.2 对接指引

天翼账号开放平台根据合作方不同的应用端场景，提供了通过3种调用方式让合作方从手机端调用获取授权码接口，包括AndroidSDK、iOS SDK以及API调用。其中，SDK方式为合作方实现了WiFi下调用，而API方式则只能在移动数据网络下调用。

3.2.1 通过Android SDK调用

1、根据Android SDK接入指南接入SDK，完成SDK的导入，配置等准备工作。

2、创建对象并调用初始化接口 init

输入参数：参数名参数说明数据类型可空appKey分配给第第三方应用的appKeyStringN

appSecrect分配给第三方应用的appsecrectStringN

3、调用获得用户手机授权码接口getPreCode

输入参数：参数名参数说明数据类型可空bussinessType业务类型，固定填写“jy”StringN

preCodeListener请求结果回调类PreCodeListenerN

输出参数：参数名参数说明数据类型可空accessCode授权码，天翼账号授权码，时效性60sStringN

msg如果result不等于0，会有相应的错误信息提示，用UTF-8编码StringN

operatorTypeCT电信，CU联通，CM移动，UN其他StringN

result操作结果返回码，0 表示操作成功intN

第二个参数preCodeListener类需要实现onSuccess和onFail方法，用于结果回调。

调用示例如下：CtgAuth ctgAuth = CtgAuth.getInstance();

//参数分别为：应用上下文, 平台下发给应用的appKey,平台下发给应用的app密钥

ctgAuth.init(MainActivity.this, APPKEY, APPSECRET);

ctgAuth.getPreCode("jy", new PreCodeListener() {

@Override

public void onSuccess(int result,final String accessCode,String msg,String op){

//获取授权码成功回调

}

@Override

public void onFail() {

//获取授权码失败回调

}

});

注意事项：

1)调用getPreCode方法前，必须先获取CtgAuth单例对象并调用其初始化方法(init)。

2)成功回调结果授权码(accessCode)具有时效性，在60s之内有效。3.2.2 通过iOS SDK调用

iOS SDK调用流程如下

1、根据iOS SDK接入指南接入SDK，完成SDK的导入，配置等准备工作。

2、配置网络权限，EAccountSDK.framework等动态库文件。

3、调用初始化接口：+ (id)initWithSelfKey:(NSString *)appKey

appSecret:(NSString *)appSecrect

appName:(NSString *)appName;

输入参数：参数名参数说明数据类型可空appKey分配给第三方应用的appKeyStringN

appSecrect分配给第三方应用的appsecrectStringN

appName分配给第三方应用的名称StringN

4、调用获取授权码接口：+ (void)preGetMobileAccessCode:(NSString *)bussinessType

completion:(successHandler)completion

failure:(failureHandler)fail;

输入参数：参数名参数说明数据类型可空bussinessType业务类型，固定填写“jy”NSStringN

completion登录成功的回调代码块blockN

failue登录失败的回调,失败有两种情况，根据error.code来判断。blockN

输出参数：参数名参数说明数据类型可空accessCode授权码，天翼账号授权码，时效性60sStringN

msg如果result不等于0，会有相应的错误信息提示，用UTF-8编码StringN

operatorTypeCT电信，CU联通，CM移动，UN其他StringN

result操作结果返回码，0 表示操作成功intN

3.2.3 通过API 调用

除了通过SDK方式进行调用外，合作方还可以通过API直接调用天翼账号平台获取授权码接口，接口调用

详情如下：

接口定义接口名称preGetMobile.do

接口描述调用该接口进行判断，是否可以取号

承载协议HTTP

承载网络公网

请求方式POST

数据格式请求参数以form表单形式提交，返回数据类型为：Json/JsonP

约束

接口URLhttp://open.e.189.cn/openapi/networkauth/preGetMobile.do

公共请求参数说明

平台仅支持以POST提交数据，请求参数个数固定，如下表所述：字段名称描述clientId开发者在注册应用的时候由天翼账号开放平台分发的AppID

clientType设备类型，具体说明参见附录3.4设备类型

format目前仅支持json和jsonp格式

version调用的接口版本号，填v1.5

signsign=HMAC-SHA1(clientId+clientType+format+version+ 请求参数, appSecret)

备注：参数需按照参数名称升序排序后，最后拼接值进行签名。appSecret为应用信息对应的应用密钥，签名加密算法详见

sign生成示例：

第一步：拼装参数String encryValue=clientId+clientType+format+paramKey+paramStr+version

第二步：把相加后的encryValue值使用HMAC-SHA1算法加密：

appSecret是综合平台颁发的应用信息对应的应用密钥

String sign=HMAC-SHA1(encryValue, appSecret);

请求参数：字段标识字段类型长度是否必填字段含义说明paramKeyString1024是密钥的密文密钥的密文，如RSA-1024(密钥A,公钥), 注：密钥A由合作方随机生成，公钥由天翼账号平台分配；加密算法详见

paramStrString1024是非公共请求参数密文非公共请求参数密文(使用密钥A加密，如AES(参数1=值1&参数2=值2，密钥A))，加密算法详见

非公共请求参数

此参数用于加密成paramStr，如paramStr=AES(参数1=值1&参数2=值2，密钥A)，如paramStr=AES(timestamp=12321321521& bussinessType=qh,密钥A)字段标识字段类型长度是否必填字段含义说明modelString50否手机型号

systemString50否手机操作系统

networkTypeString50否移动网络类型2G；3G；4G；other

onlineTypeString20否上网方式0:仅移动数据网，1：wifi加移动数据网，2：仅wifi

callbackString100否使用jsonp格式的回调方法

timeStamplong是时间戳15分钟内有效

operatorTypeString10否手机卡运营商CT电信，CU联通，CM移动，(双卡手机传二个，以英文逗号分割)

bussinessTypeString4是业务类型固定填写“jy”

注：提交给账号平台参数：公共参数+请求参数，需要提交的参数为：clientId、clientType、format、paramKey、paramStr、version、sign

-----------------------------

电信响应参数  密文字段标识字段类型字段含义说明msgString返回信息描述如果result不等于0，会有相应的错误信息提示，用UTF-8编码

resultint操作结果返回码0 表示操作成功(返回信息参照“成功返回结果”)；如result=30002，那么data会返回加密后的多个认证地址，由合作方主动并发请求，以第一个获取成功的状态码为准

dataString数据包的密文，需要使用密钥A来解密，解密算法详见data参数说明  字段标识字段类型字段含义说明accessCodeString授权码/td>天翼账号授权码，时效性60秒

operatorTypeString运营商标识CT电信，CU联通，CM移动，UN其他

成功(result=0)返回结果

Json示例：{

"result": 0,

"data": "a35336711c70456cb883f4f224e9a259"

}

jsonp示例：jQuery16107903810819167506_1484623928047({

"result":"0",

"msg":"认证成功",

"data": "a35336711c70456cb883f4f224e9a259"

})

result为30002时返回结果：data会返回加密后的多个认证地址，由合作方主动并发请求，以第一个获取成功的状态码为准，返回成功的结果如(result=0时的结果一致)

Json示例：{

"result": 30002,

"msg": "redirect other operator",

"data": "a35336711c70456cb883f4f224e9a259"

}

Json示例：jQuery16107903810819167506_1484623928047({

"result": 30002,

"msg": "redirect other operator",

"data": "a35336711c70456cb883f4f224e9a259"

})

data参数的值a35336711c70456cb883f4f224e9a259解密后结果为:{"urls":["http://www.cmpassport.com/openapi/gateway.do?sourceid=157&code=4b964e12df

c133a56b0c7449e0e4d74501b98gt1&msgid=93aa0102d1a3485989320fba798d57f6&notifyUrl=

https://open.e.189.cn/openapi/networkauth/spcallback/cm/callBackMobile.do&timestamp=

20170511150307064","http://mdn.open.wo.cn/net/rnm.do?sequenceNumber=8202000636cc4ff68

3e7bf9bb3176568&apiKey=chinatelecom&sign=abc3bade9ccb04265eb319a75e51e0fc&notifyUrl=ht

tps://open.e.189.cn/api&unikey=4741e8dfac6f46aa8ccc31b91505e4c1&timestamp=1494486187174"]}

--------------------

第二步：合作方平台调用手机号校验接口【调用此接口，按返回状态计费】

在调用预取号接口，结果为认证成功后，第二步是合作方平台调用服务端手机号校验接口，获得校验结果。调用获取手机号码接口需要传入第一步获取的授权码。

接口定义接口名称verifyMobile.do

接口描述调用该接口进行验证手机号是否正确操作

承载协议HTTPS

承载网络公网

请求方式POST

数据格式请求参数以form表单形式提交，返回数据类型为：Json/Jsonp

约束服务端调用,需要提供IP白名单

接口URLhttps://open.e.189.cn/openapi/networkauth/verifyMobile.do

公共请求参数说明字段名称描述clientId开发者在注册应用的时候由天翼账号开放平台分发的AppID

clientType设备类型，具体说明参见附录3.4设备类型

format目前仅支持json和jsonp格式

version调用的接口版本号，填v1.5

signsign=HMAC-SHA1(clientId+clientType+format+version+请求参数, appSecret)备注：参数需按照参数名称升序排序后，最后拼接值进行签名。appSecret为应用信息对应的应用密钥，签名加密算法详见

sign生成示例：

第一步：拼装参数String encryValue=accessCode+callback+clientId+clientType+format+mobile+timeStamp+version

第二步：把相加后的encryValue值使用HMAC-SHA1算法加密：

appSecret是综合平台颁发的应用信息对应的应用密钥

String sign=HMAC-SHA1(encryValue, appSecret);

请求参数字段标识字段类型长度是否必填字段含义说明timeStamplong20是时间戳精确到毫秒

callbackString100否使用jsonp格式的回调方法jsonp方式

accessCodeString256是访问令牌

mobileString64是手机号可以使用MD5或SHA256加密后传输，如mobile加密后，则algorithm必须传MD5或者SHA256；如algorithm为空，则视mobile为明文传输

algorithmString10否号码加密方式只支持MD5和SHA256，明文不需传该参数

电信响应参数字段标识字段类型长度字段含义说明msgString256返回信息描述如果result不等于0，会有相应的错误信息提示，用UTF-8编码

resultint5操作结果返回码0 表示操作成功

isVerifyint4验证结果 0：一致，1：不一致，2：无法判断

openIdString32用户在该应用下统一标识，可以唯一标识一个用户

成功返回结果

Json示例：{

"result": 0,

"msg": "操作成功",

"isVerfiy ": 0,

"openId ": 7823idkdi9didkkda323

}

3.3计费标准

1、合作方平台调用手机号校验接口，成功返回匹配验证结果时(返回匹配或不匹配)计费。

2、按照状态码返回值的情况下计费，详见下表。除此之外的其他状态码值，我们承诺不收取任何费用。

计费口径：verifyMobile.do接口，result=0 且 isVerify=0或1字段标识字段含义说明result操作结果返回码0 表示操作成功

isVerify验证结果

0：一致

1：不一致

2：无法判断0和1：计费

2：不计费

3、具体服务价格可向商务人员咨询。

3.4 demo下载

接口调用Demo：http://id.189.cn/source/files/OpenApiDemo.zip

取号Demo：http://id.189.cn/source/files/GetMobileDemo.zip

免密认证+校验相关资源：http://id.189.cn/api?initialSrc=/html/api_detail_475.html

附录

客户端类型详见 《客户端类型》