Documentación de la API

La API de Bullmark, para tu backend.

Dos superficies, una clave. La API ledger lee y mueve crédito y efectivo en las carteras que puedes tocar. La API voucher verifica y canjea vales de tus propias marcas en tu propio checkout. Toda escritura es idempotente y todo movimiento queda sellado. Guías, SDK y la referencia completa de vales están en developer.bullmark.net.

Antes de la primera llamada

La URL base es https://api.bullmark.net. Cada petición lleva tu clave en la cabecera X-Api-Key; las claves empiezan por bm_live_, las emite Bullmark y están vinculadas a tu organización de Axowl. El dinero es lo que esperarías de los tres tipos de dinero: un amount en una fila de crédito es Brand Credit en dólares de valor nominal; en una fila de efectivo, es USD.

Ámbitos

Una clave lleva una lista de ámbitos separada por comas. ledger.read lee saldos e historial. ledger.debit gasta, reembolsa, retira. ledger.grant concede crédito y registra recargas en efectivo. voucher.read consulta vales, voucher.redeem los reserva, canjea, reclama y libera. Una llamada fuera de los ámbitos de la clave es un 401.

Mover dinero

Toda escritura que mueve valor —debit, refund, withdraw, auto-topup, grant, topup y las llamadas cash-refund— es una llamada de dinero: la clave debe estar vinculada a una org de Axowl, y la petición debe llevar además una aserción de socio firmada por Axowl como Authorization: Bearer … cuyo emisor coincida con esa vinculación. Cada clave tiene un techo por transacción; por encima es un 403. Leer y canjear no necesitan ninguna de las dos cosas.

Idempotencia

Toda escritura recibe un refId, tu propia referencia. Envía el mismo refId dos veces y recibes la misma fila con idempotentReplay: true, nunca un segundo movimiento. Reintenta sin miedo.

Claves de propietario

Una cartera se nombra por su clave de propietario: enduser:{guid} para una persona, org:{guid} para una empresa, brand:{slug} para una marca. El crédito es por marca, así que la mayoría de llamadas toman owner y brand juntos. El crédito propio de la plataforma vive bajo la marca __bullmark.

Límite de tasa

120 requests per minute por clave, ventana fija, sin cola. Por encima recibes un 429 sin que se haya hecho nada. Lecturas y escrituras comparten la ventana.

Errores

Los errores son JSON con una cadena error y, cuando es útil, los números detrás. 400 entrada incorrecta · 401 sin clave, clave o ámbito equivocados · 402 saldo insuficiente (con balance y required) · 403 no es tuyo, o por encima del techo · 404 no hay nada · 409 el estado dice que no.

Ledger — /partner/ledger

Una libreta, dos tablas debajo: filas de crédito y filas de efectivo. El historial las fusiona de más nueva a más antigua; cada fila dice cuál es en bucket (cash, non-refundable, …) y qué clase de movimiento en kind.

Ruta

Ámbito

Qué hace

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

ledger.read

Saldo de crédito y efectivo de una cartera en una marca. balance es lo que se puede gastar allí.

GET /partner/ledger/earnings?owner=

ledger.read

Efectivo que ganó un negocio, en todas sus marcas: líneas por marca y el total.

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

ledger.read

Movimientos, del más nuevo al más antiguo, con los saldos. Omite brand para la libreta completa de la persona en todas las marcas, incluido el crédito de plataforma.

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

ledger.read

Lo que realmente salió por un refId, sumando crédito y efectivo. Para prorrateo y conciliación.

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

ledger.read

Recargas en efectivo que aún conservan valor: aquello de lo que puede tirar un reembolso en efectivo.

POST /partner/ledger/debit

ledger.debit

Gastar. {owner, brand, amount, refId, memo}, importe positivo. Primero crédito; el resto en efectivo en una cartera de org. 402 si falta.

POST /partner/ledger/refund

ledger.debit

Devolver crédito por un cargo. Mismo cuerpo que debit; la fila es un Refund.

POST /partner/ledger/withdraw

ledger.debit

Devolver el efectivo de una org a las tarjetas de las que vino. Solo carteras de org.

POST /partner/ledger/auto-topup

ledger.debit

Cobrar la tarjeta guardada fuera de sesión cuando un saldo baja del umbral. 402 si la tarjeta se rechaza, 502 si el proveedor de pagos no responde.

POST /partner/ledger/grant

ledger.grant

Conceder crédito no reembolsable. {owner, brand, amount, refId, memo}.

POST /partner/ledger/topup

ledger.grant

Registrar una recarga en efectivo que una org pagó por tu pasarela. Necesita providerRef: una fila de efectivo sin su recibo es una afirmación, no dinero.

POST /partner/ledger/cash-refund

ledger.debit

Reembolsar parte de una recarga en efectivo. {owner, brand, topUpRefId, amount, refId}.

POST /partner/ledger/cash-refund/receipt

ledger.debit

Adjuntar el recibo de la pasarela (providerRef) a un reembolso en efectivo una vez realizado.

POST /partner/ledger/cash-refund/reverse

ledger.debit

Deshacer un reembolso en efectivo que no llegó a realizarse. Solo de adición: el libro conserva ambas líneas.

Vouchers — /partner/vouchers

Un vale es una afirmación sobre un precio. Verifícalo, resérvalo mientras corre tu checkout, canjéalo en el instante en que se entrega el valor, libéralo si el pago falla. Todo ello contra vales de tus propias marcas: la vinculación de org de la clave dice cuáles.

Ruta

Ámbito

Qué hace

GET /partner/vouchers?holder=&holder=

voucher.read

Vales de tus marcas en manos de hasta ocho usuarios finales.

GET /partner/vouchers/{codeOrTicket}

voucher.read

Verificar: el estado actual, el precio a cobrar al canjear (priceUsd), el plazo. Puedes llamarla tantas veces como quieras.

GET /partner/vouchers/{codeOrTicket}/events

voucher.read

La cadena sellada de eventos del vale —reclamado, reservado, canjeado— con verificación del sello.

POST /partner/vouchers/reserve

voucher.redeem

Bloquearlo para tu checkout. {code} → un token de ticket con caducidad. Pedirlo dos veces devuelve el mismo ticket.

POST /partner/vouchers/redeem

voucher.redeem

La quema. {ticket | code, externalRef, note}: externalRef es el id de tu pedido y lo que hace seguro un reintento.

POST /partner/vouchers/release

voucher.redeem

Devolver un vale reservado: el pago falló o el comprador se fue.

POST /partner/vouchers/claim

voucher.redeem

Reclamar un vale para un usuario final mediante un acuerdo de recomendación. {code, productId, holder, holderEmail}.

Verificación, sin clave

Cualquiera puede leer la cadena sellada de una entidad en GET /integrity/events/{entityType}/{entityId}: el hash de cada evento, su enlace con el anterior y si la cadena está intacta. Sin clave, sin sesión: así es como un cliente, una marca o un auditor comprueba que el registro no se reescribió.

Leer primero

Efectivo, Brand Credit y Bullmark Point →

Qué significa un amount en cada tipo de fila, y en qué dirección se mueve el dinero.

Relacionado

Comisiones y adónde va el dinero →

Quién paga qué, para que una línea de liquidación cuadre al céntimo.

¿Necesitas una clave?

Las claves se emiten a empresas registradas. Publica tu startup y pide una clave de socio con los ámbitos que necesite tu integración.

Publica tu startup → Ver los ocho pasos