• 开发者必读

    • 简介

    本文档旨在向开发者描述入驻触宝开放平台的集成工作,主要包含联合登录、支付、订单回传三个部分,涉及H5 适配和服务器对接两方面,平台向开发者发布 JS-SDK & HTTP-SDK;JS-SDK定义了H5开发接口,提供⼀些native功能,帮助改善H5的用户体验;HTTP-SDK封装了服务端对接的HTTP接口,开发者只需填充业务参数,即可完成向开放平台的请求,得到业务结果;提供python/java/php/c#等版本。

    集成场景

    入驻服务商户集成需要实现两部分功能，一部分是网页前端的逻辑，使用触宝提供的JS SDK实现相关功能，一部分是实现后台接口，可使用触宝提供的服务端SDK进行集成，后台接口为触宝后台和服务商网页的桥梁，服务商后台从网页接收请求，同时会请求到触宝服务器，接入的一个原则是服务商网页和触宝服务器不直接通信。下面以具体场景来介绍。

    场景图

    该场景是从用户角度出发，如涉及具体的前后端结合，请看下面的整体流程项目 服务商需要实现一套服务网页，客户的网页icon是在全部服务里出现（图1），这里以触宝的自有服务话费流量为例，解释相应的流程。

    1. 首先用户进入到充值里（图3），输入号码进行充值
    2. 前端调用JS SDK，可判断是否已经登陆，若未登陆，调用js方法弹出登录框（图2），其中判断登陆的时机，可由服务商自行决定，建议后置到必须登陆的时机再判断
    3. 如点击了充值按钮。已登录则调用支付方法，弹出收银台页面（图4），这里支持了支付宝和微信，该页面是触宝提供的，无需服务商实现
    4. 用户点击支付，弹出支付宝或微信（图5），用户支付完成后，购买成功，服务商后续则提供服务。

    平台规约

    • 正式服务地址: open.cootekservice.com；

    • js-sdk地址: http://open.cootekservice.com/res/js/lib/ctk-1.0.0.js；

    • 文中描述的网络交互都暂时使用HTTP传输,后续会改为HTTPS；

    • 采用POST方法提交；

    • 提交和返回的数据格式均为JSON格式；

    • 文中描述的字符编码方式统一使用UTF-8编码；

    • 所有请求均要求签名，签名类型由signType指定，目前仅支持MD5和RSA；支付及退款类请求采用RSA签名，其他请求采用MD5签名；

    • 签名包含访问时间戳，防止回放攻击；

    • 时间使用标准北京时间，时区为东八区,格式为:yyyyMMddHHmmss；

    • 时间戳使用UTC时间，自1970年1月1日 0点0分0秒以来的秒数(10位数字)；

    • 交易金额默认为人民币交易，接口中参数支付金额单位为分，整数；

    名词解释

    必要字段

    • appkey:开发者的身份标识，是一个以7168开头的16位数字串，由平台发放，用于标识该服务商；

    • appsecret:与appkey匹配的秘钥，由平台随appkey一并发放的32位字符串，用于签名；

    • sellerid:标识开发者支付账户的唯一标识符， 用于支付类相关接口及财务结算、对账等；

    • sign:开发者和平台根据相同的密钥(RSA为各自私钥)和算法生成一个结果，用于校验双方身份合法性；

    • identifier:服务的全局唯一标识符，字符集限制为字母数字下划线，由服务提供商申请,格式为com.公司名.产品名，如com.company.product

    整体流程

    服务开发层次

    服务的层次结构图如下： 层次图

    服务商需要实现的主要有前端网页层，和数据接口层，需要实现的功能包含三点：

    联合登陆

    账号系统做到了账号互通，账号互通的最大收益，是可以让用户一键授权，避免重复登录，提高服务的转化率；如果服务商需要用户的详细信息，黄页平台也开放了API供服务商查询。原则上不允许服务商内网页出现二次登陆的界面，联合登陆的流程如下：

    1. 用户点击需要登陆的项目
    2. 网页调用ctk.logged判断用户是否登陆(具体js sdk接口见下方js sdk文档)
    3. 如未登录，调用ctk.login唤起登录框；如已登录，则用logged接口拿到的accessToken请求服务商实现的获取用户信息的接口，这里假定为http://test.com/user
    4. 服务商user接口收到请求，则可拿到js请求的accessToken，向触宝的接口/user/profile，去请求用户的手机号和userId
    5. 服务商后台收到触宝的返回，经过一些流程处理（如新建用户等）再返回给前端相应信息。

    支付打通

    黄页平台为服务提供商提供了一致的支付体验，目前可供支付的方式有微信和支付宝，平台集成了微信和支付宝的本地SDK，使支付体验统一、流畅，一定程度提高支付转化率。服务商在付款环节调起触宝提供的收银台页面，使得在触宝电话内的体验更加一致，需要说明的是，用户所付款项是流入了触宝的账户中，触宝再定期与服务商做结算， 支付大致分为以下几个环节：

    1. 调用JS接口select()，供用户选择支付方式得到tradeStr;
    2. 根据订单信息和tradeStr访问创建支付订单接口得到payStr;
    3. 调用JS接口pay(payStr);
    4. 服务器异步通知支付结果;

    支付逻辑的时序图如下： 时序图

    订单回传

    订单回传涉及到财务结算和通知用户，需要注意以下几点:

    1. 用户的订单都需要推送给黄页平台，包含未支付的订单或无需支付的订单;
    2. 订单任何一个关键状态的变化，都需要推送给黄页平台;
    3. 推送必须要有重试机制;
    4. 部分订单推送内容会被转化为模板消息通过服务号推送给用户;

    接入指南

    前期资料

    个人开发者所需的appkey、secret、sellerid、商户私钥需要向我司申请(联系邮箱:Life-bd@cootek.cn)，公司接入请确认上述资料已经通过邮件收到. 开发包 点此下载.

    内含：

    1. 平台公钥，包括正式和测试
    2. server-sdk，支持python/php/c#/java
    3. cootek_test_apk，支持在测试服务器上进行调试

    注意事项

    后台地址：
    正式：http://open.cootekservice.com
    测试：http://test.open.cootekservice.com:15080

    platform_publickey:
    开放平台发放的开发者信息; 该目录下的public key是平台公钥，用于response验签，均为测试环境使用，正式环境会通过邮件正式发布。 请向生活服务平台索取appkey, appsecret, sellerId, privateKey等开发者相关信息。

    test_apk:
    一个展示JS-SDK调用方式的样例页面，该页面需运行在触宝电话的app中(见cootek_open_test_v5xxx.apk);
    若使用测试网址后台对接，则也需要使用测试APK进行测试
    测试自定义网页入口在搜索栏下方的banner里”输入网址戳这里“字样，点击即可进入，(如图1)
    进入页面之后有输入框，输入网址之后点击按钮即可进入到输入的网址，(如图2)，注意，需要输入http://开头，不然会404
    进入js前端demo页，点击”JS Demo网页戳这里“进入（如图3）
    如图4，为js-demo页，里面有所有的js-sdk调用接口的例子，网址为http://test.open.cootekservice.com:15088/,在浏览器输入查看源码

    时序图

    正式地址测试入口：
    到电子市场下载android版本的"触宝电话"，下拉搜索输入"::95277259::"(不包括引号)，可以看到"服务后门"，点击进入可填写自己的服务地址进行线上测试。流程如下图:

    houmen图 注：ios版本需要点两次搜索键

    注意！！！：
    正式地址和测试地址的开发者信息不可混用
    测试地址和正式地址，使用的demo APK不可混用，否则会出现user not exist，支付不了等问题。

    技术QQ群：271141319

    更新日志

    2015-09-30版本1.0

    2016-01-20版本1.1

    1. trade/create接口增加accessToken请求字段
    2. 移除/order/query接口；
    3. /order/push接口新增attach字段，用于扩展订单信息，另更新部分字段名称；

    上海触宝信息技术有限公司（触宝科技）版权所有 ©2012 沪ICP备12012934号-1