API-Dokumentation
Die Bullmark-API, für Ihr Backend.
Zwei Flächen, ein Schlüssel. Die ledger -API liest und bewegt Guthaben und Bargeld auf Brieftaschen, die Sie anfassen dürfen. Die voucher -API prüft und löst Gutscheine Ihrer eigenen Marken in Ihrem eigenen Checkout ein. Jeder Schreibvorgang ist idempotent und jede Bewegung versiegelt. Leitfäden, SDKs und die vollständige Gutschein-Referenz stehen auf developer.bullmark.net.
Vor dem ersten Aufruf
Die Basis-URL ist https://api.bullmark.net. Jede Anfrage trägt Ihren Schlüssel im Header X-Api-Key; Schlüssel beginnen mit bm_live_, werden von Bullmark ausgegeben und sind an Ihre Axowl-Organisation gebunden. Geld ist das, was Sie von den drei Geldarten erwarten: ein amount in einer Guthabenzeile ist Brand Credit in Dollar Nennwert, in einer Bargeldzeile ist es USD.
Scopes
Ein Schlüssel trägt eine kommagetrennte Scope-Liste. ledger.read liest Salden und Historie. ledger.debit belastet, erstattet, zahlt aus. ledger.grant teilt Guthaben zu und bucht Bar-Aufladungen. voucher.read sieht Gutscheine an, voucher.redeem reserviert, löst ein, beansprucht und gibt sie frei. Ein Aufruf außerhalb der Scopes des Schlüssels ist ein 401.
Geld bewegen
Jeder Schreibvorgang, der Wert bewegt — debit, refund, withdraw, auto-topup, grant, topup und die cash-refund-Aufrufe — ist ein Geldaufruf: Der Schlüssel muss an eine Axowl-Org gebunden sein, und die Anfrage muss zusätzlich eine von Axowl signierte Partner-Assertion als Authorization: Bearer … tragen, deren Aussteller zu dieser Bindung passt. Jeder Schlüssel hat ein Transaktionslimit; darüber ist es ein 403. Lesen und Einlösen brauchen beides nicht.
Idempotenz
Jeder Schreibvorgang nimmt eine refId — Ihre eigene Referenz. Senden Sie dieselbe refId zweimal, erhalten Sie dieselbe Zeile mit idempotentReplay: true zurück, nie eine zweite Bewegung. Wiederholen Sie ruhig.
Eigentümerschlüssel
Eine Brieftasche wird durch ihren Eigentümerschlüssel benannt: enduser:{guid} für eine Person, org:{guid} für ein Unternehmen, brand:{slug} für eine Marke. Guthaben gilt je Marke, daher nehmen die meisten Aufrufe owner und brand zusammen. Das eigene Guthaben der Plattform liegt unter der Marke __bullmark.
Ratenbegrenzung
120 requests per minute pro Schlüssel, festes Fenster, keine Warteschlange. Darüber erhalten Sie ein 429, ohne dass etwas geschehen ist. Lesen und Schreiben teilen sich das Fenster.
Fehler
Fehler sind JSON mit einer error -Zeichenkette und, wo nützlich, den Zahlen dahinter. 400 ungültige Eingabe · 401 kein Schlüssel, falscher Schlüssel oder Scope · 402 unzureichender Saldo (mit balance und required) · 403 nicht Ihres, oder über dem Limit · 404 nichts da · 409 der Zustand sagt Nein.
Ledger — /partner/ledger
Ein Sparbuch, zwei Tabellen darunter: Guthabenzeilen und Bargeldzeilen. Die Historie führt sie neueste zuerst zusammen; jede Zeile sagt in bucket (cash, non-refundable, …), welche sie ist, und in kind, welche Art von Bewegung.
Route
Scope
Was sie tut
GET /partner/ledger/balance?owner=&brand=
ledger.read
Guthaben- und Bargeldsaldo einer Brieftasche bei einer Marke. balance ist das, was dort ausgegeben werden kann.
GET /partner/ledger/earnings?owner=
ledger.read
Bargeld, das ein Unternehmen über seine Marken hinweg verdient hat — Zeilen je Marke und die Summe.
GET /partner/ledger/history?owner=&brand=&limit=
ledger.read
Bewegungen, neueste zuerst, mit den Salden. Lassen Sie brand weg für das gesamte Sparbuch der Person über alle Marken hinweg, inklusive Plattformguthaben.
GET /partner/ledger/by-ref?refId=
ledger.read
Was für eine refId tatsächlich abgeflossen ist, Guthaben und Bargeld summiert. Für Anteilsberechnung und Abstimmung.
GET /partner/ledger/cash-topups?owner=&brand=
ledger.read
Bar-Aufladungen, die noch Wert tragen — worauf eine Barerstattung zugreifen kann.
POST /partner/ledger/debit
ledger.debit
Ausgeben. {owner, brand, amount, refId, memo}, Betrag positiv. Zuerst Guthaben, den Rest bar bei einer Org-Brieftasche. 402, wenn es nicht reicht.
POST /partner/ledger/refund
ledger.debit
Guthaben für eine Belastung zurückgeben. Gleicher Body wie debit; die Zeile ist ein Refund.
POST /partner/ledger/withdraw
ledger.debit
Das Bargeld einer Org an die Karten zurückzahlen, von denen es kam. Nur Org-Brieftaschen.
POST /partner/ledger/auto-topup
ledger.debit
Die gespeicherte Karte außerhalb der Sitzung belasten, wenn ein Saldo unter die Untergrenze fällt. 402, wenn die Karte ablehnt, 502, wenn der Zahlungsanbieter nicht erreichbar ist.
POST /partner/ledger/grant
ledger.grant
Nicht erstattungsfähiges Guthaben zuteilen. {owner, brand, amount, refId, memo}.
POST /partner/ledger/topup
ledger.grant
Eine Bar-Aufladung buchen, die eine Org über Ihr Gateway bezahlt hat. Benötigt providerRef — eine Bargeldzeile ohne Beleg ist eine Behauptung, kein Geld.
POST /partner/ledger/cash-refund
ledger.debit
Einen Teil einer Bar-Aufladung erstatten. {owner, brand, topUpRefId, amount, refId}.
POST /partner/ledger/cash-refund/receipt
ledger.debit
Den Beleg des Gateways (providerRef) an eine Barerstattung anhängen, sobald sie durchging.
POST /partner/ledger/cash-refund/reverse
ledger.debit
Eine Barerstattung rückgängig machen, die nicht durchging. Nur anfügbar — das Buch behält beide Zeilen.
Vouchers — /partner/vouchers
Ein Gutschein ist eine Behauptung über einen Preis. Prüfen Sie ihn, reservieren Sie ihn, während Ihr Checkout läuft, lösen Sie ihn in dem Moment ein, in dem der Wert gegeben wird, geben Sie ihn frei, wenn die Zahlung fehlschlägt. Alles gegen Gutscheine Ihrer eigenen Marken — die Org-Bindung des Schlüssels sagt, welcher.
Route
Scope
Was sie tut
GET /partner/vouchers?holder=&holder=
voucher.read
Gutscheine Ihrer Marken, gehalten von bis zu acht Endnutzenden.
GET /partner/vouchers/{codeOrTicket}
voucher.read
Prüfen: der aktuelle Zustand, der bei Einlösung fällige Preis (priceUsd), die Laufzeit. So oft aufrufbar, wie Sie mögen.
GET /partner/vouchers/{codeOrTicket}/events
voucher.read
Die versiegelte Ereigniskette des Gutscheins — beansprucht, reserviert, eingelöst — mit Siegelprüfung.
POST /partner/vouchers/reserve
voucher.redeem
Ihn für Ihren Checkout sperren. {code} → ein Ticket-Token mit Ablauf. Zweimal fragen liefert dasselbe Ticket.
POST /partner/vouchers/redeem
voucher.redeem
Die Entwertung. {ticket | code, externalRef, note} — externalRef ist Ihre Bestell-ID und das, was einen erneuten Versuch sicher macht.
POST /partner/vouchers/release
voucher.redeem
Einen reservierten Gutschein zurückgeben — die Zahlung schlug fehl oder die Käuferin ging.
POST /partner/vouchers/claim
voucher.redeem
Einen Gutschein für eine Endnutzerin über einen Empfehlungsvertrag beanspruchen. {code, productId, holder, holderEmail}.
Prüfung, ohne Schlüssel
Jede und jeder kann die versiegelte Kette einer Entität unter GET /integrity/events/{entityType}/{entityId} lesen — den Hash jedes Ereignisses, seine Verbindung zum vorherigen und ob die Kette intakt ist. Kein Schlüssel, keine Anmeldung: So prüfen Kundschaft, Marke oder Prüfer, dass der Datensatz nicht umgeschrieben wurde.
Zuerst lesen
Bargeld, Brand Credit und Bullmark Point →
Was ein amount auf jeder Zeilenart bedeutet und in welche Richtung sich Geld bewegt.
Verwandt
Gebühren und wohin das Geld geht →
Wer was zahlt — damit eine Abrechnungszeile auf den Cent aufgeht.
Brauchen Sie einen Schlüssel?
Schlüssel werden an eingetragene Unternehmen ausgegeben. Tragen Sie Ihr Startup ein und fordern Sie einen Partnerschlüssel mit den Scopes an, die Ihre Integration braucht.
Startup eintragen → Alle acht Schritte ansehen