記錄規則¶

本頁說明交易資料在各種情境下的記法。欄位定義見交易推送。

金額恆等式¶

情況	恆等式
外加稅（`prices_include_tax = false`）	`total = subtotal − discount + tax + service_charge + tip + rounding`
內含稅（`prices_include_tax = true`）	`total = subtotal − discount + service_charge + tip + rounding`

不符時不拒收，於回應 warnings 列出，請檢查後更正（version +1 重送）。

套餐與選項¶

情境	記法
套餐	套餐本身一列（`product_type = COMBO`，帶套餐價）；`combo_components` 的每個品項（含主餐）都要各列一列，`parent_line_no` 指向套餐列，`unit_price = "0.00"`
選項加價	加價記在該列 `modifiers[].price_delta`，並已加進 `unit_price`。例：Fries 4.49 + Cheese Powder 0.75 → `unit_price = "5.24"`
套餐飲料升級	套餐列 `unit_price` 加上升級價差，modifiers 記錄升級選項；飲料子品項列記實際選到的飲料，`unit_price = "0.00"`

銷量統計

套餐內含品項（有 parent_line_no 的列）計入品項銷售數量，但不計金額；金額全部記在套餐列。

範例：套餐飲料升級¶

Jimbo 套餐（14.49）選椒鹽口味，飲料升級為珍珠奶茶（+3.50）：

套餐列 unit_price = 14.49 + 3.50 = "17.99"
modifiers 含 { "group_id": "COMBO_DRINK", "option_id": "DRK-BOBA", "price_delta": "3.50" }
飲料子品項列 product_id = "DRK-BOBA"、unit_price = "0.00"

[
  { "line_no": 1, "parent_line_no": null, "product_id": "COMBO-02", "product_name": "Master Jimbo Combo", "product_type": "COMBO",
    "quantity": "1", "unit_price": "17.99", "discount_amount": "0.00", "line_amount": "17.99", "tax_category": "STANDARD",
    "modifiers": [
      { "group_id": "FLAVOR_JIMBO", "option_id": "SALT_PEPPER", "option_name": "Taiwanese Salt & Pepper", "quantity": "1", "price_delta": "0.00" },
      { "group_id": "COMBO_DRINK",  "option_id": "DRK-BOBA",    "option_name": "Taiwan Boba Tea",          "quantity": "1", "price_delta": "3.50" }
    ], "is_voided": false },
  { "line_no": 2, "parent_line_no": 1, "product_id": "SGL-JIMBO",  "product_name": "Master Jimbo",    "product_type": "SINGLE",
    "quantity": "1", "unit_price": "0.00", "discount_amount": "0.00", "line_amount": "0.00", "tax_category": "STANDARD", "modifiers": [], "is_voided": false },
  { "line_no": 3, "parent_line_no": 1, "product_id": "SIDE-FRIES", "product_name": "Fries",           "product_type": "SIDE",
    "quantity": "1", "unit_price": "0.00", "discount_amount": "0.00", "line_amount": "0.00", "tax_category": "STANDARD", "modifiers": [], "is_voided": false },
  { "line_no": 4, "parent_line_no": 1, "product_id": "DRK-BOBA",   "product_name": "Taiwan Boba Tea", "product_type": "DRINK",
    "quantity": "1", "unit_price": "0.00", "discount_amount": "0.00", "line_amount": "0.00", "tax_category": "STANDARD", "modifiers": [], "is_voided": false }
]

換貨（EXCHANGE）¶

顧客拿已購買的商品回來，在同一張單裡退掉舊品、換成新品，只收（或退）差額。一張單裡同時有退回（負）和新購（正），金額方向依品項而定，所以標準交易型態清單中 EXCHANGE 的 amount_sign 為 null。

退回的舊品：quantity 為負數，line_amount 為負數。
換到的新品：quantity、line_amount 為正數。
original_trade_record_id 指向原交易。
差額：新品較貴時，用 payment_type = SALE 補收；較便宜時用 REFUND 退差額；等價時 payments 為空陣列。

例：原本買 Fries（4.49），換成 Cheese Corn（5.49），補收 1.00（未稅）：

"items": [
  { "line_no": 1, "parent_line_no": null, "product_id": "SIDE-FRIES",       "product_name": "Fries",       "product_type": "SIDE",
    "quantity": "-1", "unit_price": "4.49", "discount_amount": "0.00", "line_amount": "-4.49", "tax_category": "STANDARD", "modifiers": [], "is_voided": false },
  { "line_no": 2, "parent_line_no": null, "product_id": "SIDE-CHEESE-CORN", "product_name": "Cheese Corn", "product_type": "SIDE",
    "quantity": "1",  "unit_price": "5.49", "discount_amount": "0.00", "line_amount": "5.49",  "tax_category": "STANDARD", "modifiers": [], "is_voided": false }
]

Tip

POS 若沒有換貨功能，可拆成一筆 RETURN＋一筆 SALE 送出，總部報表結果相同。

退款與已日結營業日的異動¶

退款：business_date 維持原交易營業日；以 payments[].payment_type = REFUND 與 original_trade_record_id 表示，original_payment_id 指向原付款。
正負號：退貨／退款交易（RETURN、REFUND）的品項 quantity、line_amount，以及交易層 subtotal_amount、discount_amount、tax_amount、total_amount 等金額一律填負數；換貨（EXCHANGE）只有退回列為負數。付款 amount 仍填正數，方向由 payment_type = REFUND 表示。這樣日結時直接加總就是淨額。
已日結營業日的異動：重送該筆交易（version + 1，新的 batch_id），並重送該日 daily-close，控制總數更新為異動後的值。
同一筆交易收到多次：以 version 較大者為準；version 相同時以 last_modified_at 較晚者為準。

訂單類型與下單管道¶

order_type 描述取餐方式（內用／外帶／自取／外送），order_source 描述從哪裡下單。兩者分開記錄：

情境	order_type	order_source	order_source_detail
櫃台點餐內用	DINE_IN	POS	—
自助機點餐外帶	TO_GO	KIOSK	—
Uber Eats 外送	DELIVERY	DELIVERY_PLATFORM	UBER_EATS
官網下單到店自取	PICK_UP	WEB	—

order_source 建議使用代碼表的值；對應不到時可送自家原始值（自由字串，建議英文大寫＋底線）。不在表內的值照收、不報錯，總部統計時歸為「其他」。
未送 order_source（null 或省略）視為未知，不會預設為 POS。
order_type 的 ONLINE、KIOSK、THIRD_PARTY 屬於下單管道的概念，建議 order_type 填取餐方式，下單管道改以 order_source 表示。

收付款性質與付款工具¶

payment_type 描述這筆錢的性質（收款、退款、暫收…），payment_method 描述用什麼工具付（現金、信用卡、點數…）：

情境	payment_type	payment_method	payment_method_detail
刷 VISA 結帳	SALE	CREDIT_CARD	VISA
用會員點數折抵	SALE	LOYALTY_POINTS	例 `POINTS:500`
用禮物卡結帳	SALE	GIFT_CARD	—
預訂蛋糕先收現金訂金	DEPOSIT	CASH	—
取貨時以訂金折抵	DEPOSIT_APPLIED	CASH（沿用原訂金的工具）	—
退貨退回信用卡	REFUND	CREDIT_CARD	VISA

amount 一律填正數，收付方向由 payment_type 決定（見代碼表）；唯一例外是 ADJUSTMENT，可用負數表示扣減。
SALE、REFUND 為所有合作夥伴必須支援的基本值；其他值可使用建議代碼或自由字串。
使用自由字串時，請事先告知總部其意義與收付方向，否則總部無法判斷方向，該筆會列入人工確認並可能影響對帳。

會員¶

交易可選填 member_id，非會員或未綁定時為 null 或省略。
member_id 必須是合作夥伴會員系統內部的 ID（最長 50 字元），不得直接使用手機號碼、Email 或身分證號。
若會員系統以手機號碼為主鍵，請改送內部流水號，或送雜湊值（例 SHA-256 加 salt）。
個資限制詳見共通規範。