API ドキュメント

Bullmark API を、あなたのバックエンドへ.

面は二つ、キーは一つ。 ledger API はあなたが触れてよいウォレットのクレジットと現金を読み、動かします。 voucher API は自社ブランドのバウチャーを自分の決済で検証し、利用処理します。すべての書き込みは冪等で、すべての移動は封印されます。ガイド・SDK・バウチャーの完全なリファレンスは developer.bullmark.net にあります。

最初の呼び出しの前に

ベース URL は 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 に紐づいていなければならず、リクエストにはそのバインディングと発行者が一致する Axowl 署名のパートナーアサーションを Authorization: Bearer … として載せる必要があります。キーごとに取引あたりの上限があり、超えると 403 です。読み取りと利用処理にはどちらも不要です。

冪等性

すべての書き込みは refId — あなた自身の参照番号 — を取ります。同じ refId を二度送ると、同じ行が idempotentReplay: true とともに返り、二度目の移動は決して起きません。安心して再試行してください。

オーナーキー

ウォレットはオーナーキーで名指されます: 人は enduser:{guid} 、会社は org:{guid} 、ブランドは brand:{slug} 。クレジットはブランドごとなので、ほとんどの呼び出しは owner と brand を一緒に取ります。プラットフォーム自身のクレジットは __bullmark ブランドの下にあります。

レート制限

キーごとに 120 requests per minute 、固定ウィンドウ、キューなし。超えると何も行われないまま 429 が返ります。読み書きは同じウィンドウを共有します。

エラー

エラーは error 文字列と、役に立つ場合はその背後の数値を含む JSON です。 400 不正な入力 · 401 キーなし・誤ったキー・スコープ不足 · 402 残高不足（ balance と required 付き） · 403 あなたのものではない、または上限超過 · 404 存在しない · 409 状態が拒否。

Ledger — /partner/ledger

通帳は一つ、その下の表は二つ: クレジット行と現金行。履歴はその二つを新しい順に統合し、各行は bucket （ cash 、 non-refundable 、…）で自分が何かを、 kind でどの種類の移動かを述べます。

ルート

スコープ

何をするか

GET /partner/ledger/balance?owner=&brand=

ledger.read

あるブランドでのウォレット1つのクレジット・現金残高。 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

あなたのブランドのバウチャーのうち、最大8人のエンドユーザーが保有するもの。

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 が何を意味するのか、そしてお金がどちら向きに動くのか。

キーが必要ですか？

キーは登録法人に発行されます。スタートアップを掲載し、連携に必要なスコープを指定してパートナーキーを申請してください。

スタートアップを掲載 → 8ステップすべてを見る

Bullmark API を、 あなたのバックエンドへ.

最初の呼び出しの前に

Ledger — /partner/ledger

Vouchers — /partner/vouchers

キーが必要ですか？

Bullmark API を、あなたのバックエンドへ.