sky121113
8ee14eaa29
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 48s
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. 待確認事項 (To-be-confirmed)
|
||
|
||
### 4.1 邏輯關聯與超時
|
||
1. **發票缺失標記**：若收到 B600 (金流) 但在預設時間內（如 5 分鐘）未收到 B601，後台是否應將該訂單標記為「發票缺失」以供巡檢。
|
||
2. **重試機制**：機台端在 B601 呼叫失敗時的緩存與重傳策略。
|