概况

• 概况
• 更新日志

概况

燃豆科技是一家用户积分运营解决方案提供商，公司专注于精细化、趣味化用户运营Saas平台的搭建，致力于为互联网企业、消费品牌提供精细化趣味化的积分运营产品服务，助力企业积分用户运营效果与效率的全面提升。

燃豆积分俱乐部为燃豆科技旗下产品之一。企业可通过简单的API接口对接，即可搭建一个与自身用户体系打通的、用户端体验优质的积分商城，并且可以通过各种高频趣味化互动玩法，帮助企业高效消耗用户积分的同时同步提升用户活跃与留存；通过精细用户标签系统精准投放运营策略，帮助企业稳步转化用户，精准控制预算。

本文档主要描述与燃豆积分俱乐部对接时需要的API的说明。

产品说明

产品说明请查看燃豆官网和燃豆后台操作手册

扫码试用

对接联系方式

对接过程中如有问题，可以添加燃豆技术支持人员微信咨询调试

更新日志

JAVA

2022-11-10 Version: 1.0.0

• First Release.

2023-02-01 Version: 1.1.0

• 新增抽奖活动类型.

2023-08-16 Version: 1.1.1

• 预扣积分事件中新增连连看小游戏类型.
• 类型为兑换的预扣积分事件新增商品编号字段
• bug修复

2023-09-08 Version: 1.1.2

• 预扣积分事件中，如果是直充商品的兑换添加充值账号字段

2023-10-25 Version: 1.2.0

• 新增订单相关接口
• bug修复

2024-01-10 Version: 1.3.0

• 新增开发者自有直冲类商品对接相关接口
• 新增积分明细对接相关接口

2024-01-26 Version: 1.3.1

• 新增沙箱环境支持

2024-03-05 Version: 1.3.2

• 新增抽奖结果的推送

2024-08-20 Version: 1.3.3

• 新增部分返回字段

2024-12-06 Version: 1.4.0

• 新增事件解析通用方案
• bug修复

PHP

2022-11-10 Version: 1.0.0

• First Release.

2023-02-01 Version: 1.1.0

• 新增抽奖活动类型.

2023-08-16 Version: 1.1.1

• 预扣积分事件中新增连连看小游戏类型.
• 类型为兑换的预扣积分事件新增商品编号字段
• bug修复

2023-09-08 Version: 1.1.2

• 预扣积分事件中，如果是直充商品的兑换添加充值账号字段

2023-10-25 Version: 1.2.0

• 新增订单相关接口
• bug修复

2024-01-10 Version: 1.3.0

• 新增开发者自有直冲类商品对接相关接口
• 新增积分明细对接相关接口

2024-01-26 Version: 1.3.1

• 新增沙箱环境支持

2024-03-05 Version: 1.3.2

• 新增抽奖结果的推送

开发前必读

• 开发前准备
• 对接模式
• 返回值说明
• 术语定义
• 调用方式
• 沙箱环境

开发前准备

注册燃豆账号

具体步骤请查看燃豆操作手册

创建团队及项目

具体步骤请查看燃豆操作手册

获取APPID及APPSECRET

具体步骤请查看燃豆操作手册

对接模式

燃豆积分俱乐部前端所有页面由h5开发，并打通了微信支付和支付宝支付两种支付方式，目前支持嵌入在APP客户端、微信公众号、手机网站中，开发者可根据自身情况选择接入方式

数据对接

用户对接

用户进入积分俱乐部页面，都需要开发者对接燃豆提供的免登接口，把用户id和相关信息发送给燃豆，燃豆返回可以自动登录的地址

积分对接

目前积分对接支持以下两种对接方式

1. 开发者自有积分

适用于开发者已经有自己的积分体系，此时需要开发者在调用免登接口时把用户的当前积分数量一起传给燃豆，同时也需要开发者对接积分相关接口

2. 平台托管积分

适用于当前没有自己的积分体系，由燃豆代为管理用户在积分俱乐部中的积分，此时积分数量存储在燃豆服务端，开发者不需要对接积分相关接口

接入方式

微信公众号（不支持支付宝支付）

即使用微信内置浏览器来打开积分俱乐部，开发者可将积分俱乐部入口（即开发者自己的免登接口）配置在微信公众号中，当用户点击时重定向到积分俱乐部的对应页面

APP接入

开发者可通过在自身APP的webView中打开积分俱乐部的页面，此种方式接入的开发者请注意以下几点：

1. 开发者的webView需要支持自定义scheme跳转协议，支付过程中可能会用到weixin，alipay等自定义协议来拉起第三方app；
2. 项目上线前请务必测试一遍所有页面，重点关注页面兼容性问题；

手机网站

同微信公众号，把积分俱乐部入口放在自己的网站中

微信小程序

需做相应适配，具体请联系燃豆客服

返回值说明

开发者在调用燃豆提供的接口时，可能获得正确或错误的返回码，企业可以根据返回信息调试接口，排查错误。

返回格式

燃豆所有接口返回值均以utf-8编码的json格式返回，返回值格式如下：

请求成功（http返回码为200）示例

{
    xxx: "yyy",   // 开发者所需要的数据，详情请查看各接口的成功返回值说明
    aaa: "bbb"
}

请求失败（http返回码非200）示例

所有失败的请求均以以下方式返回

{
    code: 100002,
    error: "MALL DOES NOT EXIST",
}

返回值判断逻辑

1. 先判断http返回码，200表示成功，其他均为失败；
2. 解析body，获取失败信息或者成功数据；

全局错误返回码说明

术语定义

appid

每个企业只要创建了团队，都拥有appid，代表该企业的唯一编号，获取该appid可在燃豆管理后台“团队中心”--“更多配置”--“团队AppID”中查看

appsecret

appsecret是企业应用里面用于保障数据安全的“钥匙”，结合appid一起使用，一个appsecret对应唯一一个appid，为了数据的安全，请务必妥善保管好appsecret，切勿外泄，appsecret用来生成接口签名，签名加密方式请查看签名机制

mall_no

开发者团队下的唯一项目编号，有几个项目就有几个mall_no，获取mall_no可在对应项目的“项目概况”中查看

http返回码

即HTTP 响应状态码，关于该码的说明请查看

调用规则

开发者在接入燃豆API时，必须遵循以下规则：

公共参数

参数说明

以下公共请求参数为开发者在调用燃豆API或燃豆调用开发者API时必须携带。

签名机制

步骤说明

1. 第一步：构建签名字符串

对所有参数进行排序，设所有发送或者接收到的数据为集合M，将集合M内全部参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串sorted_string。

举例： 假设需要传递的参数如下：

 appid：           99GUgRcFoWPoOH1fM2o0a0Z2
 mall_no：         JF_002
 uid：             guest
 timestamp：       1650448542
 nonce_str：       3jkdh978K87sjd

此时，sorted_string即为：

 sorted_string = "appid=99GUgRcFoWPoOH1fM2o0a0Z2&mall_no=JF_002&uid=guest&timestamp=1650448542&nonce_str=3jkdh978K87sjd";

2. 第二步：拼接appsecret

把第一步中的排序字符串拼接上密钥后加密

举例 假设appsecret为：

 oUBelo1nuJ22aiDwIYdKHHze

即最后待加密的字符串即

 open_string = sorted_string + "&app_secret=oUBelo1nuJ22aiDwIYdKHHze"

3. 第三步：生成加密字符串

使用MD5加密上述明文字符串，并把该密文为value，sign作为key添加到传递的参数中

举例

 encrypt_sign = MD5(open_string)

即最终传递的参数列表如下

   appid：       99GUgRcFoWPoOH1fM2o0a0Z2
   mall_no：     JF_002
   uid：         guest
   timestamp：   1650448542
   nonce_str：   3jkdh978K87sjd
   sign：        encrypt_sign // encrypt_sign请用上述结果替代

注意事项

• 参数名ASCII码从小到大排序（字典序）；
• 参数名区分大小写；
• 传送的sign参数不参与签名。

SDK

为了帮助开发者调用接口和接收事件通知，我们提供了JAVA、PHP开发语言服务端SDK，封装了签名&验签、数据解析、HTTP接口请求等基础功能。 详见下载和各接口中的demo。

其他开发语言的SDK正在陆续开发中，敬请期待…………

关于沙箱环境

使用场景说明

沙箱环境用于开发者在开发调试时候使用，在公司内部也可供测试人员测试自身服务时候配合使用。

沙箱环境数据和生产环境完全隔离，开发者及测试人员可放心操作。

开发者可联系客服提供手机号，客服会在沙箱环境中根据该手机号创建测试账号。

创建完后，开发者可登录沙箱环境（查看）操作各类功能。

沙箱环境注意事项

1. 沙箱环境提供的商品均为测试商品，不会真实发货，仅用于同燃豆系统的开始联调使用；
2. 燃豆实物商品订单会在订单状态变更为待发货后的15分钟内由系统自动模拟发货；
3. 所有需要手机验证码的地方会直接提示验证码，不会真实发送；
4. 商城、自有商品、会员等级等数据请开发者自行创建，系统已默认提供100W虚拟资金用于调试开发；
5. 请勿在沙箱环境填写真实信息，避免导致隐私数据泄露；
6. 沙箱环境无法邀请用户；
7. 沙箱环境暂不支持通过积分+钱的方式进行兑换；

沙箱环境初始数据

1. 客服创建账号后会同时默认创建团队；
2. 团队默认已充值100W初始虚拟资金；
3. 沙箱环境中已有部分用于测试的燃豆商品（商品为测试商品，不会真实发货）；
4. 公司经营数据已默认填写。

最简化商城发布流程参考

1. 创建商城：基础版或精细版可根据自身需要选择并订购；
2. 进入【团队中心】--【更多配置】--【团队APPID】，获取appid和appsecret;
3. 进入【商城】--【系统配置】--【用户积分系统配置】，选择项目积分来源后保存；
4. 进入【商城】--【系统配置】--【API接口配置】，填写接口地址后保存；
5. 进入【商城】--【页面与装修】--【首页】--【装修页面】，在装修页面右上角点击发布；

发布后即可使用免登接口获取商城的可登录地址，其他功能请参考【燃豆使用手册】

对接接口说明

1. 查看对接接口说明前，建议先查看开发前必读
2. 对应接口请在“项目概况”--“项目配置”--“API接口配置”处填写，详情请点击

• 免登接口
• 积分预扣事件
• 订单结果通知事件
• 添加积分事件
• 订单相关接口
  • 订单审核接口
  • 自有实物商品发货接口
  • 订单取消发货接口
• 自有商品充值
  • 充值事件
  • 充值查询事件

免登接口

接口提供方

该接口由燃豆开放给开发者

使用场景

用户在打开积分俱乐部前需要通过燃豆的登录鉴权，该鉴权操作需要开发者在自己的服务端完成

业务流程说明

1. 用户在开发者的客户端点击积分俱乐部入口按钮请求（该地址由开发者自行配置，且该地址为开发者自己的接口）；
2. 开发者服务端在接收到用户要求打开积分俱乐部接口时向燃豆发送请求获取积分俱乐部地址，并携带必要信息，如用户标志（必须唯一）、需要打开的积分俱乐部编号、用户当前剩余积分等；
3. 燃豆在接收到开发者服务端获取免登地址的请求后记录下相关用户信息，并把登录地址返回给开发者服务端；
4. 开发者服务端在接收到免登地址后给用户重定向（302）到积分俱乐部的页面或把地址给到客户端，由客户端本地打开该地址；

参数说明

注意事项

1. 请注意燃豆积分商城网页地址无法直接打开（游客登录也不行），必须通过免登接口获取登录地址的方式来获取可使用的地址；
2. 如需跳转到积分商城中的指定页，请使用该接口中redirect参数来实现。

返回值示例

正确返回值（http返回码为200）

{
    url: ""   // 即需要重定向的地址
}

错误返回值（http返回码为非200）

{
    code: 100001,
    error: ""
}

代码示例

PHP

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;

$appid = 'aaaaaaaaaaaaaaaaaaaaaaaa';
$appsecret = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';
$params = [
    'uid'     => $uid,
    'mall_no' => 'JF_001',
    'credits' => 11111,
    'grade'   => 2,
];

try {
    $client = RdClientBuilder::getClient($appid, $appSecret);
    // 切换到沙箱环境
    // $client->setDebug(true);

    $result = $client->fetchMallDst($params)->getDataSet();
} catch (RdException $e) {
    print_r($e);
    return;
}

return redirect()->away($result['url']);

JAVA

import com.randou_tech.model.FreeLogin;
import com.randou_tech.request.FreeLoginDstRequest;
import com.randou_tech.result.Result;

String appid = "aaaaaaaaaaaaaaaaaaaaaaaa";
String appsecret = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

FreeLoginDstRequest request = new FreeLoginDstRequest();
request.setUid("aaaaaaa").setMallNo("JF_001").setCredits(24999).setGrade(2).setRedirect("/");
RdClient rdClient =  ClientBuilder.build(appid, appsecret);

// 切换到沙箱环境
// rdClient.setDebug(true);

try {
    Result<FreeLogin> hr = rdClient.getFreeLoginDstRequest(request);

    if (hr.isSuc()) {
        System.out.println(hr.getData().getDst()); // 打印可登录的目标地址
    } else {
        System.out.println(hr.getError());
    }
} catch (RdException e) {
    e.printStackTrace();
}

积分预扣事件

接口提供方

该接口需要由开发者提供给燃豆

接口说明

如果积分俱乐部使用的是自有积分体系，则该接口必须配置，查看自有积分和平台积分的区别

使用场景

用户在积分俱乐部消耗积分时使用，如兑换商品等。

业务流程说明(以商品兑换为例)

该接口需要配合积分预扣结果通知一起使用。

1. 用户在燃豆积分俱乐部中发起商品兑换请求；
2. 燃豆服务端生成该笔兑换订单，并同时请求该接口来预扣开发者服务端的用户积分，并把该订单信息（包含一个唯一订单号）一起推送给开发者；
3. 开发者在收到请求后务必保存好该笔订单的订单号，且扣除或冻结相应的积分数量，并给燃豆返回已处理成功的消息，同时一起返回由开发者自行生成的唯一订单号；如果开发者返回失败信息，则用户兑换失败，订单取消，本次兑换流程结束，燃豆不会再发送该笔订单的结果通知；
4. 如果该接口返回处理成功，在订单结果出来后（发货后或中途取消），燃豆服务端会通过积分预扣异步通知接口把该笔订单的结果推送给开发者;
5. 开发者在收到结果后需要做出对应的处理，比如订单最终失败，需要把已扣除或冻结的积分返还给用户;

参数说明

该接口除了公共必传参数外，还包括以下参数：

redeem_detail参数说明

drawinggame_detail参数说明

linkgame_detail参数说明

返回结果

开发者需以json格式返回响应内容，且不论成功失败，http响应码必须为200，返回码非200的情况下燃豆会认为本次请求失败，并告知用户兑换失败：

json对象中的响应参数说明

返回示例

• 如果本次积分预扣成功，请返回如下格式的内容：

{
  status: "success",
  message: "",
  bizNo: "2021091533333"  // 由开发者自行生成的本地订单号
}

• 如果预扣失败，请返回如下格式的内容：

{
  status: "fail",
  message: "失败原因", //燃豆会把该失败原因显示给用户
}

注意事项

1. 由于网络和系统存在不确定性，有可能存在接口调用超时或失败的情况，燃豆在调用该接口时，设置了超时时间为5s，如果接口响应时间超过了5s，燃豆会认为该次调用失败，并且终止整个流程；如果此时开发者已经扣除或冻结了用户的积分，此时需要把这些积分返回给用户；
2. 当预扣积分失败时，用户兑换失败订单取消，此时由于预扣积分失败，该类情况不会发起后续通知事件；
3. 如果预扣积分成功，开发者需要返回由开发者自行生成的该笔订单的订单号，请确保唯一性，后续通知接口中会把该订单号原样返回，开发者可使用该订单来查找自己本地的订单;
4. 若预扣成功，请务必确保返回值中bizNo全局唯一，不仅只是兑换业务中唯一，所有预扣相关的业务都必须确保返回的bizNo唯一。

代码示例

PHP

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;


$appid = 'aaaaaaaaaaaaaaaaaaaaaaaa';
$appsecret = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';

// 获取全部请求数据
$params = $request->all();

try {
    $client = RdClientBuilder::getClient($appid, $appSecret);

//    校验并且提取订单数据
    $event = $client->withHolding($params);
} catch (RdException $e) {
  print_r($e);
  
//    校验失败，返回认证错误
    return response()->json([
        'status'  => 'fail',
        'message' => '出错了',
    ], 400);
}

// 获取订单全部数据,处理自身业务逻辑
$data = $event->all();
save($data);

//    成功样例
return response()->json([
    'status'  => 'success',
    'message' => '',
    'bizNo'   => sprintf("No%s", time() . ''),
]);

JAVA

import com.randou_tech.ClientBuilder;
import com.randou_tech.RdClient;
import com.randou_tech.RdException;
import com.randou_tech.event.WithHoldingEvent;
import javax.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.RequestMapping;

@RequestMapping("/withholding")
public Map<String, String> withHolding(HttpServletRequest request) {
    String appid = "aaaaaaaaaaaaaaaaaaaaaaaa";
    String appsecret = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

    RdClient client = ClientBuilder.build(appid, appsecret);
    Map<String, String> map = new HashMap<>();
    try {
        // 解析数据
        WithHoldingEvent event = client.withHolding(request);

        // 如果项目中没有javax.servlet.http.HttpServletRequest，可从request中自行获取出全部参数，以下为从jakarta.servlet.http.HttpServletRequest对象中获取参数
        // Enumeration<String> parameterNames = request.getParameterNames();
        // Map<String, String> params = new HashMap<>();
        // // 遍历参数名并获取对应的值
        // while (parameterNames.hasMoreElements()) {
        //     String paramName = parameterNames.nextElement();
        //     String paramValue = request.getParameter(paramName); // 只取第一个值
        //     params.put(paramName, paramValue);
        // }
        // WithHoldingEvent event = client.withHoldingWithParams(params);

        System.out.println(event.toString());

        // 处理开发者本地的预扣积分逻辑
        todo();

        // 处理成功后
        map.put("status", "success");
        map.put("message", "");
        map.put("bizNo", String.valueOf((System.currentTimeMillis() / 1000L)));
    } catch (RdException e) {
        map.put("status", "fail");
        map.put("message", e.getErrorMessage());
    }
    
    return map;
}

订单结果通知事件

接口提供方

该接口需要由开发者提供给燃豆

接口说明

如果积分俱乐部使用的是自有积分体系，则该接口必须配置，查看自有积分和平台积分的区别

使用场景

使用场景请参考积分预扣接口

业务流程说明

业务流程请参考积分预扣接口流程

参数说明

该接口除了公共必传参数外，还包括以下参数：

返回结果

开发者服务端在接收到请求后需要对结果做相应的处理，如订单失败需要把预扣的积分返回给用户。 在收到接口通知后，开发者需要以HTTP响应码为200且body为“success”纯文本字符串（不包含引号）给燃豆，表示已正确处理了该通知，其他返回均视作失败，如果失败燃豆服务端会发起重试，重试逻辑如下;

重试逻辑

由于网络和系统存在不确定性，有可能存在接口调用超时或失败的情况或者开发者没有正确返回等原因，燃豆会对接口进行重试处理，在调用该接口时，设置了超时时间为10s，如果接口响应时间超过了10s，燃豆会认为该次调用失败，此时燃豆发起重试逻辑，直到开发者接口正常返回200和“success”，调用时间间隔分别为1m，5m，60m，3h，10h共5次（即一笔订单开发者在极端情况下有可能最多会收到6次通知请求），如果这5次重试全部失败，燃豆会标记该笔订单为异常订单，此时需要开发者在燃豆后台手工进行处理；

注意事项

1. 由于接口有可能重复调用，因此开发者必须做好去重的逻辑处理，确保接口的幂等性，建议根据orderNo来做去重判断，切勿对本地数据做重复处理；
2. 由于订单可能涉及到付款、人工审核、人工发货等流程，因此该接口通知和预扣积分接口有可能有比较长的时间差；
3. 对于优惠券等不需要人工审核审核或发货的兑换流程，积分预扣接口和预扣结果通知接口也有可能时间差很小，开发者需要做好相应处理。

代码示例

PHP

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;


$appid = 'aaaaaaaaaaaaaaaaaaaaaaaa';
$appsecret = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';

$params = $request->all();
try {
    $client = RdClientBuilder::getClient($appid, $appSecret);
    $event = $client->creditsNotify($params);
} catch (RdException $e) {
    print_r($e);

    return response('fail', 400);
}

//        获取通知全部数据
$data = $event->all();
save($data);

return response('success', 200);

JAVA

import com.randou_tech.ClientBuilder;
import com.randou_tech.RdClient;
import com.randou_tech.RdException;
import com.randou_tech.event.CreditsNotifyEvent;
import javax.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.RequestMapping;



@RequestMapping("/notify")
public String notify(HttpServletRequest request) {
    String appid = "aaaaaaaaaaaaaaaaaaaaaaaa";
    String appsecret = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

    RdClient client = ClientBuilder.build(appid, appsecret);

    try {
        // 解析数据
        CreditsNotifyEvent event = client.creditsNotify(request);

        // 如果项目中没有javax.servlet.http.HttpServletRequest，可从request中自行获取出全部参数，以下为从jakarta.servlet.http.HttpServletRequest对象中获取参数
        // Enumeration<String> parameterNames = request.getParameterNames();
        // Map<String, String> params = new HashMap<>();
        // // 遍历参数名并获取对应的值
        // while (parameterNames.hasMoreElements()) {
        //     String paramName = parameterNames.nextElement();
        //     String paramValue = request.getParameter(paramName); // 只取第一个值
        //     params.put(paramName, paramValue);
        // }
        // CreditsNotifyEvent event = client.creditsNotifyWithParams(params);

        System.out.println(event.toString());

        // 处理本地业务
        todo();

        // 返回成功
        return "success";
    } catch (RdException e) {
        // e.printStackTrace();
        return "fail";
    }
}

添加积分事件

接口提供方

该接口需要由开发者提供给燃豆

接口说明

如果积分俱乐部使用的是自有积分体系，且开放了可能增加积分的相关营销活动（如签到等），则该接口必须配置，查看自有积分和平台积分的区别

使用场景

用户在积分俱乐部参与活动并获得新积分时使用，如参与签到活动，参与抽奖活动获得积分等。

业务流程说明

1. 用户在燃豆积分俱乐部中参与活动获得新积分；
2. 燃豆服务端生成该笔参与订单，同时通过该接口来发起新增用户积分的请求，并把该订单信息（包含一个唯一订单号）一起推送给开发者；
3. 开发者在收到请求后务必保存好该笔订单的订单号，增加积分给用户，并给燃豆返回已处理成功的消息；如果开发者返回失败信息，则用户参与失败，本次流程结束；

参数说明

该接口除了公共必传参数外，还包括以下参数：

返回结果

开发者需以json格式返回响应内容，且不论在业务层面成功失败，http响应码必须为200，返回码非200的情况下燃豆会认为本次请求失败，如果新增积分允许，开发者需要返回一个该业务下唯一的订单编号：

json对象中的响应参数说明

响应示例

• 如果本次积分添加成功，请返回如下格式的内容：

{
  status: "success",
  bizNo: "2021091533333",  // 由开发者生成的唯一编号，
  message: "",
}

• 如果添加失败，请返回如下格式的内容：

{
  status: "fail",
  message: "失败原因", //燃豆会把该失败原因显示给用户
}

注意事项

1. 由于网络和系统存在不确定性，有可能存在接口调用超时或失败的情况，燃豆在调用该接口时，设置了超时时间为5s，如果接口响应时间超过了5s，燃豆会认为该次调用失败，并且终止整个流程；如果此时开发者已经新增了用户的积分，此时需要把这些积分扣除；
2. 无论本次增加积分业务是否成功，开发者都需要返回http状态码为200，否则燃豆会认为该次请求失败，直接提示给用户参与失败的相关信息；
3. bizID参数必须在该业务场景下唯一；

代码示例

PHP

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;


$appid = 'q666WPW01AuTODbuCwYtANI8';
$appsecret = '1GT2G55YXixxxWHz1oxCFp9NmO3339';

// 获取全部请求数据
$params = $request->all();

try {
    $client = RdClientBuilder::getClient($appid, $appSecret);
//    校验并且提取订单数据
    $event = $client->creditsIssue($params);
} catch (RdException $e) {
    print_r($e);
    
//    校验失败，返回错误
    return response()->json([
        'status'  => 'fail',
        'message' => '出错了',
    ], 401);
}

// 获取订单全部数据,并处理自身业务逻辑
$data = $event->all();
save($data);

// 允许参加本次活动,且返回增加积分的bizNo
return response()->json([
    'status'  => 'success',
    'message' => '',
    'bizNo'   => sprintf("No%s", time() . ''),
]);

JAVA

import com.randou_tech.ClientBuilder;
import com.randou_tech.RdClient;
import com.randou_tech.RdException;
import com.randou_tech.event.CreditsIssueEvent;
import javax.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.RequestMapping;

@RequestMapping("/issue")
public Map<String, String> creditsIssue(HttpServletRequest request) {
    String appid = "aaaaaaaaaaaaaaaaaaaaaaaa";
    String appsecret = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

    RdClient client = ClientBuilder.build(appid, appsecret);
    Map<String, String> map = new HashMap<>();

    try {
        // 解析数据
        CreditsIssueEvent event = client.creditsIssue(request);

        // 如果项目中没有javax.servlet.http.HttpServletRequest，可从request中自行获取出全部参数，以下为从jakarta.servlet.http.HttpServletRequest对象中获取参数
        // Enumeration<String> parameterNames = request.getParameterNames();
        // Map<String, String> params = new HashMap<>();
        // // 遍历参数名并获取对应的值
        // while (parameterNames.hasMoreElements()) {
        //     String paramName = parameterNames.nextElement();
        //     String paramValue = request.getParameter(paramName); // 只取第一个值
        //     params.put(paramName, paramValue);
        // }
        // CreditsIssueEvent event = client.creditsIssueWithParams(params);

        System.out.println(event);

        // 处理本地业务
        todo()

        map.put("status", "success");
        map.put("message", "");
        map.put("bizNo", String.valueOf((System.currentTimeMillis() / 1000L))); // 本地唯一订单号
    } catch (RdException e) {
        map.put("status", "fail");
        map.put("message", e.getErrorMessage());
    }

    return map;
}

订单相关接口

为方便开发者实现将燃豆中的订单与自己原有后台系统打通，燃豆提供了以下3个接口用于实现该类业务场景：

1. 订单审核
2. 实物订单发货
3. 取消发货

订单审核接口

接口提供方

该接口由燃豆提供给开发者

接口说明

该接口用于审核在燃豆积分商城中产生且需要人工审核的订单，开发者可将该接口集成到自己的系统中实现兑换订单的审核。

使用场景

1. 当用户在燃豆积分商城中发起兑换操作时；
2. 燃豆服务端会发起积分预扣请求到开发者服务端，该请求中包含了need_review字段用于标记该笔兑换订单是否需要人工审核；
3. 开发者可使用该接口对需要人工审核的订单发起审核操作，包括审核通过和审核不通过。

参数说明

该接口除了公共必传参数外，还包括以下参数：

审核不通过的原因

响应示例

正确返回值（http返回码为200）

{
    orderNo: "T575276639039344640",   // 由燃豆生成的兑换订单号
    bizNo: "xxxxxxxxxxxxx"   // 由开发者生成的订单号
}

错误返回值示例（http返回码为非200）

{
    code: 100101,
    error: "WRONG STAGE"
}

注意事项

1. 该接口只能用于当前待审核的订单，订单审核事项介绍，请查看《燃豆产品文档》；
2. 审核操作无法撤销，请谨慎审核；
3. 如发货成功后需要修改快递信息，可前往开发者后台找到对应订单进行修改。

代码示例

PHP

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;
use Randou\OrderReviewConstants;


$appid = 'aaaaaaaaaaaaaaaaaaaaaaaa';
$appsecret = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';

// 审核通过参数示例
$pass_params = [
    'orderNo' => 'T575276639039344640',
    'bizNo'   => 'xxxxxxxxxxxxx',
    'pass'    => OrderReviewConstants::PASS,
];

// 审核不通过参数示例
$unpass_params = [
    'orderNo'        => 'T575276639039344640',
    'bizNo'          => 'xxxxxxxxxxxxx',
    'pass'           => OrderReviewConstants::UNPASS,
    'reason_type'    => 2,
    'reason_detail'  => '这里是审核不通过的文字描述'
    'reason_display' => 1,
];


try {
    $client = RdClientBuilder::getClient($appid, $appSecret);
    // 切换到沙箱环境
    // $client->setDebug(true);
    
    $result = $client->review($pass_params)->getDataSet();
} catch (RdException $e) {
    print_r($e);
}

JAVA

import com.randou_tech.ClientBuilder;
import com.randou_tech.RdClient;
import com.randou_tech.RdException;
import com.randou_tech.result.Result;
import com.randou_tech.request.order.OrderReviewRequest;
import com.randou_tech.model.Order;

String appid = "aaaaaaaaaaaaaaaaaaaaaaaa";
String appsecret = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

String orderNo = "T575276639039344640";
String bizNo = "xxxxxxxxxxxxx";

OrderReviewRequest request = new OrderReviewRequest();
request.setOrderNo(orderNo).setBizNo(bizNo);

// 审核通过示例
request.pass();

// 审核不通过示例
request.unPass().setReasonType(2).setReasonDetail("这里是审核不通过的文字描述").setReasonDisplay(2);

RdClient rdClient =  ClientBuilder.build(appid, appsecret);
// 切换到沙箱环境
// rdClient.setDebug(true);

try {
    Result<Order> hr = rdClient.orderReview(request);
    
    if (hr.isSuc()) {
        System.out.println("审核成功");
        System.out.println(hr.getData().getDst());
    } else {
        System.out.println("审核失败");
        System.out.println(hr.getError());
    }
} catch (RdException e) {
    e.printStackTrace();
}

自有商品快递发货接口

接口提供方

该接口由燃豆提供给开发者

接口说明

开发者自行上传的实物商品，需要由开发者自行给用户发货，该接口用于用户在积分商城创建兑换订单且订单被审核通过后，给需要快递发货的商品进行发货操作

业务流程说明

1. 当用户在燃豆积分商城中发起兑换操作时；
2. 燃豆服务端会发起积分预扣请求到开发者服务端，该请求中包含了product_type、product_from分别用来表示商品类型和商品来源，如果商品需要快递发货，燃豆会回传用户的收货信息；
3. 如果商品为开发者自行上传的商品，需要开发者自行发货，此时开发者可使用此接口来完成发货操作。

参数说明

该接口除了公共必传参数外，还包括以下参数：

响应示例

正确返回值（http返回码为200）

{
    orderNo: "T575276639039344640",   // 由燃豆生成的兑换订单号
    bizNo: "xxxxxxxxxxxxx"   // 由开发者生成的订单号
}

错误返回值示例（http返回码为非200）

{
    code: 100101,
    error: "WRONG STAGE"
}

注意事项

1. 该接口只能用于开发者自行上传且需要快递发货的商品订单；
2. 该接口只能用于当前待发货的订单；

代码示例

PHP

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;


$appid = 'aaaaaaaaaaaaaaaaaaaaaaaa';
$appsecret = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';

// 商品发货参数示例
$params = [
    'orderNo'          => 'T575276639039344640',
    'bizNo'            => 'xxxxxxxxxxxxx',
    'shipping_company' => 'JT',
    'shipping_no'      => '9999999999999999999999',
];


try {
    $client = RdClientBuilder::getClient($appid, $appSecret);
    // 切换到沙箱环境
    // $client->setDebug(true);

    $result = $client->shipping($params)->getDataSet();

    print_r($result);
} catch (RdException $e) {
    print_r($e);
}

JAVA

import com.randou_tech.ClientBuilder;
import com.randou_tech.RdClient;
import com.randou_tech.RdException;
import com.randou_tech.result.Result;
import com.randou_tech.request.order.OrderShippingRequest;
import com.randou_tech.model.Order;


String appid = "aaaaaaaaaaaaaaaaaaaaaaaa";
String appsecret = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

String orderNo = "T575276639039344640";
String bizNo = "xxxxxxxxxxxxx";

OrderShippingRequest request = new OrderShippingRequest();
request.setOrderNo(orderNo).setBizNo(bizNo).setShippingCompany("SF").setShippingNo("3333333333333333333");

RdClient rdClient =  ClientBuilder.build(appid, appsecret);
// 切换到沙箱环境
// rdClient.setDebug(true);

try {
    Result<Order> hr = rdClient.shipping(request);
    
    if (hr.isSuc()) {
        System.out.println("发货成功");
        System.out.println(hr.getData().getDst());
    } else {
        System.out.println("发货失败");
        System.out.println(hr.getError());
    }
} catch (RdException e) {
    e.printStackTrace();
}

订单取消发货接口

接口提供方

该接口由燃豆提供给开发者

接口说明

开发者自行上传的实物商品，需要由开发者自行给用户发货，该接口用于用户在积分商城创建兑换订单且订单被审核通过后，如果届时无法发货，可通过该接口取消发货，等同于取消订单

业务流程说明

1. 当用户在燃豆积分商城中发起兑换操作时；
2. 燃豆服务端会发起积分预扣请求到开发者服务端，该请求中包含了product_type、product_from分别用来表示商品类型和商品来源，如果商品需要快递发货，燃豆会回传用户的收货信息；
3. 如果商品为开发者自行上传的商品，需要开发者自行发货，届时如果无法发货，可使用该接口取消订单。

参数说明

该接口除了公共必传参数外，还包括以下参数：

响应示例

正确返回值（http返回码为200）

{
    orderNo: "T575276639039344640",   // 由燃豆生成的兑换订单号
    bizNo: "xxxxxxxxxxxxx"   // 由开发者生成的订单号
}

错误返回值示例（http返回码为非200）

{
    code: 100101,
    error: "WRONG STAGE"
}

注意事项

1. 该接口只能用于开发者自行上传且需要快递发货的商品订单；
2. 该接口只能用于当前待发货的订单；
3. 审核通过后再取消发货，对用户体验会有一定影响，请谨慎取消。

代码示例

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;


$appid = 'aaaaaaaaaaaaaaaaaaaaaaaa';
$appsecret = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';


// 订单取消发货参数示例
$params = [
    'orderNo'          => 'T575276639039344640',
    'bizNo'            => 'xxxxxxxxxxxxx',
];


try {
    $client = RdClientBuilder::getClient($appid, $appSecret);
    // 切换到沙箱环境
    // $client->setDebug(true);

    $result = $client->shippingCancel($params)->getDataSet();

    print_r($result);
} catch (RdException $e) {
    print_r($e);
}

JAVA

import com.randou_tech.ClientBuilder;
import com.randou_tech.RdClient;
import com.randou_tech.RdException;
import com.randou_tech.result.Result;
import com.randou_tech.request.order.OrderShippingCancelRequest;
import com.randou_tech.model.Order;


String appid = "aaaaaaaaaaaaaaaaaaaaaaaa";
String appsecret = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

String orderNo = "T575276639039344640";
String bizNo = "xxxxxxxxxxxxx";

OrderShippingCancelRequest request = new OrderShippingCancelRequest();
request.setOrderNo(orderNo).setBizNo(bizNo);

RdClient rdClient =  ClientBuilder.build(appid, appsecret);
// 切换到沙箱环境
// rdClient.setDebug(true);

try {
    Result<Order> hr = rdClient.orderShippingCancel(request);
    
    if (hr.isSuc()) {
        System.out.println("发货成功");
        System.out.println(hr.getData().getDst());
    } else {
        System.out.println("发货失败");
        System.out.println(hr.getError());
    }
} catch (RdException e) {
    e.printStackTrace();
}

自有充值类商品

开发者自有商品直充接口

接口提供方

该接口需要由开发者提供给燃豆

接口说明

用户在积分商城通过兑换或抽奖获得开发者自有的直充商品时，燃豆服务端会通过该接口为用户发起充值。

参数说明

该接口除了公共必传参数外，还包括以下参数：

返回结果

开发者需以json格式返回响应内容，且不论充值结果如何，http响应码必须为200，返回码非200的情况下燃豆会认为本次充值请求失败，取消订单，json对象中的响应参数如下：

返回案例

充值成功

{
    "status": "success",
    "message": "充值成功",
    "chargeBizNo": "aaaaaaaaaaaa"
}

充值失败

{
    "status": "fail",
    "message": "充值失败"
}

充值处理中

{
    "status": "process",
    "message": "充值处理中",
    "chargeBizNo": "aaaaaaaaaaaa"
}

注意事项

1. 对于处理中的充值单，燃豆会通过自有充值类商品结果查询接口，发起后续的充值单结果查询；

代码示例

PHP

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;


$appid = 'aaaaaaaaaaaaaaaaaaaaaaaa';
$appsecret = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';

// 获取全部请求数据
$params = $request->all();

try {
    $client = RdClientBuilder::getClient($appid, $appSecret);
    $event = $client->charge($params);
    print_r($event);

//    充值处理
    todo($event);

//    充值成功返回
    return response()->json([
        'status'      => 'process',  // process表示充值处理中，异步处理充值过程，返回success表示充值无需异步处理，直接充值成功
        'message'     => '充值处理中',
        'chargeBizNo' => 'No1111111',
    ]);

} catch (RdException $e) {
  print_r($e);
  
}

// 充值失败返回
return response()->json([
    'status'  => 'fail',  // 充值失败status返回fail
    'message' => '当前无法充值',
])

JAVA

import com.randou_tech.ClientBuilder;
import com.randou_tech.RdClient;
import com.randou_tech.RdException;
import com.randou_tech.event.GoodsChargeEvent;
import javax.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.RequestMapping;


@RequestMapping("/charge")
public Map<String, String> charge(HttpServletRequest request) {
    String appid = "aaaaaaaaaaaaaaaaaaaaaaaa";
    String appsecret = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

    RdClient client = ClientBuilder.build(appid, appsecret);
    Map<String, String> map = new HashMap<>();
    try {
        GoodsChargeEvent event = client.charge(request);

        // 如果项目中没有javax.servlet.http.HttpServletRequest，可从request中自行获取出全部参数，以下为从jakarta.servlet.http.HttpServletRequest对象中获取参数
        // Enumeration<String> parameterNames = request.getParameterNames();
        // Map<String, String> params = new HashMap<>();
        // // 遍历参数名并获取对应的值
        // while (parameterNames.hasMoreElements()) {
        //     String paramName = parameterNames.nextElement();
        //     String paramValue = request.getParameter(paramName); // 只取第一个值
        //     params.put(paramName, paramValue);
        // }
        // GoodsChargeEvent event = client.chargeWithParams(params);

        System.out.println(event.hasAccount());
        System.out.println(event.hasBizNo());
        System.out.println(event.toString());

//        充值处理
//      todo()

//        充值成功样例
        map.put("status", "process"); // process表示充值处理中，异步处理充值过程，返回success表示充值无需异步处理，直接充值成功
        map.put("message", "充值成功");
        map.put("chargeBizNo", "3333333333");
    } catch (RdException e) {
        map.put("status", "fail");  // 充值失败status返回fail
        map.put("message", "充值失败");
    }
    return map;
}

自有充值类商品结果查询接口

接口提供方

该接口需要由开发者提供给燃豆

接口说明

燃豆在为用户发起充值请求后，如果开发者的充值处理无法即刻完成，即充值接口中status返回process，燃豆后续会通过该接口查询充值结果。

如果开发者的自有充值逻辑没有“处理中”的逻辑，可不对接该接口。

查询逻辑说明

开发者在充值接口中返回了处理中后，燃豆服务端会在发起充值后的以下时间点（5s，15s，1m，10m，30m，1h，2h，5h）发起订单查询，直至开发者返回充值成功或者充值失败（即status字段返回了fail或success），如果在5个小时后最后一次查询中开发者仍返回充值单处理中状态，此时燃豆会认为该笔订单充值失败，同时取消对应商品订单。

请开发者务必保证至少在5小时内完成全部充值流程，如有特殊情况，请在上线前联系客服。

参数说明

该接口除了公共必传参数外，还包括以下参数：

返回结果

开发者需以json格式返回响应内容，且不论查询结果如何，http响应码必须为200，返回码非200的情况下燃豆会认为本次请求失败，json对象中的响应参数如下：

返回案例

充值成功

{
    "status": "success",
    "message": "充值成功",
}

充值失败

{
    "status": "fail",
    "message": "充值失败"
}

充值处理中

{
    "status": "process",
    "message": "充值处理中",
}

代码示例

PHP

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;


$appid = 'aaaaaaaaaaaaaaaaaaaaaaaa';
$appsecret = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';

// 获取全部请求数据
$params = $request->all();

try {
    $client = RdClientBuilder::getClient($appid, $appSecret);
    $event = $client->chargeQuery($params);
    print_r($event);

//    检查本地的充值处理结果
    check($event);

//    充值成功返回
    return response()->json([
        'status'      => 'success',  // status返回success表示充值已处理完毕并且充值成功，process表示充值仍然在处理中
        'message'     => '充值处理中'
    ]);

} catch (RdException $e) {
  print_r($e);
  
}

// 充值失败返回
return response()->json([
    'status'  => 'fail',  // 充值失败status返回fail
    'message' => '当前无法充值',
])

JAVA

import com.randou_tech.ClientBuilder;
import com.randou_tech.RdClient;
import com.randou_tech.RdException;
import com.randou_tech.event.GoodsChargeQueryEvent;
import javax.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.RequestMapping;


@RequestMapping("/chargeQuery")
public Map<String, String> chargeQuery(HttpServletRequest request) {
    String appid = "aaaaaaaaaaaaaaaaaaaaaaaa";
    String appsecret = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

    RdClient client = ClientBuilder.build(appid, appsecret);
    Map<String, String> map = new HashMap<>();
    try {
        GoodsChargeQueryEvent event = client.chargeQuery(request);

        // 如果项目中没有javax.servlet.http.HttpServletRequest，可从request中自行获取出全部参数，以下为从jakarta.servlet.http.HttpServletRequest对象中获取参数
        // Enumeration<String> parameterNames = request.getParameterNames();
        // Map<String, String> params = new HashMap<>();
        // // 遍历参数名并获取对应的值
        // while (parameterNames.hasMoreElements()) {
        //     String paramName = parameterNames.nextElement();
        //     String paramValue = request.getParameter(paramName); // 只取第一个值
        //     params.put(paramName, paramValue);
        // }
        // GoodsChargeQueryEvent event = client.chargeQueryWithParams(params);
        
//        查询本地充值结果
//      check(event);

//        充值成功样例
        map.put("status", "success"); // status返回success表示充值已处理完毕并且充值成功，process表示充值仍然在处理中，
        map.put("message", "充值成功");
    } catch (RdException e) {
        map.put("status", "fail");  // 充值失败status返回fail
        map.put("message", "充值失败");
    }
    return map;
}

积分明细对接

接口提供方

该接口需要由开发者提供给燃豆

接口说明

鉴于燃豆服务端并未包含用户的全部积分明细数据，如果开发者需要在燃豆积分商城中展示用户全部的积分明细，可通过该接口对接后在燃豆后台开启积分明细列表页入口。

燃豆会在用户打开积分明细列表页面时，通过该接口实时请求开发者服务端用于获取积分明细数据直接展示给用户。

如果开发者不需要该功能，可不对接。

参数说明

该接口除了公共必传参数外，还包括以下参数：

返回结果

开发者需以json数组格式返回响应内容，且不论查询结果如何，http响应码必须为200，返回码非200的情况下燃豆会认为本次请求失败，json数组中的响应参数如下：

没有数据，可传空数组

返回案例

获取成功(http响应码为200)

[
    {
        "id": "100",
        "amount": -1000,
        "desc": "抽奖",
        "ts": 1704448060
    },
    {
        "id": "99",
        "amount": -1500,
        "desc": "兑换商品",
        "ts": 1704448060
    },
    {
        "id": "98",
        "amount": 2000,
        "desc": "抽奖获得",
        "ts": 1704448060
    }
]


// 如果没有更多了，请返回空数组
[]

获取失败(http响应码为非200)

{
    "errMsg": "获取失败，请稍后再试"
}

代码示例

PHP

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;


$appid = 'aaaaaaaaaaaaaaaaaaaaaaaa';
$appsecret = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';

$params = $request->all();
try {
    $client = RdClientBuilder::getClient($this->appid2, $this->appSecret2);

    $event = $client->creditsList($params);
//    print_r($event->all());

    return [
        ['id' => '5', 'amount' => -999, 'desc' => '系统年底清零', 'ts' => 1704448060],
        ['id' => '4', 'amount' => 2100, 'desc' => '兑换返还', 'ts' => 1704447060],
        ['id' => '3', 'amount' => -2100, 'desc' => '商品兑换', 'ts' => 1704446060],
        ['id' => '2', 'amount' => 10, 'desc' => '每日签到', 'ts' => 1704445060],
        ['id' => '1', 'amount' => -20, 'desc' => '抽奖', 'ts' => 1704444060],
    ];

} catch (RdException $e) {
    return response()->json([
        'errMsg' => '获取失败，请稍后再试',
    ], 500);
}

JAVA

import com.randou_tech.ClientBuilder;
import com.randou_tech.RdClient;
import com.randou_tech.RdException;
import com.randou_tech.event.QueryCreditsListEvent;
import com.randou_tech.event.CreditsDetail
import com.randou_tech.Helper;
import javax.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.RequestMapping;


@RequestMapping("creditsQuery")
public ArrayList<CreditsDetail> creditsQuery(HttpServletRequest request) throws RdException {
    String appid = "aaaaaaaaaaaaaaaaaaaaaaaa";
    String appsecret = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

    RdClient client = ClientBuilder.build(appid, appsecret);

    QueryCreditsListEvent event = client.queryCreditsList(request);
    // 如果项目中没有javax.servlet.http.HttpServletRequest，可从request中自行获取出全部参数，以下为从jakarta.servlet.http.HttpServletRequest对象中获取参数
    // 获取所有参数名
    // Enumeration<String> parameterNames = request.getParameterNames();
    // Map<String, String> params = new HashMap<>();
    // // 遍历参数名并获取对应的值
    // while (parameterNames.hasMoreElements()) {
    //     String paramName = parameterNames.nextElement();
    //     String paramValue = request.getParameter(paramName); // 只取第一个值
    //     params.put(paramName, paramValue);
    // }
    // QueryCreditsListEvent event = client.queryCreditsListWithParams(params);


    System.out.println(event.toString());

    ArrayList<CreditsDetail> l = new ArrayList<CreditsDetail>();
    l.add(new CreditsDetail("5", "系统年底清零", -888, 1704770389));
    l.add(new CreditsDetail("4", "抽奖", -10, 1704770379));
    l.add(new CreditsDetail("3", "兑换返还", 200, 1704770369));
    l.add(new CreditsDetail("2", "兑换", -200, 1704770359));
    l.add(new CreditsDetail("1", "每日签到", 20, 1704770349));

    System.out.println(Helper.listToJson(l));

    return l;
}

消息订阅相关接口

为燃豆积分商城能够更好的结合开发者的自有系统，燃豆提供了用户在燃豆积分商城中部分相关操作结果的数据推送渠道，开发者可按需订阅。

订阅只需在燃豆开发者后台填写相关的接口，即可获得相应消息的推送。

1. 抽奖
2. 陆续开发中…………

用户抽奖结果的订阅

接口提供方

该接口需要由开发者提供给燃豆

接口说明

抽奖结果订阅接口，对接后可以接收到抽奖相关的结果通知。 可通过该订阅，开发者可结合自身产品实现想要的功能，比如用户抽到商品类奖品，该商品发货的时候，可以通过自身推送系统消息告知用户商品已发货的信息，提升产品体验。

抽奖具体推送时间点下图中黄色框中所示：

• 抽中【积分】，获得该奖品即推送；
• 抽中【再抽1次】，获得该奖品即推送；
• 抽中【优惠券】，系统自动发放，发货该奖品时推送；
• 抽中【实物商品】【直充商品】，因领取商品是需要用户手动填写收货信息/充值账号信息
  • 如果用户填写了收货信息/充值账号信息，系统发货该奖品时推送；
  • 如果用户未在领奖期限内填写收货信息/充值账号信息，导致过期未领。领奖过期时推送。

参数说明

该接口除了公共必传参数外，还包括以下参数：

drawinggame_detail参数说明

prize参数说明

prize.goods参数说明

返回结果

在收到消息推送后，开发者需要以HTTP响应码为200且body为“success”纯文本字符串（不包含引号）返回给燃豆，表示已正确处理了该消息，其他返回均视作失败。

注意事项

1. 抽奖业务流程较长，情况较多，请开发者做好相应的处理。

代码示例

PHP

use Randou\Exception\RdException;
use Randou\RdClient;
use Randou\RdClientBuilder;


$appid = 'aaaaaaaaaaaaaaaaaaaaaaaa';
$appsecret = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb';

// 获取全部请求数据
$params = $request->all();

try {
    $client = RdClientBuilder::getClient($appid, $appsecret);
    $event = $client->drawingGameSubscription($params);
    $client->setDebug(true); // 切换沙箱环境

    if ($event->isHit()) { // 是否中奖
        echo '中奖啦';
        if ($event->isReceive()) {   // 是否领奖
            echo '领奖啦';
            print_r($event->getPrize()); // 打印奖品信息

            if ($event->isGoodsPrize()) {
                echo '中了商品类奖品';
                print_r($event->getGoodsPrize()); // 打印商品信息
                echo $event->isPrizeGoodsOrderSuccess() ? '商品类奖品发放成功' : '商品类奖品发放失败';  // 打印商品类奖品产生的订单是否成功
            } elseif ($event->isCreditsPrize()) {
                echo '中了积分类商品';
                print_r($event->getCreditsGain()); // 抽中的积分数量
            } elseif ($event->isFreeDrawPrize()) {
                echo '中了“再来一瓶”';
            }
        } else {
            echo '未领奖';
        }
    } else {
        echo '很遗憾，未中奖';
    }

} catch (RdException $e) {
    print_r($e->getMessage());
    return response('fail', 400);
}

return response('success', 200);

JAVA

import com.randou_tech.ClientBuilder;
import com.randou_tech.RdClient;
import com.randou_tech.RdException;
import com.randou_tech.event.DrawingPrizeEvent;
import javax.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.RequestMapping;

@RequestMapping("/subscription-drawinggame")
public String subscriptionDrawinggame(HttpServletRequest request) {
    RdClient client = ClientBuilder.build(appid, appsecret);
    // client.setDebug(debug);

    try {
        DrawingPrizeEvent event = client.drawingGameSubscription(request);
        // 如果项目中没有javax.servlet.http.HttpServletRequest，可从request中自行获取出全部参数，以下为从jakarta.servlet.http.HttpServletRequest对象中获取参数
        // 获取所有参数名
        // Enumeration<String> parameterNames = request.getParameterNames();
        // Map<String, String> params = new HashMap<>();
        // // 遍历参数名并获取对应的值
        // while (parameterNames.hasMoreElements()) {
        //     String paramName = parameterNames.nextElement();
        //     String paramValue = request.getParameter(paramName);
        //     params.put(paramName, paramValue);
        // }
        // DrawingPrizeEvent event = client.drawingGameSubscriptionWithParams(params);
        
        System.out.println(event);

        if (event.isHit()) { // 是否中奖
            System.out.println("中奖啦");
            if (event.isReceive()) {  // 是否领奖
                System.out.println("领奖啦");
                System.out.println(event.getPrize());
                if (event.isCreditsPrize()) {
                    System.out.println("领的是积分奖：" + event.getCreditsGain());
                } else if (event.isGoodsPrize()) {
                    System.out.println("领的是商品奖：" + event.getGoodsPrize());
                    System.out.println("商品类奖品是否发放成功" + event.isPrizeGoodsOrderSuccess());
                } else if (event.isFreeDrawPrize()) {
                    System.out.println("领的是再来一瓶：" + event.prize.type);
                }
            } else {
                System.out.println("没领奖");
            }
        } else {
            System.out.println("未中奖");
        }

        return "success";
    } catch (RdException e) {
        System.out.println(e);
        return "fail";
    }
}

概况

• 关于游客账号
• 关于redirect参数
• 快递公司列表
• 微信小程序分享

关于游客账号

游客账号用于开发者的用户在未登录的情况下浏览积分商城，当游客账号在访问需要登录才能使用的功能时，如参与活动、访问我的兑换记录等，燃豆默认提示一个未登录的弹框，如下图所示：

如需跳转至指定登录页，请联系客服！！！

关于redirect参数

redirect参数用于开发者在调用燃豆免登接口时指定需要打开的页面，把需要打开的页面的地址通过该参数传递给燃豆，用户在打开时即跳转到对应页面。

鉴于开发者自行拼接对应页面的uri较为繁琐，当前我们在燃豆开发者后台提供了部分页面的链接复制功能，开发者只需在燃豆开发者后台的“API接口配置”配置用户登录接口即可使用，请注意该接口为开发者在自己的产品中配置的用于打开积分俱乐部的接口地址，与燃豆并无直接交互，填写该地址仅用于开发者方便拼接对应的uri，以实现打开积分商城指定页面的功能；

当前支持复制的页面

1. 首页

2. 商品详情页

开发者如果还需要其他页面，请联系我们。

案例

假设开发者填写的登陆接口链接为https://a.com/mall/entry，且当前要打开商城首页，则复制出来的地址即如下：

https://a.com/mall/entry?redirect=%2F

该redirect参数即为打开商城首页的目标uri，开发者只需在自己的接口将该redirect参数的值透传给燃豆免登接口即可。

快递公司列表

当前燃豆开发者后台支持的快递公司，如需要补充其他快递公司，请联系客服添加

微信小程序分享

目标

开发者在自有微信小程序中通过嵌入燃豆积分商城并实现自定义分享（转发），用户在点击他人转发出来的分享卡片后直接打开积分商城中的被分享页面。

实现逻辑

开发者通过微信小程序的web-view组件接入燃豆积分商城的页面后，通过web-view组件提供的bindmessage属性来接收当前H5页面的信息（包括图片，链接，说明等）；然后通过这些信息来实现自定义的分享内容。

H5推送的消息如下所示：

wx.miniProgram.postMessage({
    data: {
        title: '页面内容',
        // 该redirect是用于打开当前积分商城H5页面的地址，把该地址通过免登接口的redirect参数传递给燃豆服务端，即可实现打开积分商城后直接抵达该页面
        redirect: '%2Fgoods%3Fgoods_id%3Dce115952-45ff-402f-8d23-33d13b0be134',  
        // imageUrl为页面的图片，当前仅分享商品详情页时有值，其他页面都为空，建议直接使用微信小程序默认的图片展示方式即可
        imageUrl: 'https://static.randou-tech.com/goods/2023/11/e725f129c58cbdbe6ddaf3a17473c88d_thumb.png',
    },
});

开发者可通过bindmessage属性接收上述商城页面推送的信息，关于该属性，请查看微信小程序官方开发文档。

注意事项

1. 关于推送中的redirect参数：该参数用于打开燃豆积分商城指定页面，需要配合免登接口中的redirect参数一起使用才能实现打开积分商城中指定页面，请注意推送中的redirect参数是使用了url编码后的值；
2. 关于imageUrl参数：该参数当前仅商品详情页中会返回商品图的第一张图片地址，其他页面都为空，为空的情况下，建议直接使用微信小程序提供的默认方式，默认方式请查看微信小程序官方开发文档中关于图片参数为空的处理方式；
3. 请开发者注意转发过程中微信小程序关于各个API或者组件的版本支持情况，进行全面测试。

小程序关键代码示例

wxml文件示例

<!-- pages/mall/mall.wxml -->
<!-- listenMsg用来监听由H5传递的信息 -->
<web-view src="{{url}}" bindmessage="listenMsg" />

js文件示例

// pages/mall/mall.js
Page({

  /**
   * 页面的初始数据
   */
  data: {
    url: '',  // 燃豆积分商城的打开地址
    shareParam: {
      title: '默认title',
      imageUrl: '默认图片',
      path: '/pages/mall/mall', // 非真实地址，请开发者自行替换
    },
  },

  /**
   * 生命周期函数--监听页面加载
   */
  onLoad(options) {
    wx.showLoading({
      title: '打开中',
    })

    const p = {};
    if ('redirect' in options) {
      // 接收到的redirect经过了url编码处理，传给开发者服务端时请注意编码问题
      p['redirect'] = decodeURIComponent(options.redirect);
    }
    // console.log(p);

    var that = this;
    wx.request({
      url: 'https://a.com/rd-mall/entry', // 仅为示例，并非真实的接口地址
      method: 'GET',
      data: p,
      success(res) {
        // console.log(res);
        that.setData({
          url: res.data.dst,  // 写入可打开的地址
        })
        wx.hideLoading();
      },
      fail(err) {
        console.log(err)
        wx.hideLoading();
      }
    })
  },

  /**
   * 监听webview推送的消息
   */
  listenMsg(e) {
    console.log('listenMsg', e);
    const {
      data
    } = e.detail;
    // 由于消息会多次推送，因此请使用最后一次推送的消息
    this.setData({
      shareParam: {
        title: data[data.length - 1].title,
        imageUrl: data[data.length - 1].imageUrl,
        // path地址请自行修改为真实地址，请注意，data中推送的redirect经过了url编码处理，
        // path的redirect参数需要在分享内容被打开后获取到，通过免登接口传递给燃豆服务端以打开对应页面
        path: '/pages/mall/mall?redirect=' + data[data.length - 1].redirect, 
      }
    })
  },
  
  /**
   * 用户点击右上角分享
   */
  onShareAppMessage(e) {
    console.log('onShareAppMessage:', e, this.data.shareParam);
    return this.data.shareParam;
  }

  /**
   * 生命周期函数--监听页面初次渲染完成
   */
  onReady() {

  },

  /**
   * 生命周期函数--监听页面显示
   */
  onShow() {

  },

  /**
   * 生命周期函数--监听页面隐藏
   */
  onHide() {

  },

  /**
   * 生命周期函数--监听页面卸载
   */
  onUnload() {

  },

  /**
   * 页面相关事件处理函数--监听用户下拉动作
   */
  onPullDownRefresh() {

  },

  /**
   * 页面上拉触底事件的处理函数
   */
  onReachBottom() {

  },
})