sky121113
773396fc90
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 52s
50 lines
1.9 KiB
Markdown
50 lines
1.9 KiB
Markdown
# 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. 待確認事項 (已結案)
|
||
|
||
所有關於發票關聯邏輯與重試機制的技術決策已於 2026-03-12 完成確認：
|
||
1. **發票缺失標記**：系統不需針對 B600 與 B601 的到達時差進行「發票缺失」自動標記。
|
||
2. **重試機制**：機台端呼叫失敗時不需額外的緩存與重傳策略（維持基本回報邏輯）。
|