银商聊天开放接口文档

用于三方平台与银商系统之间的即时通讯对接

基础路径： /api/agent/player/chat
完整示例： https://agent.samsctop.com/api/agent/player/chat/merchants
图片上传路径： /api/common/upload/image
WebSocket 端点： wss://agent.samsctop.com/ws

🔑 认证方式必须

HTTP 接口：所有 HTTP 接口均需要在请求头中携带 X-API-Key，值为平台分配给贵方的唯一密钥（从后台 sys_config 表中配置）。

X-API-Key: your-unique-api-key-here

WebSocket 连接：不需要 X-API-Key，只需在 URL 参数中提供 username（玩家的游戏ID）即可识别身份。

注意： API Key 由银商系统管理，请妥善保管，避免泄露。如 Key 无效或缺失，接口将返回 {"code":500,"msg":"无效的 API Key"}。

1. 获取可用银商列表

GET /merchants

获取当前所有正常营业的银商（代理）信息，用于玩家选择客服归属。银商需满足：sys_user.userType=2 AND sys_user.status=2 AND agent_info.shop_status=1。

请求头

参数名	类型	必填	说明
X-API-Key	string	是	平台分配的 API Key

响应示例

{ "code": 200, "msg": "success", "data": [ { "agentId": 1001, "shopName": "银商一店", "businessStatus": 1, "customerLink": "https://example.com/shop1", "image": "https://xxxx.com/xxx.jpg" }, { "agentId": 1002, "shopName": "银商二店", "businessStatus": 1, "customerLink": "https://example.com/shop2", "image": "https://xxxx.com/xxx.jpg" } ] }

字段说明： agentId 为银商唯一标识；shopName 银商名称；businessStatus 1=营业 0=休息；customerLink 银商官方链接（可选）；image 银商标识图片（可选）。

2. 发送消息（玩家 -> 银商）

POST /send

玩家向指定银商发送消息。若玩家（username + agentId）首次聊天，系统会自动创建玩家记录；后续同一玩家对同一银商直接使用已有记录。

请求头

参数名	类型	必填	说明
X-API-Key	string	是	平台分配的 API Key
Content-Type	string	是	application/json

请求 Body 参数 (JSON)

的人们nickname的人们realName

参数名	类型	必填	说明
username	string	是	玩家在原系统的唯一登录标识（游戏ID）
agentId	number	是	目标银商ID（从 /merchants 接口获取）
content	string	是	消息内容，纯文本或图片URL，最长500字符
string	否	玩家昵称，首次创建时若未提供则默认使用 username
string	否	玩家真实姓名（可选）

请求示例

POST /api/agent/player/chat/send Headers: X-API-Key: xxxxx Body: { "username": "player_123456", "agentId": 1001, "content": "你好，请问充值优惠？", "nickname": "小明", "realName": "张小明" }

响应示例

{ "code": 200, "msg": "发送成功", "data": null }

错误示例（缺少 username）：

{ "code": 500, "msg": "gameId 不能为空" }

3. 获取聊天记录

GET /messages

根据玩家游戏ID（username）和银商ID（agentId）分页获取聊天历史记录。不需要提前获取内部 playerId。

请求头

参数名	类型	必填	说明
X-API-Key	string	是	平台分配的 API Key

Query 参数

参数名	类型	必填	说明
username	string	是	玩家的游戏ID（与发送消息中的 username 一致）
agentId	number	是	银商ID
page	number	否	页码，默认1
size	number	否	每页条数，默认20，最大100

请求示例

GET /api/agent/player/chat/messages?username=player_123456&agentId=1001&page=1&size=20 Headers: X-API-Key: xxxxx

响应示例

{ "code": 200, "msg": "success", "data": { "list": [ { "id": 101, "senderType": 2, "content": "你好，请问充值优惠？", "createTime": "2025-04-10 10:30:00" }, { "id": 102, "senderType": 1, "content": "您好，目前有满100减10活动", "createTime": "2025-04-10 10:32:15" } ], "total": 2, "page": 1, "size": 20 } }

字段说明： senderType 1=银商（代理）发送，2=玩家发送；createTime 格式为 yyyy-MM-dd HH:mm:ss。

4. 标记消息已读

PUT /markRead

玩家端调用此接口，将玩家与银商之间的所有未读消息（银商发给玩家的）标记为已读。

请求头

参数名	类型	必填	说明
X-API-Key	string	是	平台分配的 API Key

Query 参数

参数名	类型	必填	说明
username	string	是	玩家的游戏ID
agentId	number	是	银商ID

请求示例

PUT /api/agent/player/chat/markRead?username=player_123456&agentId=1001 Headers: X-API-Key: xxxxx

响应示例

{ "code": 200, "msg": "已标记已读" }

5. 创建提现订单（三方提交）

POST /createOrder

三方平台提交提现订单，订单状态默认为 0（待派单）。

请求头

参数名	类型	必填	说明
X-API-Key	string	是	平台分配的 API Key
Content-Type	string	是	application/json

请求 Body 参数 (JSON)

参数名	类型	必填	说明
orderNo	string	是	交易流水号/订单号（唯一）
amount	string	是	金额，字符串格式（如 "100.00"）
bankUrl	string	否	备注信息（对应 member_remark 字段）
bankCard	string	否	支付宝账号/银行卡号/USDT地址
bankName	string	否	银行名称（银行卡类型时使用）
realName	string	是	真实姓名
remitType	number	否	支付类型：1=微信二维码，2=支付宝二维码，3=支付宝账号，4=银行卡，5=数字人民币，6=USDT

📌 订单状态说明：
0-待派单 → 1-已派单 → 2-处理中 → 3-成功或 4-失败

请求示例

POST /api/agent/player/chat/createOrder Headers: X-API-Key: xxxxx Body: { "orderNo": "WD20250101123456", "amount": "500.00", "bankUrl": "急用，请尽快处理", "bankCard": "6222021234567890123", "bankName": "中国银行", "realName": "张三", "remitType": 4 }

响应示例

{ "code": 200, "msg": "订单创建成功", "data": { "orderNo": "WD20250101123456", "status": 0, "createTime": "2026-05-29 15:30:00" } }

错误示例（订单号已存在）：

{ "code": 500, "msg": "订单号已存在" }

6. 批量查询订单状态

POST /orderBatchQuery

三方平台批量查询订单状态。此接口只返回状态为成功(3)或失败(4)的订单，处理中的订单不会在列表中返回，会放在 notFoundOrderNos 字段中。

请求头

参数名	类型	必填	说明
X-API-Key	string	是	平台分配的 API Key
Content-Type	string	是	application/json

请求 Body 参数 (JSON)

参数名	类型	必填	说明
orderNos	array	是	订单号数组，如 ["WD001", "WD002", "WD003"]

请求示例

POST /api/agent/player/chat/orderBatchQuery Headers: X-API-Key: xxxxx Body: { "orderNos": ["WD20250101123456", "WD20250101123457", "WD20250101123458", "WD20250101123459"] }

响应示例

{ "code": 200, "msg": "success", "data": { "list": [ { "orderNo": "WD20250101123456", "amount": 500.00, "status": 3, "statusDesc": "成功", "failReason": null, "createTime": "2026-05-29 15:30:00", "completeTime": "2026-05-29 16:30:00", "bankCard": "6222021234567890123", "bankName": "中国银行", "realName": "张三" }, { "orderNo": "WD20250101123457", "amount": 300.00, "status": 4, "statusDesc": "失败", "failReason": "银行卡信息错误，打款失败", "createTime": "2026-05-29 15:35:00", "completeTime": "2026-05-29 15:45:00", "bankCard": "6222021234567890999", "bankName": "工商银行", "realName": "李四" } ], "total": 2, "notFoundOrderNos": ["WD20250101123458", "WD20250101123459"] } }

响应字段说明

字段名	类型	说明
list	array	已完成订单列表（状态为3或4的订单）
list[].orderNo	string	订单号
list[].amount	number	订单金额
list[].status	number	订单状态：3-成功，4-失败
list[].statusDesc	string	状态描述（成功/失败）
list[].failReason	string	失败原因（仅失败时有值）
list[].createTime	string	订单创建时间
list[].completeTime	string	订单完成时间
list[].bankCard	string	收款账号/银行卡号
list[].bankName	string	银行名称
list[].realName	string	真实姓名
total	number	已完成订单数量
notFoundOrderNos	array	未完成的订单号列表（状态为0、1、2的订单，或订单不存在）

📌 使用建议：
- 三方平台可定时（如每10-30秒）调用此接口批量查询订单状态。
- 返回的 notFoundOrderNos 中的订单号表示尚未处理完成，需要继续等待后续查询。
- 订单状态说明：0-待派单 1-已派单 2-处理中 3-成功 4-失败

7. 上传图片

POST /api/common/upload/image

上传图片文件，用于聊天中的图片消息。上传成功后返回图片URL，可直接用于发送消息的 content 字段。

请求头

的人们X-API-Key的人们Content-Type

参数名	类型	必填	说明
string	是	平台分配的 API Key
string	是	multipart/form-data

请求参数 (form-data)

的人们file

参数名	类型	必填	说明
file	是	图片文件，支持 jpg、png、gif、webp 等格式，大小不超过2MB

请求示例

POST /api/common/upload/image Headers: X-API-Key: xxxxx Body (form-data): file = @/path/to/image.jpg

响应示例

{ "url": "https://agent.samsctop.com/images/20250526123456_abc123.jpg" }

返回的 url 可以直接作为发送消息接口的 content 参数（图片消息）使用。

错误示例：

{ "timestamp": "2025-05-26T04:34:56.789+00:00", "status": 500, "error": "Internal Server Error", "message": "图片大小不能超过2MB" }

8. WebSocket 实时消息推送

WebSocket wss://agent.samsctop.com/ws

玩家端建立 WebSocket 连接后，可以实时接收到两类消息：银商回复的聊天消息 和 代理充值到账通知。

连接参数

的人们username

参数名	类型	必填	说明
string	是	玩家的唯一标识（游戏ID，与发送消息接口中的 `username` 完全一致）

连接 URL 示例：wss://agent.samsctop.com/ws?username=player_123456

注意： WebSocket 连接不需要 X-API-Key，仅通过 username 识别玩家身份。连接后会建立点对点通道。

连接协议

使用 STOMP 1.2 协议，底层支持 WebSocket 和 SockJS（推荐使用 SockJS 实现降级）。客户端需要实现 STOMP 客户端。

订阅地址

连接成功后，需要订阅以下两个目的地址（可同时订阅）：

/user/queue/chat — 用于接收银商回复的聊天消息
/user/queue/recharge — 用于接收代理充值的到账通知

（/user 前缀由框架自动处理，实际订阅时只需写 /queue/chat 和 /queue/recharge）

消息格式

聊天消息（银商回复）

{ "msgId": 123, "playerId": 10086, "agentId": 1001, "content": "您好，有什么可以帮您？", "senderType": 1, "createTime": "2025-05-26 15:30:00", "nickname": "银商客服", "gameId": "agent_1001" }

充值到账通知（代理充值成功后推送）

{ "orderNo": "CZ1686123456001", "amount": 100.00, "afterBalance": 1250.00, "payType": "manual", "rechargeTime": "2025-06-07T10:30:00", "username": "player_123456" }

字段说明：

orderNo - 充值订单号
amount - 充值金额
afterBalance - 充值后玩家余额
payType - 固定为 "manual"（人工充值）
rechargeTime - 充值时间（ISO 8601格式）
username - 玩家的 gameId

连接步骤（JavaScript + StompJS 示例）

// 安装依赖: npm install @stomp/stompjs sockjs-client import { Client } from '@stomp/stompjs'; import SockJS from 'sockjs-client'; const username = 'player_123456'; const client = new Client({ webSocketFactory: () => new SockJS(`https://agent.samsctop.com/ws?username=${username}`), debug: (str) => console.log(str), onConnect: () => { console.log('WebSocket 连接成功'); // 订阅聊天消息 client.subscribe('/user/queue/chat', (message) => { const msg = JSON.parse(message.body); console.log('收到银商消息:', msg); // 处理聊天消息，显示在聊天界面 }); // 订阅充值通知 client.subscribe('/user/queue/recharge', (message) => { const recharge = JSON.parse(message.body);

银商聊天开放接口文档

🔑 认证方式 必须

请求头

响应示例

请求头

请求 Body 参数 (JSON)

请求示例

响应示例

请求头

Query 参数

请求示例

响应示例

请求头

Query 参数

请求示例

响应示例

请求头

请求 Body 参数 (JSON)

请求示例

响应示例

请求头

请求 Body 参数 (JSON)

请求示例

响应示例

响应字段说明

请求头

请求参数 (form-data)

请求示例

响应示例

连接参数

连接协议

订阅地址

消息格式

连接步骤（JavaScript + StompJS 示例）

🔑 认证方式必须