star-cloud/docs/b601_technical_spec.md

B601 API (發票資訊回傳) 技術規範與執行指南

本文件定義 B601 API 的技術實作規範，用於紀錄每筆訂單對應的電子發票資訊。

---

1. 業務流程與角色定義

1.1 系統角色

• 機台端：負責與電子發票系統對接、開立發票，並於取得發票號碼後將資訊回傳至雲端。
• 雲端 (Star Cloud)：僅負責紀錄 (Logging) 發票資訊，不涉及上傳傳財政部平台或寄送中獎通知。

1.2 串聯機制

• 關聯 ID：必須攜帶 B600 取得的 flow_id，以便將發票資訊正確掛載至對應的 orders。

---

2. 資料庫結構：invoices

為符合台灣發票規範，除了原始 PDF 欄位外，本系統將擴充相關稅務欄位：

欄位	說明	備註
order_id	訂單關聯 ID	透過 flow_id 對應
invoice_no	發票號碼	例：AB-12345678
invoice_date	發票日期
random_number	隨機碼	4 位數
love_code	愛心碼	捐贈碼
business_tax_id	公司統編	8 位數
carrier_id	載具編號	手機條碼或自然人憑證
carrier_type	載具類型
status	發票狀態	1:有效, 0:作廢

---

3. 發票作廢機制 (Invoice Voiding)

• 需求確認：當交易發生退款或特定失敗情境時，機台端需具備回報「發票作廢」的能力。
• API 實作：
  • 方法一：呼叫 B601 POST 時帶入 status = 0。
  • 方法二：新增 /api/app/B601/void 專屬端點（待後續細化）。

---

4. 待確認事項 (To-be-confirmed)

4.1 邏輯關聯與超時

1. 發票缺失標記：若收到 B600 (金流) 但在預設時間內（如 5 分鐘）未收到 B601，後台是否應將該訂單標記為「發票缺失」以供巡檢。
2. 重試機制：機台端在 B601 呼叫失敗時的緩存與重傳策略。