Documentação da API

A API do Bullmark, para o seu backend.

Duas superfícies, uma chave. A API ledger lê e move crédito e dinheiro nas carteiras que você pode tocar. A API voucher verifica e resgata vouchers das suas próprias marcas no seu próprio checkout. Toda escrita é idempotente e todo movimento é selado. Guias, SDKs e a referência completa de vouchers ficam em developer.bullmark.net.

Antes da primeira chamada

A URL base é https://api.bullmark.net. Cada requisição leva sua chave no cabeçalho X-Api-Key; chaves começam com bm_live_, são emitidas pelo Bullmark e vinculadas à sua organização Axowl. Dinheiro é o que você esperaria dos três tipos de dinheiro: um amount numa linha de crédito é Brand Credit em dólares de valor de face; numa linha de caixa, é USD.

Escopos

Uma chave carrega uma lista de escopos separada por vírgulas. ledger.read lê saldos e histórico. ledger.debit gasta, reembolsa, saca. ledger.grant concede crédito e lança recargas em dinheiro. voucher.read consulta vouchers, voucher.redeem reserva, resgata, retira e libera. Uma chamada fora dos escopos da chave é um 401.

Mover dinheiro

Toda escrita que move valor — debit, refund, withdraw, auto-topup, grant, topup e as chamadas cash-refund — é uma chamada de dinheiro: a chave precisa estar vinculada a uma org Axowl, e a requisição também precisa carregar uma asserção de parceiro assinada pela Axowl como Authorization: Bearer … cujo emissor corresponda a esse vínculo. Cada chave tem um teto por transação; acima disso é um 403. Ler e resgatar não precisam de nenhum dos dois.

Idempotência

Toda escrita recebe um refId — sua própria referência. Envie o mesmo refId duas vezes e você recebe a mesma linha de volta com idempotentReplay: true, nunca um segundo movimento. Repita à vontade.

Chaves de dono

Uma carteira é nomeada pela chave do dono: enduser:{guid} para uma pessoa, org:{guid} para uma empresa, brand:{slug} para uma marca. Crédito é por marca, então a maioria das chamadas leva owner e brand juntos. O crédito da própria plataforma fica sob a marca __bullmark.

Limite de taxa

120 requests per minute por chave, janela fixa, sem fila. Acima disso você recebe um 429 sem nada feito. Leituras e escritas dividem a janela.

Erros

Erros são JSON com uma string error e, quando útil, os números por trás. 400 entrada inválida · 401 sem chave, chave ou escopo errado · 402 saldo insuficiente (com balance e required) · 403 não é seu, ou acima do teto · 404 não há nada · 409 o estado diz não.

Ledger — /partner/ledger

Uma caderneta, duas tabelas embaixo: linhas de crédito e linhas de caixa. O histórico as junta da mais nova para a mais antiga; cada linha diz qual é em bucket (cash, non-refundable, …) e que tipo de movimento em kind.

Rota

Escopo

O que faz

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

ledger.read

Saldo de crédito e caixa de uma carteira em uma marca. balance é o que pode ser gasto ali.

GET /partner/ledger/earnings?owner=

ledger.read

Dinheiro que um negócio ganhou, em todas as suas marcas — linhas por marca e o total.

GET /partner/ledger/history?owner=&brand=&limit=

ledger.read

Movimentos, do mais novo ao mais antigo, com os saldos. Omita brand para a caderneta inteira da pessoa em todas as marcas, incluindo crédito da plataforma.

GET /partner/ledger/by-ref?refId=

ledger.read

O que de fato saiu para um refId, crédito e caixa somados. Para rateio e conciliação.

GET /partner/ledger/cash-topups?owner=&brand=

ledger.read

Recargas em dinheiro que ainda guardam valor — aquilo de que um reembolso em dinheiro pode tirar.

POST /partner/ledger/debit

ledger.debit

Gastar. {owner, brand, amount, refId, memo}, valor positivo. Crédito primeiro, caixa para o resto numa carteira de org. 402 quando faltar.

POST /partner/ledger/refund

ledger.debit

Devolver crédito de um débito. Mesmo corpo do debit; a linha é um Refund.

POST /partner/ledger/withdraw

ledger.debit

Devolver o dinheiro de uma org para os cartões de onde veio. Apenas carteiras de org.

POST /partner/ledger/auto-topup

ledger.debit

Cobrar o cartão salvo fora de sessão quando um saldo cai abaixo da linha mínima. 402 se o cartão recusar, 502 se o provedor de pagamento estiver inacessível.

POST /partner/ledger/grant

ledger.grant

Conceder crédito não reembolsável. {owner, brand, amount, refId, memo}.

POST /partner/ledger/topup

ledger.grant

Lançar uma recarga em dinheiro que uma org pagou pelo seu gateway. Precisa de providerRef — uma linha de caixa sem recibo é uma afirmação, não dinheiro.

POST /partner/ledger/cash-refund

ledger.debit

Reembolsar parte de uma recarga em dinheiro. {owner, brand, topUpRefId, amount, refId}.

POST /partner/ledger/cash-refund/receipt

ledger.debit

Anexar o recibo do gateway (providerRef) a um reembolso em dinheiro depois de concluído.

POST /partner/ledger/cash-refund/reverse

ledger.debit

Desfazer um reembolso em dinheiro que não passou. Somente adição — o livro guarda as duas linhas.

Vouchers — /partner/vouchers

Um voucher é uma afirmação sobre um preço. Verifique-o, reserve-o enquanto seu checkout roda, resgate-o no instante em que o valor é entregue, libere-o se o pagamento falhar. Tudo isso contra vouchers das suas próprias marcas — o vínculo de org da chave diz quais.

Rota

Escopo

O que faz

GET /partner/vouchers?holder=&holder=

voucher.read

Vouchers das suas marcas detidos por até oito usuários finais.

GET /partner/vouchers/{codeOrTicket}

voucher.read

Verificar: o estado atual, o preço devido no resgate (priceUsd), o prazo. Seguro chamar quantas vezes quiser.

GET /partner/vouchers/{codeOrTicket}/events

voucher.read

A cadeia selada de eventos do voucher — retirado, reservado, resgatado — com verificação do selo.

POST /partner/vouchers/reserve

voucher.redeem

Travar para o seu checkout. {code} → um token de tíquete com expiração. Pedir duas vezes devolve o mesmo tíquete.

POST /partner/vouchers/redeem

voucher.redeem

A queima. {ticket | code, externalRef, note} — externalRef é o id do seu pedido e o que torna uma nova tentativa segura.

POST /partner/vouchers/release

voucher.redeem

Devolver um voucher reservado — o pagamento falhou ou o comprador saiu.

POST /partner/vouchers/claim

voucher.redeem

Retirar um voucher para um usuário final por um acordo de indicação. {code, productId, holder, holderEmail}.

Verificação, sem chave

Qualquer pessoa pode ler a cadeia selada de uma entidade em GET /integrity/events/{entityType}/{entityId} — o hash de cada evento, sua ligação com o anterior, e se a cadeia está intacta. Sem chave, sem login: é assim que um cliente, uma marca ou um auditor confere que o registro não foi reescrito.

Leia primeiro

Dinheiro, Brand Credit e Bullmark Point →

O que um amount significa em cada tipo de linha, e para que lado o dinheiro se move.

Relacionado

Taxas e para onde vai o dinheiro →

Quem paga o quê — para uma linha de liquidação bater no centavo.

Precisa de uma chave?

Chaves são emitidas para empresas registradas. Cadastre sua startup e peça uma chave de parceiro com os escopos de que sua integração precisa.

Cadastre sua startup → Ver os oito passos