商户群机器人使用说明

机器人：@puyunpay_bot。提供商户余额、订单只读查询及平台向商户发送支付通知失败时的告警，不提供群内补单、改订单、提现或转账。

绑定商户群

内部群余额查询：超管“系统配置 → 内部群通知”中指定的内部群无需绑定商户。群主或非匿名群管理员可发送 /balance@puyunpay_bot M1788699797 查询指定商户，只显示人民币可用、人民币冻结及查询时间；机器人也需为群管理员。未填商户号会提示用法，商户不存在会提示核对；两秒限频，不支持全商户批量查询。发送前再次核对内部群配置，旧群失去跨商户查询权限。以下绑定流程仅适用于普通商户群。

1. 把机器人加入目标商户群并设为管理员。
2. 由群管理员发送 /bind@puyunpay_bot，取得 10 分钟有效、一次性使用的绑定码。
3. 平台管理员打开运营后台“商户列表 → TG 群”，确认目标商户、输入绑定码后绑定，无需选择余额币种。
4. 在群内发送 /balance@puyunpay_bot 和 /orders@puyunpay_bot 1 验证。

每个商户只能绑定一个群，每个群只能绑定一个商户。机器人被移除、降权或群迁移后会暂停绑定，需要后台解绑并重新绑定。解绑后停止查询和未发送告警；已经发送的群消息不会自动撤回。

查询命令

群内有多个机器人时，命令后加 @puyunpay_bot。商户群余额回复只显示商户号、人民币可用和人民币冻结（¥，保留两位小数），不再展示原账户余额或币种标注；后台绑定无需选择币种。历史账务与绑定兼容字段保留，不删除或合并资金。订单金额仍按订单自身币种显示。人民币收款按下单时的商户授权费率扣费后入账，详见商户余额入账说明。

自动告警

• 首次观察到商户通知失败：提示系统继续重试。
• 商户通知重试耗尽：提示检查商户接收接口。
• 已发送失败告警的通知随后成功：发送恢复成功提示。

告警只读取已落库的平台 → 商户支付通知结果，不是上游 → 平台通知监控，不改变支付状态和原有回调重试规则。支付成功不等于商户回调成功；缺少上游通知也不能由该告警推断。

每笔通知每个阶段持久化去重，首次绑定以及重新开启告警不集中补发之前的历史失败。Telegram 发送失败单独重试，最多 10 次；后台可查看机器人心跳、错误码及投递失败记录。网络超时可能发生“Telegram 已接收但确认丢失”，因此不能保证绝对不重复。

告警不包含签名、完整回调地址和原始错误响应。详细原因需登录后台查看。机器人故障不会阻塞支付、结算或商户回调。

上线验收

绑定后请用真实商户工作群确认普通成员可查询本商户人民币余额，但不能查询订单或其他商户，再安排受控的回调失败和恢复验收。未绑定群不会发送商户数据，自动化测试不替代真实群验收。

Telegram 官方说明：机器人作为群管理员时，查询其他成员身份的能力才有保证。