商家 App：电子发票 PDF 打印接入

本功能是 ezPay 电子发票证明联，与 /getOrderPrintInfo 餐点小票不同。后端负责版式、金额和条码，App 只负责保存、展示 PDF 和调用打印机。

接口前缀：/system/orderShOprate。请求头传商家登录 token；订单 ID 使用 pos_order.id。普通商家、夜市、摊位、授权子账号都沿用现有订单权限。

1. 查看明细及打印次数

GET /getInvoicePrintDetail?orderId=3173

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "invoiceNumber": "AB12345678",
    "printCount": 0,
    "fileName": "AB12345678-detail.pdf",
    "contentType": "application/pdf",
    "pdfBase64": "JVBERi0..."
  }
}

pdfBase64 是无 Data URL 前缀的 Base64；解码成 PDF 文件后查看。
这是交易明细，没有兑奖二维码，不是证明联。重复查看/打印明细不增加 printCount。
printCount=0 显示“打印发票”；大于 0 显示“申请补印”。只统计我们系统，不同步 ezPay 后台历史。
无纸本资格、未开立、已作废或发票商查询失败，会返回业务错误；直接展示 msg，不要改用订单金额拼发票。

2. 首次打印证明联

用户点击打印时调用 POST /printInvoice：

{
  "orderId": 3173,
  "requestId": "78490c8a-6755-4a49-bd36-2b661f46f653",
  "reprint": false
}

requestId：每次打印意图生成一个 UUID，调用前保存。超时、断网或丢失响应时必须带原值重试；同一请求号不能换订单发票、补印参数或操作账号。按钮提交中禁用，避免连点。

成功返回：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "printJobId": 123,
    "invoiceNumber": "AB12345678",
    "printSequence": 1,
    "reprint": false,
    "fileName": "AB12345678-1.pdf",
    "contentType": "application/pdf",
    "pdfBase64": "JVBERi0...",
    "reversePdfBase64": "JVBERi0..."
  }
}

pdfBase64：正面打印文件。个人 B2C 第1页为证明联，第2页为交易明细；分开裁切。B2B 为同一长页，明细接续打印，不能中途裁切。
reversePdfBase64：57×90mm 背面参考文件，含兑奖说明及领奖收据。不要在正面后顺序打印它。使用已有合规预印背面的纸卷时无需打印此文件；其他纸张需确保相应背面符合要求。
纸宽57mm，证明区域高90mm。按100%实际尺寸输出，关闭“适应页面”、缩放、额外页眉页脚。不得自行改二维码、字体、顺序或裁切证明区域。
服务端成功生成并保存 PDF 就增加次数；不是打印机完成出纸回执。App 不提供“打印失败重置为首次”功能。原请求重试只用于恢复同一次未收妥的响应，不能用缓存原件反复打印。

3. 补印

仅适用于原联记载不清等法定情形，并需核对内容、保留原联。不是重复点击就能再出一份原件。

{
  "orderId": 3173,
  "requestId": "a25ece72-8030-475d-97c9-3c49ce308d26",
  "reprint": true,
  "reprintReason": "原证明联字迹不清，已核对发票内容一致",
  "originalAvailable": true,
  "contentsVerified": true
}

原因必填，最多200字；两个确认必须为 true。
成功后 printSequence>=2、reprint=true，PDF 标题自动加“補印”，App 无需拼字。
首次尚未申请时不能直接补印；已经申请过原件不能再 reprint=false。出现并发冲突时刷新打印次数并展示错误，不自动改成补印重试。
作废票不可打印；重开后的新发票重新计数，必须使用新的 requestId。

上线联调

开发者先手动执行 updatesql/sql.md 的“2026-10-30 商家App电子发票证明联打印”建表段，再发布后端。
ezPay 纸本 B2C/B2B 各验证一笔，核对真实日期、总额、商品和税额；查询失败时不能出纸。
真机验证中文字体、57mm实际尺寸、明细裁切，以及左右二维码/Code39均可读取。
首次、超时原请求重试、跨设备重复点击、补印、作废/重开、越权访问均需联调。
正式使用前完成适用的样张、二维码解密验证和纸张验收；本地生成 PDF 不等于已获核准。

本期不包含 App 页面、蓝牙/网络打印驱动或载具发票转纸本。普通查看继续使用交易明细，首次打印接口不要在进入详情页时自动调用。

frontend-app-printing.md 4.4 KB Historie Surový

商家 App：电子发票 PDF 打印接入

1. 查看明细及打印次数

2. 首次打印证明联

3. 补印

上线联调

frontend-app-printing.md 4.4 KB

Historie Surový