繁花惠 / 优花速达开票

分销小程序发票中心（花店端）+ 运营后台平台开票管理。所有接口均为 POST + JSON，一个接口一张卡片，每张卡片按「用途 → 请求 → 响应 → 示例」排。

接口一览

本版变化（相对 2026-07-27 版，没接过旧版可跳过）

• 新增分组列表接口。「我的发票」页改用它渲染，不再从一键预览拼分组。
• 一键提交返回结构变了：data 从 long 变为 { applicationId, receiptIds }。成功判定用 code === 0。
• 一键预览新增 receiptPreview（收据部分），发票总额 totalAmount 不含它。
• 状态文案改口径：待申请开票 / 待商家开票 / 已开发票 / 已逾期。直接展示后端 statusDesc。
• 时间窗统一：分组列表、组内订单、一键开票池默认都是「确认收货 3 个月内」。
• 发票与收据可分开申请（2026-09-09）：预览 / 提交新增 applyType，1 仅发票、2 仅收据，不传维持原一键全量；金额互斥，分开不影响任何计算。
• 收据改由平台出具、与发票分屏：分销花店的收据页只有列表 / 详情 / 凭证，申请入口在发票中心「可开收据」Tab 的「去开收据」；收据接口新增 partnerId、itemType。
• 平台项 supplierId 不再恒为 0（挂内部开票公司账号）。判类型一律用 invoiceItemType。
• 后台：平台开票列表加所属平台筛选；发票申请列表加开票类型 / 所属平台筛选与返回（供应商开票列表不变）；物流商配置加可开票标识。

通用约定

请求

• 全部 POST，Content-Type: application/json，无参数也传 {}。
• 小程序端：沿用花店登录态；purchaserId 后端从登录态取，前端不传。前缀 /invoice（发票）、/receipt（收据）。
• 后台端：沿用运营后台登录态。前缀 /invoice/manage（开票管理）、/logistics（物流商配置）。
• 时间格式与各端现有接口一致（示例按 yyyy-MM-dd HH:mm:ss）。金额单位元，两位小数。

响应与分页

枚举

invoiceItemType 开票项目类型，两端通用

partnerId 所属平台，同订单 partner_id

0 寻梦批发 · 3 优花速达 · 140 繁花惠 · 其他值 → 后台文案「其他分销商」

分组内订单状态 status 与筛选 statusTab

开票记录状态 request 维度

其他

• voucherType：1 发票
• 收据 status：0 申请中 / 1 已开具
• 收据明细 itemType：0 花材款 / 2 干线物流费
• 凭证 actionType：2 预览 / 3 下载

业务规则（前端需要感知的）

页面与接口对应

金额拆分 一笔订单各项之和 = 用户实付

规则

• 无勾选。申请范围由后端算：确认收货 3 个月内的全部可申请订单，按「订单 × 开票项」剔除已被未撤销申请占用的部分。
• 某项金额为 0 的订单不出现在该分组。线上物流结算数据尚未导入，此时干线物流费为 0、金额进平台服务费。
• 存量：上线前走老流程开过票的分销订单整单锁定，各分组显示“待商家开票”。
• 逾期：超 30 天未上传变“已逾期”，花店得 2% 寻梦币补偿；运营仍可代上传。平台三项不进逾期扣款、不发短信。
• 转代开只对花材款：原记录变“已转代开”，新生成一条“待商家开票”承接。
• 收据不可撤销。发票记录撤销后金额回到可开票池。
• 同一花店在两个平台都有单时，收据按平台各一张，receiptIds 多条。

小程序 · 发票 · 前缀 /invoice

POST/invoice/partner/group/list可开票分组列表

新增

「我的发票」页数据源。按出具主体 × 费用类型分组：每个可开票供应商一组，平台三项各一组。不分页，每组自带订单列表。无数据返回空数组。

请求

响应 data 为数组

示例

// 请求
{ "statusTab": 1 }
// 响应
{
  "code": 0, "msg": "success",
  "data": [
    { "invoiceItemType": 0, "supplierId": 1021, "issuerName": "云南甲花卉", "voucherType": 1,
      "groupName": "云南甲花卉·鲜切花", "totalAmount": 356.00, "orderCount": 2,
      "orderList": [
        { "orderSn": "XM2026090112345", "roundNo": "2026-09-01", "amount": 200.00,
          "createTime": "2026-09-01 12:00:00", "status": 0, "statusDesc": "待申请开票", "canApply": true },
        { "orderSn": "XM2026082898765", "roundNo": "2026-08-28", "amount": 156.00,
          "createTime": "2026-08-28 09:30:00", "status": 1, "statusDesc": "待商家开票", "canApply": false }
      ] },
    { "invoiceItemType": 1, "supplierId": 0, "issuerName": "花序公司", "voucherType": 1,
      "groupName": "供应链服务费", "totalAmount": 48.00, "orderCount": 2, "orderList": [ … ] },
    { "invoiceItemType": 3, "supplierId": 0, "issuerName": "花古德公司", "voucherType": 1,
      "groupName": "平台服务费", "totalAmount": 63.50, "orderCount": 2, "orderList": [ … ] }
  ]
}

POST/invoice/partner/group/order/list组内订单列表

变更：默认时间窗改为确认收货 3 个月内

单个分组下的订单，不分页。分组卡片已自带 orderList，本接口用于只刷新某一组的场景。

请求

响应 data 为数组，字段同分组列表的 orderList 元素

示例

{ "invoiceItemType": 0, "supplierId": 1021, "statusTab": 2 }
{ "invoiceItemType": 3 }

POST/invoice/partner/apply/preview一键开票预览

变更：新增 receiptPreview、applyType

返回发票部分总额与拆分、收据部分预览。applyType 控制只算哪一半：「可开票」Tab 传 1，「可开收据」Tab 传 2，不传两半都算。无可开票内容时 totalAmount 为 0、supplierBreakdown 为空数组、receiptPreview 为 null，不报错。用作底栏数据源。

请求 body 可为空

响应 data 为对象

示例

{
  "code": 0, "msg": "success",
  "data": {
    "totalAmount": 467.50, "orderCount": 2,
    "supplierBreakdown": [
      { "invoiceItemType": 0, "supplierId": 1021, "supplierName": "云南甲花卉", "amount": 356.00, "orderCount": 2, "quotaSufficient": true },
      { "invoiceItemType": 1, "supplierId": 0, "supplierName": "供应链服务费", "amount": 48.00, "orderCount": 1, "quotaSufficient": true },
      { "invoiceItemType": 3, "supplierId": 0, "supplierName": "平台服务费", "amount": 63.50, "orderCount": 1, "quotaSufficient": true }
    ],
    "receiptPreview": {
      "totalAmount": 120.00, "orderCount": 1,
      "flowerAmount": 120.00, "flowerRoundText": "2026.09.01 共一个场次",
      "logisticsAmount": 0, "logisticsRoundText": ""
    }
  }
}

POST/invoice/partner/apply/submit一键开票提交

变更：data 从 long 变为对象、新增 applyType

只传抬头，范围由后端算（与预览一致）。发票与收据可以分开申请：「去开票」传 applyType=1 只提交发票申请（自动拆多条开票记录）；「去开收据」传 applyType=2 只按平台各开一张收据。不传则两者一次全做。成功后按入口分别跳开票记录页 / 收据列表页。

请求

响应 data 为对象

示例

// 去开票
{ "invoiceTitleId": 88, "applyType": 1 }
{ "code": 0, "msg": "success", "data": { "applicationId": 5127, "receiptIds": [] } }
// 去开收据
{ "invoiceTitleId": 88, "applyType": 2 }
{ "code": 0, "msg": "success", "data": { "applicationId": null, "receiptIds": [ 903 ] } }

业务错误 msg 直接展示

POST/invoice/partner/request/list开票记录列表

变更：状态文案

开票记录页数据源，request 维度分页，按申请时间倒序。

请求

响应 data.records 元素

示例

{ "pageIndex": 1, "pageSize": 10, "status": null }

POST/invoice/partner/request/detail开票记录详情

不变

票据详情页数据源。含列表的全部字段，另加票据类型与所含订单。下载直接用 invoiceUrl。

请求

响应 data 为对象，列表字段之外新增

示例

{ "requestNo": "REQ20260901xxxx" }

POST/invoice/partner/request/cancel撤销开票记录

变更：新增错误文案

按单条开票记录撤销，仅 canCancel=true 的可撤。撤销后金额回到可开票池。收据不可撤销。

请求

响应

业务错误

示例

{ "requestNo": "REQ20260901xxxx" }

小程序 · 收据 · 前缀 /receipt

分销收据由平台出具，与发票分屏。分销花店的收据页只有「列表 → 详情 → 凭证」，没有可开收据订单列表和勾选申请（/receipt/order/list、/receipt/apply/* 仅寻梦批发花店使用）。收据 PDF 正文固定两行：「鲜切花」和「物流运输」。

POST/receipt/application/list我的收据列表

变更：新增 partnerId

请求

响应 data.records 元素

示例

{ "pageIndex": 1, "pageSize": 10 }

POST/receipt/application/detail收据详情

变更：新增 partnerId、itemType

请求

响应 data 为对象

示例

{ "id": 903 }

POST/receipt/application/voucher收据凭证预览/下载

不变

返回 PDF 地址并记录操作日志。

请求

响应 data 为对象

示例

{ "id": 903, "actionType": 2 }

运营后台 · 前缀 /invoice/manage、/logistics

POST/invoice/manage/partnerPlatform/list平台开票列表

变更：新增 partnerId 筛选与 platformName

数据源为 invoiceItemType 为 1、2、3 的平台开票记录。响应带三格金额汇总；汇总跟随除状态以外的筛选条件，切状态 Tab 不变。

请求 均可选

响应 data 为对象

示例

{ "index": 1, "size": 20, "searchCount": true, "invoiceItemType": 2, "partnerId": 140, "status": 0 }

POST/invoice/manage/partnerPlatform/sendNo/list物流费关联发货单

不变

仅干线物流费记录（invoiceItemType=2）可调，按发货单号聚合。其他类型报“该开票记录不是物流费类型”。

请求

响应 data 为数组

示例

{ "id": 8801 }

POST/invoice/manage/partnerPlatform/order/list关联订单列表

不变

仅供应链服务费（1）、平台服务费（3）记录可调。

请求

响应 data 为数组

示例

{ "id": 8802 }

POST/invoice/manage/request/list发票申请列表

变更：新增 2 个筛选、4 个返回字段

既有接口。本次只加字段，其余行为不变。

请求

响应 data.records 元素，只列本次新增字段，其余不变

示例

{ "index": 1, "size": 20, "invoiceItemType": 0, "partnerId": 3 }

POST/invoice/manage/supplier/request/list供应商开票列表

不变

既有接口，本次 请求与返回都没有改动，前端无需处理。开票类型 / 所属平台的筛选与返回只加在 发票申请列表 上，平台三项（供应链服务费 / 干线物流费 / 平台服务费）的运营视图走 平台开票列表。

POST/logistics/list/costConfig物流商列表

变更：新增 isInvoiceMarked

既有接口。物流商是否为「合作可开票物流商」决定分销订单的干线物流费开发票还是进收据。本次只加一个字段。

请求 新增字段，其余不变

响应 data.records 元素，新增字段

示例

{ "index": 1, "size": 20, "isInvoiceMarked": 1 }

POST/logistics/add/costConfig物流商新增/编辑

变更：新增 isInvoiceMarked

既有接口，新增与编辑共用。本次只加一个字段。

请求 新增字段，其余不变

响应

与现有接口一致。

对应后端分支 xiaofun/xm-bulky-mall-suppiler，applyType 拆分 2026-09-09 开发完成待上测；其余 2026-09-04 已上测（purchaser：bulky-test/purchaser，admin：bulky-test/admin）。接口行为与文档不符时以 knife4j 在线文档为准并反馈后端。