兑吧积分商城技术对接文档.docxVIP

1、对接流程 1.1术语定义 开发者：使用兑吧积分商城服务的开发者简称。 积分：开发者与兑吧商城对接使用的“虚拟货币单位”，开发者可以自己更改“货币名称”和“货币汇率”。 汇率：开发者自己平台上的虚拟货币与现实中人民币的大致比率。如：100积分 = 1元 意味着100积分可以兑换1元面值的商品。 服务端：指开发者的服务器，用于接口对接。 客户端：又称用户端，目前支持Android（安卓）、IOS、微信、纯H5方式接入。 自动登录url：又称免登录url，在用户进入兑吧积分商城的时候由服务端实时生成，提供用户的登录信息，包含用户id和积分值。 扣积分接口：用户发起兑换请求后，兑吧会向开发者发一个扣积分的http请求，开发者接收到请求后，需创建订单、扣除用户相应的积分，并响应相应的信息。 通知接口：用户在兑吧兑换成功/失败后，兑吧会向开发者发通知请求，告知订单最终结果，开发者需根据通知结果修改本地订单状态，如果结果为失败，还需要退还用户之前扣除的积分。 开发者账号：开发者在兑吧注册的账号 应用（app）：开发者账号下可以创建多个应用，便于统一账号下管理。 appKey：每个应用都有一个唯一的标识码。 签名：遍历请求参数的值进行MD5编码，比对sign值，确保请求不可伪造。 自有虚拟商品：由开发者自己平台向用户提供充值的商品，如：会员等级，礼品卡，月卡，游戏点数，虚拟货币等。 1.2积分兑换原理说明 用户在使用积分进行兑换时，兑吧如何与开发者共同来实现这一功能呢？ 整体原理图如下： 当用户发起一个兑换请求时，兑吧服务器会先收到这个请求。然后会依次执行下面的步骤： Step1. 向开发者服务器发起扣除用户积分的请求。 兑吧开始启动兑换流程，向服务器发送扣除用户积分的请求。 比如用户兑换话费需要消耗100积分，这个请求中就会带上用户id，以及需要扣除的积分数：100。 开发者需要对这个请求进行响应，比如扣除成功，或者扣除失败，原因是什么。 只有兑吧收到开发 者的扣除积分成功的消息，才会继续兑换流程。 Step2. 兑吧开始进行真实的兑换 Step3. 兑换成功/失败通知 如果兑换成功，兑吧服务器会向开发者服务器发送兑换成功的消息，里面会包含开发者订单号等信息。 如果兑换失败，兑吧服务器也会向开发者服务器发送兑换失败的消息，包含开发者订单号等。如果开发者服务器收到了兑换失败的消息，开发者需要将此次兑换预先扣除的积分返还给用户。 整个兑换过程，开发者需要向兑吧开放2个接口，分别是： 用户积分扣除接口 兑换成功/失败消息的接收接口 整个兑换过程中的请求交互，我们都会进行MD5签名，保证请求的不可伪造，确保资金安全！ 1.3交互流程图 客户端、开发者服务端、兑吧服务端交互流程图： 服务端接入简介 服务端接入 2.1用户登陆积分商城 生成免登录url 原理及说明 兑吧积分商城本质上是一个网页，开发者需要将网页嵌入到App中去。 用户登录兑吧积分商城，需要开发者根据用户信息在服务端生成一个免登录url，通过这个url链接，兑吧才能知道是哪个用户来访问积分商城，并通过credits参数获取用户的积分余额。 为了确保客户端每次请求到都是最新的免登陆url，客户端每次向服务器发的请求不能是固定的，以避免请求被缓存。 兑吧免登录url经过签名，该url地址5分钟失效，请务必在生成地址后立即使用，使用后用户即可进入积分商城，登录状态24小时有效。 开发者服务器端需要通过一个重定向功能实现动态生成免登录url地址。 如果开发者事先生成免登录url地址，将导致5分钟后用户访问该地址过期。 输入参数： 参数是否必须参数类型限制长度参数说明uidyesstring255用户id （用not_login作为uid标记游客用户，详见  HYPERLINK /tech_doc_book/optional/not_login.html 游客访问）creditsyeslong20用户积分余额appKeyyesstring255接口appKey，应用的唯一标识timestampyeslong201970-01-01开始的时间戳，毫秒为单位。redirectnostring255登录成功后的重定向地址，可以直达积分商城内的任意页面（建议为此参数配置一个接口入参，根据传参来灵活修改重定向地址），查看  HYPERLINK /tech_doc_book/optional/direct_reach.html 运营位直达方法signyesstring255MD5签名，详见  HYPERLINK /tech_doc_book/appendix/sign_rule.html 签名规则示例：