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

한 브랜드에서 지갑 하나의 크레딧·현금 잔액. 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

당신 브랜드의 바우처 중 최대 여덟 명의 엔드유저가 가진 것들.

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 가 무엇을 뜻하는지, 그리고 돈이 어느 방향으로 움직이는지.

키가 필요하신가요?

키는 등록된 법인에게 발급됩니다. 스타트업을 등록하고, 연동에 필요한 스코프를 지정해 파트너 키를 요청하세요.

내 스타트업 등록하기 → 여덟 걸음 모두 보기