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

docs/H5-积分商城接口文档.md

@@ -159,6 +159,47 @@ curl "https://{域名}/api/v1/temLogin?username=test001"
 
 ---
 
+### 3.9 积分流水（领取/兑换/退回）
+
+**GET** ` /api/v1/mall/pointsLogs `
+
+鉴权：携带 `token` 或 `session_id` 或 `user_id`
+
+参数（Query）：
+- `limit`：可选，每页条数（默认 20，最大 100）
+- `cursor`：可选，游标（上一页响应返回的 `next_cursor`，传入后获取下一页）
+- `direction`：可选，`IN`（入账）/`OUT`（扣减），不传返回全部
+
+返回（成功 `data`）：
+- `list[]`：流水数组（按时间倒序）
+  - `biz_type`：`CLAIM`（领取入账）/ `REDEEM_BONUS|REDEEM_PHYSICAL|REDEEM_WITHDRAW`（兑换扣分）/ `REFUND`（订单驳回或终态失败退回）
+  - `direction`：`IN` / `OUT`
+  - `points`：积分变动值（正数，方向由 `direction` 表示）
+  - `ts`：时间戳（Unix 秒）
+  - `ref_id`：关联业务号（领取为 `claim_request_id`；订单为 `external_transaction_id`）
+  - `order_no`：订单号（非订单类为空）
+  - `order_status`：订单状态（非订单类为空）
+  - `mallItem`：商品信息（非订单类为 null）
+    - `id`：商品ID
+    - `title`：商品名
+    - `type`：商品类型（`1=BONUS 2=PHYSICAL 3=WITHDRAW`）
+    - `score`：所需积分
+    - `amount`：现金面值（红利/提现档位）
+    - `multiplier`：流水倍数
+    - `category`：红利业务类别
+    - `category_title`：类别展示名
+  - `item_id/item_title/item_type/item_score`：兼容字段（建议优先使用 `mallItem`）
+  - `cursor`：当前记录游标（用于分页）
+- `next_cursor`：下一页游标（为本页最后一条的 `cursor`；若本页为空则为 null）
+
+示例：
+
+```bash
+curl -G "https://{域名}/api/v1/mall/pointsLogs" \
+  -H "token: <muser_token>" \
+  --data-urlencode "limit=20"
+```
+
 ## 4. 地址管理（H5）
 
 > 地址与资产主体通过 `playx_user_asset_id` 关联（即 `mall_user_asset.id`）。