API 文件
Bullmark API， 給你的後端.
兩個介面，一把金鑰。 ledger API 讀取並移動你有權觸碰之錢包裡的點數與現金。 voucher API 在你自己的結帳流程中驗證並核銷你自家品牌的票券。每一次寫入都是冪等的，每一次移動都被封存。指南、SDK 與完整的票券參考在 developer.bullmark.net 。
第一次呼叫之前
基礎網址是 https://api.bullmark.net 。每個請求都在 X-Api-Key 標頭中攜帶你的金鑰；金鑰以 bm_live_ 開頭，由 Bullmark 發放，並綁定到你的 Axowl 組織。金額就如你在 三種錢 中所預期的：點數列上的 amount 是以面額美元表示的 Brand Credit，現金列上則是 USD。
權限範圍
一把金鑰帶有以逗號分隔的權限清單。 ledger.read 讀取餘額與歷程。 ledger.debit 進行扣款、退款、提領。 ledger.grant 授予點數並記錄現金加值。 voucher.read 查看票券， voucher.redeem 保留、核銷、領取與釋放票券。超出金鑰權限的呼叫會得到 401 。
移動金錢
每一個會移動價值的寫入 — debit、refund、withdraw、auto-topup、grant、topup 以及 cash-refund 系列呼叫 — 都是 金錢呼叫 ：金鑰必須綁定到一個 Axowl org，而且請求還必須以 Authorization: Bearer … 攜帶一份由 Axowl 簽署、發行者與該綁定相符的夥伴斷言。每把金鑰都有單筆上限；超過即為 403 。讀取與核銷兩者都不需要。
冪等性
每一次寫入都接受一個 refId — 你自己的參考編號。送出相同的 refId 兩次，你會拿回同一行並帶著 idempotentReplay: true ，絕不會有第二次移動。請放心重試。
擁有者鍵值
錢包由它的擁有者鍵值命名：個人是 enduser:{guid} ，公司是 org:{guid} ，品牌是 brand:{slug} 。點數是按品牌分開的，所以大多數呼叫會同時帶上 owner 與 brand 。平台自己的點數在 __bullmark 這個品牌之下。
速率限制
每把金鑰 120 requests per minute ，固定時間窗，沒有佇列。超過就會得到 429 ，而且什麼都沒做。讀取與寫入共用同一個窗口。
錯誤
錯誤是 JSON，帶有一個 error 字串，以及在有用時附上背後的數字。 400 輸入有誤 · 401 沒有金鑰、金鑰或權限不對 · 402 餘額不足（附 balance 與 required ） · 403 不是你的，或超過上限 · 404 沒有這個東西 · 409 狀態不允許。
Ledger — /partner/ledger
一本存摺，底下兩張表：點數列與現金列。歷程會把兩者由新到舊合併；每一列以 bucket （ cash 、 non-refundable 、…）說明自己是哪一種，並以 kind 說明是哪一類移動。
路由
權限
它做什麼
GET /partner/ledger/balance?owner=&brand=
ledger.read
某個錢包在某個品牌的點數與現金餘額。 balance 是在那裡可以花的金額。
GET /partner/ledger/earnings?owner=
ledger.read
一家企業在旗下各品牌賺到的現金 — 各品牌明細與總計。
GET /partner/ledger/history?owner=&brand=&limit=
ledger.read
所有移動，由新到舊，附上餘額。省略 brand 就會得到那個人跨所有品牌的完整存摺，包含平台點數。
GET /partner/ledger/by-ref?refId=
ledger.read
某一個 refId 實際流出了什麼，點數與現金加總。用於按比例計算與對帳。
GET /partner/ledger/cash-topups?owner=&brand=
ledger.read
仍有價值的現金加值 — 現金退款可以動用的來源。
POST /partner/ledger/debit
ledger.debit
扣款。 {owner, brand, amount, refId, memo} ，amount 為正數。先用點數，若是 org 錢包則不足部分用現金補。不足時回 402 。
POST /partner/ledger/refund
ledger.debit
把一筆扣款以點數退回。請求主體與 debit 相同；該列是 Refund。
POST /partner/ledger/withdraw
ledger.debit
把 org 的現金退回它來自的那些卡片。僅限 org 錢包。
POST /partner/ledger/auto-topup
ledger.debit
當餘額低於下限時，以離線方式向已儲存的卡片扣款。卡片被拒回 402 ，付款服務商無法連上回 502 。
POST /partner/ledger/grant
ledger.grant
授予不可退還的點數。 {owner, brand, amount, refId, memo} 。
POST /partner/ledger/topup
ledger.grant
記錄某個 org 透過你的金流服務支付的現金加值。需要 providerRef — 沒有收據的現金列是一個主張，不是錢。
POST /partner/ledger/cash-refund
ledger.debit
退還現金加值的一部分。 {owner, brand, topUpRefId, amount, refId} 。
POST /partner/ledger/cash-refund/receipt
ledger.debit
在現金退款實際完成後，附上金流服務的收據（ providerRef ）。
POST /partner/ledger/cash-refund/reverse
ledger.debit
撤銷一筆沒有完成的現金退款。只能追加 — 帳本會保留兩行。
Vouchers — /partner/vouchers
票券是對一個價格的主張。驗證它、在你的結帳進行時保留它、在價值交付的瞬間核銷它、若付款失敗就釋放它。這一切都只針對 你自己 品牌的票券 — 金鑰的 org 綁定決定是哪些。
路由
權限
它做什麼
GET /partner/vouchers?holder=&holder=
voucher.read
你旗下品牌的票券，由最多八位終端使用者持有。
GET /partner/vouchers/{codeOrTicket}
voucher.read
驗證：目前狀態、核銷時應收的價格（ priceUsd ）、期限。想呼叫幾次都安全。
GET /partner/vouchers/{codeOrTicket}/events
voucher.read
票券的封存事件鏈 — 已領取、已保留、已核銷 — 並附封印驗證。
POST /partner/vouchers/reserve
voucher.redeem
為你的結帳鎖住它。 {code} → 一個帶到期時間的票證權杖。問兩次會拿到同一張票證。
POST /partner/vouchers/redeem
voucher.redeem
銷毀。 {ticket | code, externalRef, note} — externalRef 是你的訂單 id，也是讓重試變安全的東西。
POST /partner/vouchers/release
voucher.redeem
把保留中的票券還回去 — 付款失敗，或買家離開了。
POST /partner/vouchers/claim
voucher.redeem
透過推薦合約為終端使用者領取一張票券。 {code, productId, holder, holderEmail} 。
無需金鑰的驗證
任何人都可以在 GET /integrity/events/{entityType}/{entityId} 讀取某個實體的封存鏈 — 每個事件的雜湊、它與前一個的連結，以及這條鏈是否完整。不需要金鑰，也不需要登入：顧客、品牌或稽核人員就是這樣確認紀錄沒有被改寫的。
先讀這個
現金、Brand Credit 與 Bullmark Point →
amount 在每一種列上代表什麼，以及錢往哪個方向流動。
相關
費用與錢的去向 →
誰付什麼 — 好讓一行結算能對到分。
需要金鑰嗎？
金鑰只發給已登記的公司。刊登你的新創，並申請一把帶有你整合所需權限的夥伴金鑰。
刊登你的新創 → 看完整八個步驟