線上續費開票介面

本文件包含線上續費流程中供前端使用的五個開票介面：開票抬頭查詢、開票申請提交、單訂單及批量開票進度查詢和電子發票下載。

通用約定

• 介面前綴：/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 下載或預覽發票。