계정 API2026-11프리뷰

잔액

주문 결제에 쓰는 돈(CN¥). ninjabuy.com에서 충전하며, API는 읽기만 하고 카드에 청구하지 않아요.

잔액으로 결제할 수 없는 주문은 awaiting_payment로 대기하다가 충전하면 자동으로 진행돼요.
취소한 주문이나 구매하지 못한 항목의 환불은 잔액으로 돌아가요. 수수료에 모든 청구 항목이 있어요.

엔드포인트

GET/v1/balance잔액 조회
GET/v1/balance/transactions거래 목록

Balance 객체

availablemoney: 새 주문에 쓸 수 있는 금액(CN¥).
reservedmoney: 구매 중인 주문과 계량 대기 중인 택배를 위해 보류됨.
top_up_urlstring: ninjabuy.com에 로그인해 충전하는 곳.

balance

{
  "available": { "amount": "2140.00", "currency": "CNY" },
  "reserved": { "amount": "264.20", "currency": "CNY" },
  "top_up_url": "https://www.ninjabuy.com/me/balance/top-up",
  "updated_at": "2026-11-04T09:20:03Z"
}

잔액 조회

GET/v1/balance

대량 주문을 보내기 전에 확인하세요.

범위balance:read

curl "https://www.ninjabuy.com/api/v1/balance" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "available": { "amount": "2140.00", "currency": "CNY" },
  "reserved": { "amount": "264.20", "currency": "CNY" },
  "top_up_url": "https://www.ninjabuy.com/me/balance/top-up",
  "updated_at": "2026-11-04T09:20:03Z"
}

거래 목록

GET/v1/balance/transactions

충전, 주문·배송 청구, 환불, 최신순. 금액에는 부호가 있으며 청구는 음수예요.

범위balance:read

쿼리 매개변수

typestring: 선택 사항. top_up, order, shipping 또는 refund.
orderstring: 선택 사항. 주문 ID: 그 주문으로 움직인 모든 것.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/balance/transactions?limit=3" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "txn_k22a",
      "type": "shipping",
      "order": "ord_3n7q",
      "amount": { "amount": "-134.52", "currency": "CNY" },
      "created_at": "2026-11-03T05:58:00Z"
    },
    {
      "id": "txn_k21d",
      "type": "order",
      "order": "ord_3n7q",
      "amount": { "amount": "-57.00", "currency": "CNY" },
      "created_at": "2026-11-01T09:14:02Z"
    },
    {
      "id": "txn_k1zz",
      "type": "top_up",
      "order": null,
      "amount": { "amount": "2000.00", "currency": "CNY" },
      "created_at": "2026-10-31T16:40:12Z"
    }
  ],
  "has_more": true,
  "cursor": "c_k1zz"
}