商家 App 小票数据接入

接口使用请求头 token: 商家登录token，返回统一包装 {code:200,msg:"...",data:...}。接口只提供数据，连接打印机、排版和出纸由 App 实现。

订单小票信息

小票功能直接提供，无需查询启用状态或配置字典。

GET /system/orderShOprate/getOrderPrintInfo?ddId=991789716730512

ddId 是订单列表里的完整订单号 pos_order.dd_id，作为字符串传入，不是数据库主键 orderId、父单号或多店批次 ID。多店订单对每张子单的 ddId 分别读取，按对应门店打印。

返回字段（data）

字段	类型	说明
orderId / orderNo	long / string	订单主键 / 完整订单号，订单号按字符串处理
storeId / storeName	long / string	门店ID / 下单时店名快照（没有快照才取当前店名）
storeAddress / storeTelephone	string	当前门店地址 / 电话；可能为空
createTime	string	下单时间，`yyyy-MM-dd HH:mm:ss`，UTC+8
orderType	long	0外送、1自取、2堂食
selfDelivery	int	1商家自配送、0平台配送；老单可能为空
state	long	订单现有状态码，沿用商家订单页面解释
payType / payTypeName / payStatus	string / string / long	原訂單支付方式代碼 / 臺灣繁體付款方式名稱 / 原訂單支付狀態
pickUpNum / tableNo	long / string	取餐号 / 桌号；不适用时为空
delryTime / pickUpTime	string	原订单预约配送信息 / 自取时间，原样展示；可能为空
reservePhone	string	自取预留电话；可能为空
recipient	object或null	收货信息，仅 `{name,phone,address,addressDetail}`；无地址时为 null
items	array	商品快照，结构见下表，不需要再解析 JSON 字符串
foodAmount	int或null	原订单保存的商品总额；不根据当前菜单重算
amount	int或null	原订单应付总额，作为小票总额直接展示
freight	number	原配送费，包含客户实付和商家承担部分
customerDeliveryFee	number	客户实付配送费；老单无此快照时回退 freight，小票客户运费显示此字段
merchantDeliverySubsidy	number	商家承担的免运金额；老单返回0，与商品优惠分开
discounts	object	商品优惠分项和合计，结构见下文
remarks	string	整张子单备注

items[]

字段	类型	说明
foodId	long或null	商品ID；老单可能缺失
name	string	下单时商品名称
quantity	int	商品数量，取快照 number
price / otherPrice	number或null	快照商品价格 / 规格加价；保留原值，老单字段可能为空
specifications	string[]	取快照 ask，例如 `["小","中辣"]`；没有时为空数组
remarks	string或null	该商品备注，取快照 beizhu

discounts 字段均为 number，缺失按0返回：

platformCouponAmount：平台优惠券，取 discountAmount。
storeCouponAmount：门店优惠券，取 mdDiscountAmount。
platformPromotionAmount：平台促销，取 salesReduction。
storePromotionAmount：门店促销，取 mdSalesReduction。
pointsAmount：积分抵扣，取 pointsReduction。
totalAmount：上述五项之和，不包含商家运费补贴。

所有金额沿用订单单位（TWD元），不要再除100。amount 是权威订单总额；优惠只用于列示，不能再从 amount 扣一次。历史订单 price/otherPrice 不统一重算，App 不应靠逐行金额重建应付。没有存储税额，不返回固定为0的 tax。

关键处理

payTypeName 由後端按 payType 返回：1 貨到付款、2 信用卡、3 LINE Pay、4 現金、5 Apple Pay、6 線下轉帳；空值或未知代碼返回「未知付款方式」。App 小票可直接顯示此欄，仍應以 payType 判斷付款流程。

收货人、商品、规格、备注、金额取下单快照，不因用户改地址、商品改价或规格删除而改变。
到付 payType="1" 即使 payStatus=1，也不代表客户已经交现金，应标记到付，不能标记已收款。
用户、骑手和无权限的商家不能读取；分管账号受授权门店限制，摊主受绑定摊位限制。
商品或地址快照损坏会返回业务错误，App 提示错误，不打印空白小票。
本轮未接入自动打印、设备绑定、打印状态回执、去重或补打记录。App 不应把每一次推送都直接当作可重复出纸的命令；新订单触发、重试与设备能力需要后续单独完成。
这里是订单小票，不是电子发票证明联；不返回发票防伪码或打印发票凭证。

商家代客下单自动打印触发（2026-11-03 已确认，后端待实现）

代客订单支付方式	新订单通知与打印时机
现金 `payType=4`	订单创建事务提交成功后；不用等待确认收款
信用卡 `2`、LINE Pay `3`、Apple Pay `5`	服务端确认支付成功后；创建时不打印

以上是本轮新增规则，不代表后端或 App 已上线。到付 1 和线下转账 6 不纳入本轮现金/线上规则变更。

接入步骤：

监听商家新订单通知。沿用业务内容中的 ddId、type=0、pushType=1；原生新单通知按订单类型附带 NEW_ORDER_DELIVERY、NEW_ORDER_PICKUP 或 NEW_ORDER_DINE_IN 的 eventScene。不要把所有 type=0 消息都当新单，应结合商家新单消息场景识别，支付成功提示等其他消息不能再次打印。
用完整 ddId 请求本页小票接口，按返回的订单类型、真实付款状态、商品、金额和备注排版。
按完整订单号协调打印任务并持久化已打印记录；推送重复、消息列表刷新、通知点击，以及创建页本地触发与推送同时到达，都不能重复出纸。多设备需明确由哪个打印终端执行，单设备本地去重不能保证跨设备只打印一次。
打印失败保留可重试任务，不把收到通知或取到小票数据当作打印成功。用户明确补打与首次自动打印分开处理。

现金创建时 payStatus=0 仍可能尚未收款，不能在小票上自动标为“已付款”。通知可能延迟或丢失，App 应保留订单页手动打印入口；本轮后端不提供物理打印成功回执或跨设备打印锁。

frontend-app-integration.md 6.3 KB History Raw