Documentation de l'API
L'API Bullmark, pour votre backend.
Deux surfaces, une clé. L'API ledger lit et déplace crédit et espèces sur les portefeuilles que vous avez le droit de toucher. L'API voucher vérifie et utilise les bons de vos propres marques dans votre propre tunnel. Toute écriture est idempotente et tout mouvement est scellé. Guides, SDK et référence complète des bons sur developer.bullmark.net.
Avant le premier appel
L'URL de base est https://api.bullmark.net. Chaque requête porte votre clé dans l'en-tête X-Api-Key; les clés commencent par bm_live_, sont émises par Bullmark et liées à votre organisation Axowl. L'argent est ce que vous attendriez des trois types d'argent: un amount sur une ligne de crédit est du Brand Credit en dollars de valeur faciale; sur une ligne d'espèces, c'est de l'USD.
Portées
Une clé porte une liste de portées séparées par des virgules. ledger.read lit soldes et historique. ledger.debit dépense, rembourse, retire. ledger.grant attribue du crédit et enregistre les recharges en espèces. voucher.read consulte les bons, voucher.redeem les réserve, les utilise, les réclame et les libère. Un appel hors des portées de la clé donne un 401.
Déplacer de l'argent
Toute écriture qui déplace de la valeur — debit, refund, withdraw, auto-topup, grant, topup et les appels cash-refund — est un appel d'argent: la clé doit être liée à une org Axowl, et la requête doit aussi porter une assertion partenaire signée par Axowl en Authorization: Bearer … dont l'émetteur correspond à cette liaison. Chaque clé a un plafond par transaction; au-delà, c'est un 403. Lire et utiliser n'ont besoin ni de l'un ni de l'autre.
Idempotence
Toute écriture prend un refId — votre propre référence. Envoyez deux fois le même refId et vous récupérez la même ligne avec idempotentReplay: true, jamais un second mouvement. Réessayez librement.
Clés de propriétaire
Un portefeuille est nommé par sa clé de propriétaire: enduser:{guid} pour une personne, org:{guid} pour une société, brand:{slug} pour une marque. Le crédit est par marque, donc la plupart des appels prennent owner et brand ensemble. Le crédit propre de la plateforme vit sous la marque __bullmark.
Limite de débit
120 requests per minute par clé, fenêtre fixe, sans file d'attente. Au-delà, vous obtenez un 429 sans que rien n'ait été fait. Lectures et écritures partagent la fenêtre.
Erreurs
Les erreurs sont du JSON avec une chaîne error et, quand c'est utile, les nombres derrière. 400 entrée invalide · 401 pas de clé, mauvaise clé ou portée · 402 solde insuffisant (avec balance et required) · 403 pas à vous, ou au-delà du plafond · 404 rien ici · 409 l'état dit non.
Ledger — /partner/ledger
Un livret, deux tables en dessous: lignes de crédit et lignes d'espèces. L'historique les fusionne du plus récent au plus ancien; chaque ligne dit laquelle elle est dans bucket (cash, non-refundable, …) et quel type de mouvement dans kind.
Route
Portée
Ce qu'elle fait
GET /partner/ledger/balance?owner=&brand=
ledger.read
Solde de crédit et d'espèces d'un portefeuille chez une marque. balance est ce qui peut y être dépensé.
GET /partner/ledger/earnings?owner=
ledger.read
Espèces gagnées par une entreprise, toutes marques confondues — lignes par marque et total.
GET /partner/ledger/history?owner=&brand=&limit=
ledger.read
Mouvements, du plus récent au plus ancien, avec les soldes. Omettez brand pour le livret complet de la personne sur toutes les marques, crédit plateforme inclus.
GET /partner/ledger/by-ref?refId=
ledger.read
Ce qui est réellement sorti pour un refId, crédit et espèces additionnés. Pour le prorata et le rapprochement.
GET /partner/ledger/cash-topups?owner=&brand=
ledger.read
Recharges en espèces qui ont encore de la valeur — ce sur quoi un remboursement en espèces peut puiser.
POST /partner/ledger/debit
ledger.debit
Dépenser. {owner, brand, amount, refId, memo}, montant positif. Crédit d'abord, espèces pour le reste sur un portefeuille org. 402 si insuffisant.
POST /partner/ledger/refund
ledger.debit
Rendre du crédit pour un débit. Même corps que debit; la ligne est un Refund.
POST /partner/ledger/withdraw
ledger.debit
Reverser les espèces d'une org vers les cartes d'origine. Portefeuilles org uniquement.
POST /partner/ledger/auto-topup
ledger.debit
Débiter la carte enregistrée hors session quand un solde passe sous le seuil bas. 402 si la carte est refusée, 502 si le prestataire de paiement est injoignable.
POST /partner/ledger/grant
ledger.grant
Attribuer du crédit non remboursable. {owner, brand, amount, refId, memo}.
POST /partner/ledger/topup
ledger.grant
Enregistrer une recharge en espèces qu'une org a payée via votre passerelle. Nécessite providerRef — une ligne d'espèces sans son reçu est une affirmation, pas de l'argent.
POST /partner/ledger/cash-refund
ledger.debit
Rembourser une partie d'une recharge en espèces. {owner, brand, topUpRefId, amount, refId}.
POST /partner/ledger/cash-refund/receipt
ledger.debit
Joindre le reçu de la passerelle (providerRef) à un remboursement en espèces une fois passé.
POST /partner/ledger/cash-refund/reverse
ledger.debit
Annuler un remboursement en espèces qui n'a pas abouti. En ajout seul — le livre garde les deux lignes.
Vouchers — /partner/vouchers
Un bon est une affirmation sur un prix. Vérifiez-le, réservez-le pendant que votre tunnel tourne, utilisez-le à l'instant où la valeur est donnée, libérez-le si le paiement échoue. Le tout sur les bons de vos propres marques — la liaison org de la clé dit lesquelles.
Route
Portée
Ce qu'elle fait
GET /partner/vouchers?holder=&holder=
voucher.read
Bons de vos marques détenus par jusqu'à huit utilisateurs finaux.
GET /partner/vouchers/{codeOrTicket}
voucher.read
Vérifier: l'état en direct, le prix dû à l'utilisation (priceUsd), la durée. Appelable aussi souvent que vous voulez.
GET /partner/vouchers/{codeOrTicket}/events
voucher.read
La chaîne d'événements scellée du bon — réclamé, réservé, utilisé — avec vérification du sceau.
POST /partner/vouchers/reserve
voucher.redeem
Le verrouiller pour votre tunnel. {code} → un jeton de ticket avec expiration. Le demander deux fois renvoie le même ticket.
POST /partner/vouchers/redeem
voucher.redeem
La consommation. {ticket | code, externalRef, note} — externalRef est votre id de commande et ce qui rend une nouvelle tentative sûre.
POST /partner/vouchers/release
voucher.redeem
Rendre un bon réservé — le paiement a échoué ou l'acheteur est parti.
POST /partner/vouchers/claim
voucher.redeem
Réclamer un bon pour un utilisateur final via un accord de parrainage. {code, productId, holder, holderEmail}.
Vérification, sans clé
N'importe qui peut lire la chaîne scellée d'une entité à GET /integrity/events/{entityType}/{entityId} — le hachage de chaque événement, son lien avec le précédent, et si la chaîne est intacte. Pas de clé, pas de connexion: c'est ainsi qu'un client, une marque ou un auditeur vérifie que l'enregistrement n'a pas été réécrit.
À lire d'abord
Espèces, Brand Credit et Bullmark Point →
Ce que signifie un amount sur chaque type de ligne, et dans quel sens l'argent circule.
À voir aussi
Frais et destination de l'argent →
Qui paie quoi — pour qu'une ligne de règlement se réconcilie au centime.
Besoin d'une clé?
Les clés sont délivrées aux sociétés enregistrées. Référencez votre startup et demandez une clé partenaire avec les portées dont votre intégration a besoin.
Référencez votre startup → Voir les huit étapes