在线续费开票接口

本文档包含在线续费流程中供前端使用的五个开票接口：开票抬头查询、开票申请提交、单订单及批量开票进度查询和电子发票下载。

通用约定

• 接口前缀：/v3/console/package-renewal-order
• 接口需要使用控制台现有的登录态调用。用户身份和订单归属由服务端从登录态取得，无需且不能在请求中传入 unionId。
• POST 请求的 Content-Type 为 application/json。
• 成功响应统一为：{ "code": 200, "status": "success", "data": ... }。
• 失败响应的 status 为 error，错误详情位于 error.code 和 error.desc。前端应使用 status === "success" 判断业务成功。

订单列表开票资格字段

GET /v3/console/package-renewal-order/list 的每个订单项新增以下字段：

前端仅对 canApplyInvoice=true 的订单处理发票入口：NOT_APPLIED 显示“申请开票”，ISSUED 显示“下载发票”，其余状态展示申请进度。批量查询接口可用于局部刷新状态。

服务端状态同步

客户提交申请后，申请状态先为 PROCESSING。支付服务会按 ONLINE_INVOICE_POLL_INTERVAL_SECONDS 配置周期轮询 PCS/CRM，并将 ISSUED、FAILED、发票号码、PDF 地址和失败原因写回申请表；终态不再轮询。轮询采用数据库租约，避免多实例重复更新同一申请。前端不需要依赖页面刷新来推进状态。

1. 查询历史开票抬头

按公司名称查询 CRM 中已有的开票抬头，用于自动回填纳税人识别号。未查询到记录时返回空数组，不代表请求失败。

请求

GET /v3/console/package-renewal-order/invoice-title

请求示例：

GET /v3/console/package-renewal-order/invoice-title?companyName=广州保利云科技有限公司

响应数据

data 为数组：

响应示例：

{
  "code": 200,
  "status": "success",
  "data": [
    {
      "companyName": "广州保利云科技有限公司",
      "taxpayerId": "91440101MA5XXXXXXX"
    }
  ]
}

前端建议在用户完成公司名称输入后调用；若返回多条记录，允许用户选择对应的纳税人识别号。

2. 提交开票申请

为当前登录用户的在线续费订单提交电子发票申请。服务端会校验订单归属及可开票条件，并对同一订单的重复提交进行幂等处理。

请求

POST /v3/console/package-renewal-order/invoice-application

请求体字段：

请求示例：

{
  "orderId": "renewal_order_123456",
  "invoiceType": "VAT_NORMAL",
  "companyName": "广州保利云科技有限公司",
  "taxpayerId": "91440101MA5XXXXXXX"
}

响应数据

data 为开票申请信息：

响应示例：

{
  "code": 200,
  "status": "success",
  "data": {
    "orderId": "renewal_order_123456",
    "requestNo": "invoice_request_123456",
    "invoiceType": "VAT_NORMAL",
    "companyName": "广州保利云科技有限公司",
    "taxpayerId": "91440101MA5XXXXXXX",
    "amountCent": 99800
  }
}

示例仅展示核心字段；实际响应会按上表返回开票状态及发票信息。提交前应禁用重复点击；即使因网络重试重复提交，服务端也会按订单处理幂等。申请提交成功仅表示申请已受理。

3. 查询开票进度

查询当前登录用户指定续费订单的开票申请状态。接口会同步 CRM 中的最新状态，适合在申请提交后或订单详情页刷新时调用。

请求

GET /v3/console/package-renewal-order/invoice-application

请求示例：

GET /v3/console/package-renewal-order/invoice-application?orderId=renewal_order_123456

响应数据

data 的完整字段与第 2 节“提交开票申请”的响应数据一致。重点关注以下字段：

响应示例：

{
  "code": 200,
  "status": "success",
  "data": {
    "orderId": "renewal_order_123456",
    "requestNo": "invoice_request_123456",
    "statusName": "开票中",
    "invoiceApplicationStatus": "PROCESSING"
  }
}

订单尚未申请时，接口返回：

{
  "code": 200,
  "status": "success",
  "data": {
    "orderId": "renewal_order_123456",
    "invoiceApplicationStatus": "NOT_APPLIED"
  }
}

4. 批量查询开票进度

用于订单列表批量判断操作项。接口仅接受当前登录用户的、已支付且支持在线开票的续费订单；任一订单不满足条件时，整个请求返回业务失败。

请求

POST /v3/console/package-renewal-order/invoice-application/batch

请求体字段：

请求示例：

{
  "orderIds": [
    "renewal_order_123456",
    "renewal_order_654321"
  ]
}

响应数据

data 为以订单 ID 为键的对象。每个值均含有 invoiceApplicationStatus，其取值与订单列表字段一致；未申请的订单仅返回 orderId 和 invoiceApplicationStatus=NOT_APPLIED。

{
  "code": 200,
  "status": "success",
  "data": {
    "renewal_order_123456": {
      "orderId": "renewal_order_123456",
      "statusName": "已开票",
      "invoiceApplicationStatus": "ISSUED",
      "invoiceNo": "1234567890",
      "pdfUrl": "https://example.com/invoices/invoice_request_123456.pdf"
    },
    "renewal_order_654321": {
      "orderId": "renewal_order_654321",
      "invoiceApplicationStatus": "NOT_APPLIED"
    }
  }
}

订单列表展示规则：invoiceApplicationStatus=NOT_APPLIED 时显示“申请开票”；ISSUED 时显示“下载发票”；其他状态展示申请进度。不要使用 status 数值做前端分支。

5. 获取电子发票 PDF 下载地址

获取当前登录用户已开票续费订单的电子发票 PDF 地址。订单尚未开票时，服务端会返回业务失败响应。

请求

GET /v3/console/package-renewal-order/invoice-download

请求示例：

GET /v3/console/package-renewal-order/invoice-download?orderId=renewal_order_123456

响应数据

data 的完整字段与第 2 节“提交开票申请”的响应数据一致，其中 pdfUrl 为本接口的核心字段。前端取得 pdfUrl 后可在新窗口打开或按现有下载策略处理。

响应示例：

{
  "code": 200,
  "status": "success",
  "data": {
    "orderId": "renewal_order_123456",
    "requestNo": "invoice_request_123456",
    "invoiceNo": "1234567890",
    "pdfUrl": "https://example.com/invoices/invoice_request_123456.pdf"
  }
}

推荐调用顺序

1. 用户填写公司名称后，调用“查询历史开票抬头”回填或选择纳税人识别号。
2. 用户确认开票信息后，调用“提交开票申请”。
3. 在订单列表调用“批量查询开票进度”；在订单详情页或申请结果页调用“查询开票进度”，并依据 statusName、failureReason 展示状态。
4. 已开票后调用“获取电子发票 PDF 下载地址”，使用返回的 pdfUrl 下载或预览发票。