biz-api-cloud-zax/db/20260918_hard_coffee_h5_api.md

咖啡机(屋里咖啡)H5支付页对接契约 - 一期饭卡支付

交付时间: 2026-09-18。H5 页面在前端仓库(biz_zax_app_cloud)实现,本文档为后端接口契约。

1. 页面入口与二维码 URL

用户在咖啡机上选择饮品后,机器展示二维码,URL 由屋里咖啡后台配置,指向我方 H5:

https://www.pjzhhq.cn/h5/#/pages/pay/coffee-pay?order_no={厂商订单号}

• order_no: 厂商订单号,19 位数字(测试环境 18 位)。
• 屋里咖啡后台的「支付跳转 URL 模板」按上述地址配置,占位符以厂商后台实际支持为准。

2. 接口(匿名,无需登录态)

网关前缀: https://www.pjzhhq.cn/api/hard (StripPrefix 后到 hardware 服务)。 所有响应为统一 R<T> 结构 {code:0, msg, data},code != 0 时展示 msg。

2.1 拉取订单信息

GET /api/hard/hard-coffee/order-info?orderNo={order_no}

响应 data:

字段	类型	说明
orderId	long	本地订单id,支付时回传
orderNo	string	厂商订单号
product	string	产品名称
img	string	产品图片完整链接
isCold	string	1冷饮 0热饮
price	int	价格(分)
priceYuan	string	价格(元,两位小数),直接展示
machineName	string	机器号
paid	boolean	是否已支付。true 时展示"已支付"并禁止再次支付
remainSeconds	long	支付剩余秒数(下单起5分钟),用于倒计时,超时提示重新发起

页面逻辑: 进入页面即调用;paid=true 显示已支付结果;remainSeconds<=0 显示超时。

2.2 饭卡支付(卡号即扣款)

POST /api/hard/hard-coffee/card-pay
Content-Type: application/json

{ "orderId": 1234567890, "cardNo": "0123456789" }

• 卡号即身份,与消费机刷卡一致,无密码。失败原因见 msg(非本单位饭卡/余额不足/订单已超时/订单已支付等)。

响应 data:

字段	类型	说明
orderId	long	本地订单id
orderNo	string	厂商订单号
name	string	支付人姓名(脱敏展示由前端决定)
cardNo	string	饭卡卡号
balanceYuan	string	支付后余额(元)

支付成功后展示"取咖啡"提示;出餐由后端回调厂商完成,前端无需轮询(如需兜底可再次调用 2.1 查看 paid)。

3. 注意事项

1. 匿名接口无租户头,后端通过机器号自动定位租户,前端无需传 TENANT-ID。
2. 同一订单支付窗口 5 分钟,过期后在咖啡机重新发起生成新二维码。
3. 防重复提交由后端并发锁保证,前端支付按钮加 loading 即可。
4. 一期仅饭卡支付;微信/支付宝支付为二期,接口预留扩展。