# 繁花惠 / 优花速达开票

> 分销小程序发票中心（分组列表 / 一键开票 / 收据分屏）+ 运营后台平台开票管理，含较 7 月版的变化清单

- 类型：前端对接
- 分类：分销开票
- 端：分销小程序 / 运营后台
- 后端服务：supplier / admin
- 更新：2026-09-18
- 网页版：https://doc.xfun.fun/partner-invoice-api

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

## 接口一览

| 端 | 路径 | 名称 | 状态 |
|----|----|----|----|
| 小程序 · 发票 | [`/invoice/partner/group/list`](#invoice-partner-group-list) | 可开票分组列表 | **新增** |
| 小程序 · 发票 | [`/invoice/partner/group/order/list`](#invoice-partner-group-order-list) | 组内订单列表 | **变更** 默认时间窗 |
| 小程序 · 发票 | [`/invoice/partner/apply/preview`](#invoice-partner-apply-preview) | 一键开票预览 | **变更** 新增 receiptPreview |
| 小程序 · 发票 | [`/invoice/partner/apply/submit`](#invoice-partner-apply-submit) | 一键开票提交 | **变更** 返回结构 |
| 小程序 · 发票 | [`/invoice/partner/request/list`](#invoice-partner-request-list) | 开票记录列表 | **变更** 状态文案 |
| 小程序 · 发票 | [`/invoice/partner/request/detail`](#invoice-partner-request-detail) | 开票记录详情 | 不变 |
| 小程序 · 发票 | [`/invoice/partner/request/cancel`](#invoice-partner-request-cancel) | 撤销开票记录 | **变更** 新增错误文案 |
| 小程序 · 收据 | [`/receipt/application/list`](#receipt-application-list) | 我的收据列表 | **变更** 新增 partnerId |
| 小程序 · 收据 | [`/receipt/application/detail`](#receipt-application-detail) | 收据详情 | **变更** 新增 partnerId、itemType |
| 小程序 · 收据 | [`/receipt/application/voucher`](#receipt-application-voucher) | 收据凭证预览/下载 | 不变 |
| 运营后台 | [`/invoice/manage/partnerPlatform/list`](#invoice-manage-partnerplatform-list) | 平台开票列表 | **变更** 新增平台筛选 |
| 运营后台 | [`/invoice/manage/partnerPlatform/sendNo/list`](#invoice-manage-partnerplatform-sendno-list) | 物流费关联发货单 | 不变 |
| 运营后台 | [`/invoice/manage/partnerPlatform/order/list`](#invoice-manage-partnerplatform-order-list) | 关联订单列表 | 不变 |
| 运营后台 | [`/invoice/manage/request/list`](#invoice-manage-request-list) | 发票申请列表 | **变更** 新增筛选/返回字段 |
| 运营后台 | [`/invoice/manage/supplier/request/list`](#invoice-manage-supplier-request-list) | 供应商开票列表 | 不变 |
| 运营后台 | [`/logistics/list/costConfig`](#logistics-list-costconfig) | 物流商列表 | **变更** 新增 isInvoiceMarked |
| 运营后台 | [`/logistics/add/costConfig`](#logistics-add-costconfig) | 物流商新增/编辑 | **变更** 新增 isInvoiceMarked |

## 本版变化（相对 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`）。金额单位元，两位小数。

#### 响应与分页

| 端 | 响应结构 | 分页入参 | 分页出参 |
|----|----|----|----|
| 小程序端 | `{ code: 0, msg, data }`，`code === 0` 为成功 | `pageIndex`（从 1 起）、`pageSize` | `data.records`、`data.total`、`data.current`、`data.pages` |
| 后台端 | `{ code, msg, data }`，与现有后台一致 | `index`、`size`、`searchCount` | `data.records`、`data.total`、`data.index`、`data.size` |

## 枚举

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

| 值 | 名称 | 出具主体 | 票据形式 |
|----|----|----|----|
| 0 | 花材款 | 可开票供应商，一个供应商一条 | 发票；不可开票供应商的花材走收据 |
| 1 | 供应链服务费 | 花序公司 | 发票 |
| 2 | 干线物流费 | 捷通公司 | 发票；不可开票物流商的运费走收据 |
| 3 | 平台服务费 | 花古德公司 | 发票 |

#### partnerId 所属平台，同订单 partner_id

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

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

| status | 文案       | 对应 statusTab |
|--------|------------|----------------|
| 0      | 待申请开票 | 2              |
| 1      | 待商家开票 | 4              |
| 2      | 已开发票   | 3              |
| 3      | 已逾期     | 5              |
| —      | 全部       | 1（默认）      |

#### 开票记录状态 request 维度

| 值  | 小程序文案 | 后台文案        | 说明                         |
|-----|------------|-----------------|------------------------------|
| 0   | 待商家开票 | 开票中 / 待开票 | 小程序 `canCancel=true`      |
| 1   | 已开发票   | 已开票          | `invoiceUrl` 非空            |
| 2   | 已逾期     | 已逾期          | 超 30 天未上传；运营可代上传 |
| 3   | 已撤销     | 已撤销          | 小程序「全部」不返回         |
| 4   | 已转代开   | 已转代开        | 仅花材款                     |

#### 其他

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

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

#### 页面与接口对应

| 页面 | 用到的接口 |
|----|----|
| 我的发票（分组卡片） | [可开票分组列表](#invoice-partner-group-list)；Tab 切换传 `statusTab`；单独刷某一组用 [组内订单列表](#invoice-partner-group-order-list) |
| 「可开票」Tab 底栏「去开票」 | [一键开票预览](#invoice-partner-apply-preview)（applyType=1）取发票总额 → 选抬头 → [一键开票提交](#invoice-partner-apply-submit)（applyType=1） |
| 「可开收据」Tab 底栏「去开收据」 | [一键开票预览](#invoice-partner-apply-preview)（applyType=2）取收据总额 → 选抬头 → [一键开票提交](#invoice-partner-apply-submit)（applyType=2） |
| 开票记录 | [开票记录列表](#invoice-partner-request-list) → [详情](#invoice-partner-request-detail)；`canCancel=true` 可 [撤销](#invoice-partner-request-cancel) |
| 收据（独立一屏） | [收据列表](#receipt-application-list) → [详情](#receipt-application-detail) → [凭证预览/下载](#receipt-application-voucher)；申请走上面的「去开收据」 |

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

| 项 | 取值 | 票据 |
|----|----|----|
| 花材款（可开票供应商） | 供货价 × 数量，固定不减 | 供应商开发票 |
| 花材款（不可开票供应商） | 供货价 × 数量，优惠溢出时倒扣 | 平台开收据，一行「鲜切花」 |
| 干线物流费 | min(发货单实际物流成本, 用户物流加价, 剩余额度)；取不到成本时为 0 | 可开票物流商 → 捷通公司发票；否则平台收据一行「物流运输」 |
| 供应链服务费 | min(打包服务费, 剩余额度) | 花序公司发票 |
| 平台服务费 | 剩余残差 | 花古德公司发票 |

#### 规则

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

## 小程序 · 发票 · 前缀 /invoice

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

**新增**

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

#### 请求

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| `statusTab` | int | 否 | 1 全部（默认）2 待申请开票 3 已开发票 4 待商家开票 5 已逾期 |
| `startTime` | datetime | 否 | 下单开始时间。不传默认确认收货 3 个月内 |
| `endTime` | datetime | 否 | 下单结束时间 |

#### 响应 data 为数组

| 字段 | 类型 | 说明 |
|----|----|----|
| `invoiceItemType` | int | 0 花材款 1 供应链服务费 2 干线物流费 3 平台服务费 |
| `supplierId` | long | 花材款为供应商 id；平台项为内部开票公司账号 id，未配置时 0 |
| `issuerName` | string | 出具主体：供应商名 / 花序公司 / 捷通公司 / 花古德公司 |
| `voucherType` | int | 固定 1 发票 |
| `groupName` | string | 分组名：「供应商名·鲜切花」或费用类型(如「平台服务费」，不带公司前缀) |
| `totalAmount` | decimal | 分组金额合计（当前 Tab 筛选后） |
| `orderCount` | int | 订单数（当前 Tab 筛选后） |
| `orderList` | array | 组内订单，按下单时间倒序 |
| `orderSn` | string | 订单号 |
| `roundNo` | string | 场次 |
| `amount` | decimal | 该订单在该分组的可开票金额 |
| `createTime` | datetime | 下单时间 |
| `status` | int | 0 待申请开票 1 待商家开票 2 已开发票 3 已逾期 |
| `statusDesc` | string | 状态文案 |
| `canApply` | boolean | 是否会进入一键开票范围，等价于 status==0 |

#### 示例

```text
// 请求
{ "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，本接口用于只刷新某一组的场景。

#### 请求

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| `invoiceItemType` | int | 是 | 0 花材款 1 供应链服务费 2 干线物流费 3 平台服务费 |
| `supplierId` | long | 条件 | 花材款必传，取分组列表的 supplierId；平台项不传 |
| `statusTab` | int | 否 | 同分组列表 |
| `startTime` | datetime | 否 | 下单开始时间。不传默认确认收货 3 个月内 |
| `endTime` | datetime | 否 | 下单结束时间 |

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

| 字段         | 类型     | 说明                                          |
|--------------|----------|-----------------------------------------------|
| `orderSn`    | string   | 订单号                                        |
| `roundNo`    | string   | 场次                                          |
| `amount`     | decimal  | 该订单在该分组的可开票金额                    |
| `createTime` | datetime | 下单时间                                      |
| `status`     | int      | 0 待申请开票 1 待商家开票 2 已开发票 3 已逾期 |
| `statusDesc` | string   | 状态文案                                      |
| `canApply`   | boolean  | 是否会进入一键开票范围                        |

#### 示例

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

> [!NOTE]
> 花材款不传 `supplierId` 报“花材款分组必须指定供应商”；分组不存在返回空数组。

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

**变更**：新增 receiptPreview、applyType

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

#### 请求 body 可为空

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| `applyType` | int | 否 | **新增** 不传 / 0 发票+收据；1 仅发票（收据部分 `receiptPreview` 返回 null）；2 仅收据（发票部分 `totalAmount` 0、`supplierBreakdown` 空） |

#### 响应 data 为对象

| 字段 | 类型 | 说明 |
|----|----|----|
| `totalAmount` | decimal | 发票部分总金额，不含收据 |
| `orderCount` | int | 发票部分覆盖订单数 |
| `supplierBreakdown` | array | 发票拆分明细 |
| `invoiceItemType` | int | 0 花材款 1 供应链服务费 2 干线物流费 3 平台服务费 |
| `supplierId` | long | 花材款为供应商 id；平台项为内部开票公司账号 id，未配置时 0 |
| `supplierName` | string | 供应商名，或「供应链服务费」这类分组名 |
| `amount` | decimal | 该项金额 |
| `orderCount` | int | 花材款为该供应商关联订单数；平台项固定 1 |
| `quotaSufficient` | boolean | 分销订单恒为 true |
| `receiptPreview` | object | 收据部分；无可开收据订单时 null |
| `totalAmount` | decimal | 收据总金额（多平台合计） |
| `orderCount` | int | 收据覆盖订单数 |
| `flowerAmount` | decimal | 花材收据金额 |
| `flowerRoundText` | string | 花材场次文案，如「2026.06.05-2026.09.01 共十个场次」；金额为 0 时空串 |
| `logisticsAmount` | decimal | 物流收据金额 |
| `logisticsRoundText` | string | 物流场次文案 |

#### 示例

```json
{
  "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": ""
    }
  }
}
```

> [!NOTE]
> 底栏：「可开票」Tab 用 `totalAmount` 置灰「去开票」；「可开收据」Tab 用 `receiptPreview.totalAmount` 置灰「去开收据」。

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

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

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

#### 请求

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| `invoiceTitleId` | long | 是 | 发票抬头 ID，来自 `/invoice/title/list`。只开收据也要传，收据购买人名称取自抬头 |
| `applyType` | int | 否 | **新增** 不传 / 0 发票+收据；1 仅发票；2 仅收据。其他值报「申请类型参数错误」 |

#### 响应 data 为对象

| 字段 | 类型 | 说明 |
|----|----|----|
| `applicationId` | long | 发票申请单 ID；没有可开发票项或 `applyType=2` 时 null |
| `receiptIds` | long\[\] | 收据申请 ID 列表，每个平台一张；没有可开收据项或 `applyType=1` 时空数组 |

#### 示例

```text
// 去开票
{ "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 直接展示

| msg | 含义 | 前端处理 |
|----|----|----|
| 没有可开票的订单 | applyType 不传 / 1 时没有可申请内容 | 预览为 0 时提前置灰 |
| 没有可开收据的订单 | applyType=2 时没有可开收据订单 | 预览 receiptPreview 为 null 时提前置灰 |
| 开票申请处理中，请勿重复提交 | 上一次提交还在处理 | 稍后重试 |
| 订单xxx已在开票申请中 | 并发兜底 | 重新拉预览 |
| 存在已开收据订单，请刷新后重试 | 收据部分被并发抢先 | 重新拉预览 |

> [!NOTE]
> 不传 applyType 时若发票成功、收据失败，接口整体返回失败，但发票申请已落库；用户重试只会补收据，不会重复申请发票。发票与收据金额互斥（可开票部分进发票，不可开票部分进收据），分开申请不改变任何金额。

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

**变更**：状态文案

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

#### 请求

| 字段        | 类型 | 必填 | 说明                                               |
|-------------|------|------|----------------------------------------------------|
| `pageIndex` | int  | 是   | 页码，从 1 开始                                    |
| `pageSize`  | int  | 是   | 每页条数                                           |
| `status`    | int  | 否   | 不传全部（不含已撤销）；0 待开票 1 已开票 2 已逾期 |

#### 响应 data.records 元素

| 字段 | 类型 | 说明 |
|----|----|----|
| `requestNo` | string | 申请单号 |
| `invoiceItemType` | int | 0 花材款 1 供应链服务费 2 干线物流费 3 平台服务费 |
| `supplierId` | long | 花材款为供应商 id；平台项为内部开票公司账号 id，未配置时 0 |
| `typeDesc` | string | 「供应商名·鲜切花」/ 供应链服务费 / 干线物流费 / 平台服务费 |
| `titleName` | string | 票据抬头 |
| `taxNumber` | string | 公司税号 |
| `requestAmount` | decimal | 申请开票金额 |
| `orderCount` | int | 关联订单数 |
| `createTime` | datetime | 申请时间 |
| `status` | int | 0 待商家开票 1 已开发票 2 已逾期 4 已转代开 |
| `statusDesc` | string | 状态文案 |
| `invoiceUrl` | string | 发票文件 URL，已开票时非空 |
| `canCancel` | boolean | 是否可撤销，仅待商家开票为 true |
| `deadline` | datetime | 开票截止时间 |

#### 示例

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

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

**不变**

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

#### 请求

| 字段        | 类型   | 必填 | 说明     |
|-------------|--------|------|----------|
| `requestNo` | string | 是   | 申请单号 |

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

| 字段              | 类型     | 说明                       |
|-------------------|----------|----------------------------|
| `invoiceTypeDesc` | string   | 票据类型，固定「电子发票」 |
| `orderList`       | array    | 所含订单                   |
| `orderSn`         | string   | 订单号                     |
| `roundNo`         | string   | 场次                       |
| `amount`          | decimal  | 该订单在本票据中的开票金额 |
| `createTime`      | datetime | 下单时间                   |

#### 示例

```json
{ "requestNo": "REQ20260901xxxx" }
```

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

**变更**：新增错误文案

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

#### 请求

| 字段        | 类型   | 必填 | 说明     |
|-------------|--------|------|----------|
| `requestNo` | string | 是   | 申请单号 |

#### 响应

| 字段   | 类型    | 说明      |
|--------|---------|-----------|
| `data` | boolean | true 成功 |

#### 业务错误

| msg | 前端处理 |
|----|----|
| 开票记录不存在 | 刷新列表 |
| 只有待开票的记录可以撤销 | 刷新列表 |
| 开票记录状态已变化，请刷新后重试 | 并发下供应商刚上传了发票或已被撤销，刷新列表 |

#### 示例

```json
{ "requestNo": "REQ20260901xxxx" }
```

## 小程序 · 收据 · 前缀 /receipt

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

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

**变更**：新增 partnerId

#### 请求

| 字段        | 类型     | 必填 | 说明              |
|-------------|----------|------|-------------------|
| `pageIndex` | int      | 是   | 页码，从 1 开始   |
| `pageSize`  | int      | 是   | 每页条数          |
| `status`    | int      | 否   | 0 申请中 1 已开具 |
| `startTime` | datetime | 否   | 申请开始时间      |
| `endTime`   | datetime | 否   | 申请结束时间      |

#### 响应 data.records 元素

| 字段 | 类型 | 说明 |
|----|----|----|
| `id` | long | 收据申请 ID |
| `receiptNo` | string | 电子收款凭证号 |
| `partnerId` | int | **新增** 所属平台：0 寻梦批发 3 优花速达 140 繁花惠 |
| `applyTime` | datetime | 申请时间 |
| `issueTime` | datetime | 开具时间 |
| `totalAmount` | decimal | 收据金额 |
| `orderCount` | int | 订单数 |
| `status` | int | 0 申请中 1 已开具 |
| `receiptUrl` | string | 收据 PDF 地址 |
| `orderSnList` | string\[\] | 订单编号列表 |

#### 示例

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

### POST /receipt/application/detail · 收据详情

**变更**：新增 partnerId、itemType

#### 请求

| 字段 | 类型 | 必填 | 说明        |
|------|------|------|-------------|
| `id` | long | 是   | 收据申请 ID |

#### 响应 data 为对象

| 字段 | 类型 | 说明 |
|----|----|----|
| `id` | long | 收据申请 ID |
| `receiptNo` | string | 电子收款凭证号 |
| `buyerName` | string | 购买人名称（取抬头） |
| `buyerCertificateNo` | string | 购买人证照号 |
| `partnerId` | int | **新增** 所属平台 |
| `totalAmount` | decimal | 收据金额 |
| `applyTime` | datetime | 申请时间 |
| `issueTime` | datetime | 开具时间 |
| `status` | int | 0 申请中 1 已开具 |
| `receiptUrl` | string | 收据 PDF 地址 |
| `orderList` | array | 订单快照 |
| `orderSn` | string | 订单号 |
| `roundNo` | string | 场次 |
| `receiptAmount` | decimal | 该订单收据金额 |
| `supplierCount` | int | 供应商数 |
| `confirmTime` | datetime | 确认收货时间 |
| `itemList` | array | 明细 |
| `itemType` | int | **新增** 0 花材款 2 干线物流费 |
| `orderSn` / `roundNo` | string | 同所属订单 |
| `supplierId` / `supplierName` | long / string | 分销收据不按供应商拆分，恒为 null，前端忽略 |
| `productName` | string | 「鲜切花」或「物流运输」 |
| `itemNum` | int | 数量，物流行固定 1 |
| `receiptAmount` | decimal | 金额 |

#### 示例

```json
{ "id": 903 }
```

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

**不变**

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

#### 请求

| 字段         | 类型 | 必填 | 说明          |
|--------------|------|------|---------------|
| `id`         | long | 是   | 收据申请 ID   |
| `actionType` | int  | 是   | 2 预览 3 下载 |

#### 响应 data 为对象

| 字段         | 类型   | 说明           |
|--------------|--------|----------------|
| `id`         | long   | 收据申请 ID    |
| `receiptNo`  | string | 电子收款凭证号 |
| `receiptUrl` | string | 收据 PDF 地址  |

#### 示例

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

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

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

**变更**：新增 partnerId 筛选与 platformName

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

#### 请求 均可选

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| `index` | int | 否 | 页码 |
| `size` | int | 否 | 每页条数 |
| `searchCount` | boolean | 否 | 是否统计总数 |
| `invoiceItemType` | int | 否 | null 全部 1 供应链服务费 2 干线物流费 3 平台服务费；2026-10-28 起支持 0 花材款，详见[花店开票列表新增花材款](/partner-invoice-admin-flower-api) |
| `partnerId` | int | 否 | **新增** null 全部 0 寻梦批发 3 优花速达 140 繁花惠 |
| `status` | int | 否 | null 全部 0 开票中 1 已开票 2 已逾期 3 已撤销 |
| `requestNo` | string | 否 | 申请编号，精确 |
| `titleName` | string | 否 | 发票抬头，模糊 |
| `taxNumber` | string | 否 | 税号，精确 |
| `purchaserPhone` | string | 否 | 花店手机号，精确 |
| `createTimeStart` | datetime | 否 | 申请时间起 |
| `createTimeEnd` | datetime | 否 | 申请时间止 |

#### 响应 data 为对象

| 字段 | 类型 | 说明 |
|----|----|----|
| `invoicingTotalAmount` | decimal | 开票中总金额 |
| `invoicedTotalAmount` | decimal | 已开票总金额 |
| `overdueTotalAmount` | decimal | 已逾期总金额 |
| `total` | long | 总条数 |
| `records` | array | 列表 |
| `id` | long | 记录 ID，关联单查询用 |
| `requestNo` | string | 申请单号 |
| `invoiceItemType` | int | 1 供应链服务费 2 干线物流费 3 平台服务费 |
| `invoiceItemTypeDesc` | string | 开票类型文案 |
| `partnerId` | int | **新增** 所属平台 |
| `platformName` | string | **新增** 寻梦批发 / 优花速达 / 繁花惠 / 其他分销商 |
| `purchaserId` | long | 花店 ID |
| `purchaserName` | string | 花店名称 |
| `purchaserPhone` | string | 花店手机号 |
| `titleName` | string | 发票抬头 |
| `taxNumber` | string | 税号 |
| `requestAmount` | decimal | 申请开票金额 |
| `orderCount` | int | 关联订单数（按实际订单号数） |
| `status` | int | 0 开票中 1 已开票 2 已逾期 3 已撤销 |
| `statusDesc` | string | 状态文案 |
| `invoiceUrl` | string | 发票 URL |
| `createTime` | datetime | 申请时间 |
| `uploadTime` | datetime | 上传时间 |
| `deadline` | datetime | 开票截止时间 |

#### 示例

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

> [!NOTE]
> 平台项由三家内部开票公司在供应商端自行上传发票；运营侧「代上传」沿用现有代上传接口，待开票和已逾期均可代上传。平台项不支持转代开，不展示该按钮。

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

**不变**

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

#### 请求

| 字段 | 类型 | 必填 | 说明                          |
|------|------|------|-------------------------------|
| `id` | long | 是   | 平台开票列表的 records\[\].id |

#### 响应 data 为数组

| 字段          | 类型    | 说明                     |
|---------------|---------|--------------------------|
| `sendNo`      | string  | 发货单号                 |
| `roundNo`     | string  | 场次                     |
| `expressName` | string  | 物流商名称，多个逗号分隔 |
| `amount`      | decimal | 该发货单物流费合计       |
| `orderCount`  | int     | 订单数                   |

#### 示例

```json
{ "id": 8801 }
```

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

**不变**

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

#### 请求

| 字段 | 类型 | 必填 | 说明                          |
|------|------|------|-------------------------------|
| `id` | long | 是   | 平台开票列表的 records\[\].id |

#### 响应 data 为数组

| 字段      | 类型    | 说明           |
|-----------|---------|----------------|
| `orderSn` | string  | 订单号         |
| `roundNo` | string  | 场次           |
| `amount`  | decimal | 该订单对应金额 |

#### 示例

```json
{ "id": 8802 }
```

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

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

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

#### 请求

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| `index` | int | 否 | 页码 |
| `size` | int | 否 | 每页条数 |
| `invoiceItemType` | int | 否 | **新增** null 全部 0 花材款 1 供应链服务费 2 干线物流费 3 平台服务费 |
| `partnerId` | int | 否 | **新增** null 全部 0 寻梦批发 3 优花速达 140 繁花惠 |
| `requestNo` | string | 否 | 申请单号 |
| `purchaserPhone` | string | 否 | 花店手机号 |
| `supplierId` | long | 否 | 供应商 ID |
| `supplierName` | string | 否 | 供应商名称 |
| `status` | int | 否 | 0 待开票 1 已开票 2 已逾期 3 已撤销 4 已转代开 |
| `registrationId` | long | 否 | 登记单 ID |
| `titleName` | string | 否 | 抬头名称 |
| `createTimeStart` | datetime | 否 | 创建时间起 |
| `createTimeEnd` | datetime | 否 | 创建时间止 |
| `uploadTimeStart` | datetime | 否 | 上传时间起 |
| `uploadTimeEnd` | datetime | 否 | 上传时间止 |

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

| 字段 | 类型 | 说明 |
|----|----|----|
| `invoiceItemType` | int | **新增** 0 花材款 1 供应链服务费 2 干线物流费 3 平台服务费；存量数据为 0 |
| `invoiceItemTypeDesc` | string | **新增** 开票类型文案 |
| `partnerId` | int | **新增** 所属平台；存量数据已回刷 |
| `platformName` | string | **新增** 寻梦批发 / 优花速达 / 繁花惠 / 其他分销商 |

#### 示例

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

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

**不变**

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

> [!NOTE]
> 本列表按开票记录的 supplier_id 查询，没有开票类型过滤：花序 / 捷通 / 花古德三个开票公司账号名下的平台项记录也会出现在这里，与真实供应商的花材款记录混排。若运营侧需要区分，另起需求再加字段。

> [!NOTE]
> 老的「开票订单列表」不再返回繁花惠 / 优花速达的订单，这两家全部走分销端一键开票，运营侧只做代上传与查看。

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

**变更**：新增 isInvoiceMarked

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

#### 请求 新增字段，其余不变

| 字段              | 类型 | 必填 | 说明                         |
|-------------------|------|------|------------------------------|
| `isInvoiceMarked` | int  | 否   | **新增** null 全部 0 否 1 是 |

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

| 字段              | 类型 | 说明               |
|-------------------|------|--------------------|
| `isInvoiceMarked` | int  | **新增** 0 否 1 是 |

#### 示例

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

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

**变更**：新增 isInvoiceMarked

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

#### 请求 新增字段，其余不变

| 字段              | 类型 | 必填 | 说明                                   |
|-------------------|------|------|----------------------------------------|
| `isInvoiceMarked` | int  | 否   | **新增** 0 否 1 是；编辑时不传保持原值 |

#### 响应

与现有接口一致。

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