对接文档-PlayX 调用积分商城接口说明

docs/PlayX-接口文档.md

@@ -823,6 +823,64 @@ curl -G 'http://localhost:1818/api/v1/mall/orders' --data-urlencode 'token=上
 
 ---
 
-### 3.11 同步额度（可选）
+### 3.11 积分流水（Points Logs）
+* 方法：`GET`
+* 路径：`/api/v1/mall/pointsLogs`
+
+#### 请求参数（鉴权）
+同 **3.1**（`session_id` / `token` / `user_id`）。
+
+#### Query 参数
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `limit` | int | 否 | 每页条数，默认 20，最大 100 |
+| `cursor` | string | 否 | 游标（上一页返回 `next_cursor`） |
+| `direction` | string | 否 | `IN` 仅入账 / `OUT` 仅扣减；不传返回全部 |
+
+#### 返回（成功 data）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.list` | array | 流水数组（时间倒序） |
+| `data.next_cursor` | string\|null | 下一页游标（本页最后一条记录的游标） |
+
+`list` 每一项字段：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `biz_type` | string | `CLAIM`/`REDEEM_BONUS`/`REDEEM_PHYSICAL`/`REDEEM_WITHDRAW`/`REFUND` |
+| `direction` | string | `IN`/`OUT` |
+| `points` | int | 积分变动值（正数，方向由 `direction` 表示） |
+| `ts` | int | Unix 秒 |
+| `ref_id` | string | 领取为 `claim_request_id`；订单为 `external_transaction_id` |
+| `order_no` | string | 订单号（非订单类为空） |
+| `order_status` | string | 订单状态（非订单类为空） |
+| `mallItem` | object\|null | 商品信息（非订单类为 null） |
+| `item_id` | int | 兼容字段：商品ID（非订单类为 0） |
+| `item_title` | string | 兼容字段：商品标题（非订单类为空） |
+| `item_type` | int | 兼容字段：商品类型（非订单类为 0；`1=BONUS 2=PHYSICAL 3=WITHDRAW`） |
+| `item_score` | int | 兼容字段：商品所需积分（非订单类为 0） |
+| `cursor` | string | 当前记录游标 |
+
+`mallItem` 字段（非隐私）：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | int | `mall_item.id` |
+| `title` | string | 商品名 |
+| `type` | int | 商品类型 |
+| `score` | int | 所需积分 |
+| `amount` | number | 现金面值 |
+| `multiplier` | int | 流水倍数 |
+| `category` | string | 红利业务类别 |
+| `category_title` | string | 类别展示名 |
+
+#### 示例
+```bash
+curl -G 'http://localhost:1818/api/v1/mall/pointsLogs' \
+  --data-urlencode 'token=上一步temLogin返回的token' \
+  --data-urlencode 'limit=20'
+```
+
+---
+
+### 3.12 同步额度（可选）
 当前代码未实现并未注册路由：`/api/v1/mall/syncLimit`。