# 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 呼叫失敗時的緩存與重傳策略。