Java API 开发文档

> [点击查看](https://github.com/MinePayTeam/MinePayApiDemo)开发例子

# 添加依赖
> i 推荐使用 API V2 进行开发，需 **MinePay ≥ 3.9.0**（研发中）
```xml
<dependencies>
    <dependency>
        <groupId>top.minepay</groupId>
        <artifactId>MinePayApi</artifactId>
        <version>2.0-RELEASE</version>
		<scope>provided</scope>
    </dependency>
</dependencies>
```

# 监听事件
```java
/**
* 开始交易
*
* @param event 事件
*/
@EventHandler
public void onMinePayPreTradingEvent(MinePayPreTradingEvent event) {
	Bukkit.getConsoleSender().sendMessage("preTrading");
	// 获取订单信息
	TradeInfo info = event.getTradeInfo();
	// 获取订单价格（单位：分）
	int price = info.getPrice();
	// 允许修改订单金额（单位：分）
	info.setPrice(100);
	// 获取下单玩家名字
	String playerName = info.getPlayerName();
	// 获取订单类型（点券或礼包）
	TradeType tradeType = info.getTradeType();
	// 获取付款方式（微信或支付宝）
	PaymentType paymentType = info.getType();
	// 设置 true 将取消订单
	event.setCancelled(false);
}

/**
* 交易处理
*
* @param event 事件
*/
@EventHandler
public void onMinePayTradingEvent(MinePayTradingEvent event) {
	Bukkit.getConsoleSender().sendMessage("trading");
	// 默认 true ，设置为 false 那么 MinePay 将不处理订单，如二维码地图生成等
	event.setHandled(true);
	TradeInfo info = event.getTradeInfo();
	// 获取用于生成二维码的文本内容
	String qrCodeContent = info.getQrcodeContent();
}

/**
* 订单开始取消
*
* @param event 事件
*/
@EventHandler
public void onMinePayPreCancelEvent(MinePayPreCancelEvent event) {
	Bukkit.getConsoleSender().sendMessage("preCancel");
}

/**
* 订单已取消
*
* @param event 事件
*/
@EventHandler
public void onMinePayCancelledEvent(MinePayCancelledEvent event) {
	Bukkit.getConsoleSender().sendMessage("cancelled");
}

/**
* 完成交易
*
* @param event 事件
*/
@EventHandler
public void onMinePaySuccessEvent(MinePaySuccessEvent event) {
	Bukkit.getConsoleSender().sendMessage("success");
}

/**
* 订单过期
*
* @param event 事件
*/
@EventHandler
public void onMinePayOutdatedEvent(MinePayTradeOutDatedEvent event) {
	Bukkit.getConsoleSender().sendMessage("outdated");
}
```

# 获取服务
```java
RegisteredServiceProvider<MinePayApiService> provider = getServer()
        .getServicesManager()
        .getRegistration(MinePayApiService.class);
MinePayApiService minePayApiService = provider.getProvider();
```

# 订单
### 生成订单
```java
// 构建礼包订单
KitBuilder kitBuilder = minePayApiService.kit()
        .remark("订单备注")
        .paymentType(PaymentType.WECHAT)
        .kitName("测试金币")
        .playerName("玩家名字");
// 发起订单
minePayApiService.order()
        // 支持异步
        .createAsync(kitBuilder)
        .whenComplete(($, throwable) -> {
            if (throwable != null) {
                Bukkit.getConsoleSender()
                        .sendMessage("订单创建失败: " + throwable.getMessage());
            }
        });

// 构建点券订单
PointBuilder pointBuilder = minePayApiService.point()
        .remark("订单备注")
        .paymentType(PaymentType.ALIPAY)
        .playerName("玩家名字")
        .quantity(100);
// 发起订单
minePayApiService.order()
        // 同步发起
        .create(pointBuilder);
```

### 取消订单
```java
minePayApiService.order().close(player);
```

# 排行榜
### 获取 N 个排行榜
```java
minePayApiService.rank()
        // 异步获取 10 个排行榜的数据
        .getMaxAsync(10)
        .whenComplete((rankItems, throwable) -> {
            for (RankItem item : rankItems) {
                Bukkit.getConsoleSender()
                        .sendMessage(item.getPlayerName() + ": " + item.getValue());
            }
        });
```
### 获取指定排行榜
```java
// 单独异步获取排行榜
minePayApiService.rank()
        .getRankAsync(1)
        .whenComplete((rankItem, throwable) ->
                Bukkit.getConsoleSender()
                        .sendMessage(rankItem.getPlayerName() + ": " + rankItem.getValue()));
```

# 累充 API
### 获取累充数据
```java
minePayApiService.consume()
        // 异步获取累充数据
        .getConsumeAsync(player)
        .whenComplete((consume, throwable) ->
                Bukkit.getConsoleSender()
                .sendMessage(player.getName() + ":" + consume.toString()));
```

### 设置累充
```java
minePayApiService.consume()
        // 异步设置玩家累充为 1￥（100 分）
        .setConsumeAsync(player, 100);
```

### 添加累充
```java
minePayApiService.consume()
        // 异步增加玩家累充 1￥（100 分）
        .addConsume(player, 100);
````

### 减少累充
```java
minePayApiService.consume()
        // 异步减少玩家累充 1￥（100 分）
        .subConsume(player, 100);
```

# 充值记录
### 获取充值记录
```java
minePayApiService.rechargeLog()
        // 异步获取充值数据
        .getAsync(player)
        .whenComplete((logs, throwable) -> {
            for (RechargeLogItem log : logs) {
                Bukkit.getConsoleSender()
                        .sendMessage(log.toString());
            }
        });
```

---

> w 旧版本 API
> 适用 MinePay < 3.9.0
```xml
<dependencies>
    <dependency>
        <groupId>top.minepay</groupId>
        <artifactId>MinePayApi</artifactId>
        <version>1.8-RELEASE</version>
		<scope>provided</scope>
    </dependency>
</dependencies>
```

### 监听事件
```java
/**
* 开始交易
*
* @param event 事件
*/
@EventHandler
public void onMinePayPreTradingEvent(MinePayPreTradingEvent event) {
	Bukkit.getConsoleSender().sendMessage("preTrading");
	// 获取订单信息
	TradeInfo info = event.getTradeInfo();
	// 获取订单价格（单位：分）
	int price = info.getPrice();
	// 允许修改订单金额（单位：分）
	info.setPrice(100);
	// 获取下单玩家名字
	String playerName = info.getPlayerName();
	// 获取订单类型（点券或礼包）