판매자가 특정 회원(user_id)의 적립금을 수동으로 지급·회수·만료시키는 운영용 API 입니다. 대상 회원을 파라미터로 지정한다는 점이 구매자 본인용 적립금 API(/v1/point/*, 단수형)와 다릅니다.
/v1/point/* (단수) |
/v1/points/* (복수, 이 문서) |
|
|---|---|---|
| 누가 | 로그인한 구매자 본인 | 판매자(운영) — 가맹점 서버 전용 |
| 대상 회원 | 회원 본인(회원 JWT 또는 쇼핑몰 서버가 지정한 user_id) |
user_id 파라미터(대상 회원 — 호출자 세션은 바뀌지 않음) |
| 할 수 있는 일 | 잔액·내역 조회 | 지급·회수·만료 |
인증 방식
secretKey 로 만든 Basic 인증(또는 그 키로 발급한 Bearer 토큰)이 필요합니다. 키체인 키면 supervisor:point_issue·supervisor:point_reclaim·supervisor:point_expire scope 를 받아 둬야 합니다. clientKey(Bootpay-Client-Key 헤더)나 쇼핑몰 도메인만으로는 호출할 수 없습니다.
user_id 는 호출자가 아니라 대상 회원입니다. 24자리 회원 ID 면 Bootpay 회원 ID, 그 밖의 값은 이 몰의 외부 회원 ID(ex_uid)로 찾습니다. user_ex_uid·user_external_uid·user_uid 도 같은 뜻이고, 로그인 아이디는 login_id 로 보냅니다. 이 몰의 회원이 아니거나 탈퇴한 회원이면 404 USER_NOT_FOUND 입니다.
| HTTP | error_code | 언제 (세 엔드포인트 공통) |
|---|---|---|
| 400 | TOKEN_AUTHORIZE_TYPE_INVALID |
Authorization 헤더가 없거나 Basic·Bearer 가 아님 |
| 401 | API_SCOPE_INVALID |
키체인 키에 scope 가 없음 |
| 400 | REQUIRED_PARAMETER_IS_MISSING |
user_id(또는 별칭·login_id)가 없음 |
| 404 | USER_NOT_FOUND |
이 몰의 회원이 아니거나 탈퇴한 회원(형식 오류 포함) |
| 403 | USER_NOT_MATCH |
user_id 와 login_id 가 서로 다른 회원 |
현재 상태 (2026-09-28): 인증·대상 회원 확인을 통과한 요청은 적립금 변경의 감사 기록 단계에서 서버 내부 오류(
500 SERVER_ERROR)로 끝납니다. 수정되기 전까지는 연동에 쓰지 마세요. 아래 내용은 코드가 의도한 요청·응답 형식입니다.
POST /v1/points/issue
회원에게 적립금을 지급합니다. 잔액 기록이 없는 회원이면 새로 만든 뒤 지급합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:point_issue - 회원 JWT(
Bootpay-User-JWT): 필요 없음 (보내도 대상 회원은user_id로 정해집니다)
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | O | 대상 회원 — 회원 ID 또는 외부 회원 ID(ex_uid). 별칭 user_ex_uid 등, login_id 도 가능 |
|
| body | amount | integer | O | 지급 금액. 1 이상 | |
| body | reason | string | admin_issue |
지급 사유 (거래 내역의 reason) |
응답
200 OK — 처리 후 잔액
{
"available_balance": 5500,
"total_earned": 7000,
"total_used": 1500,
"last_purchase_at": "2026-05-24T10:12:00+09:00",
"expires_at": "2026-11-24T10:12:00+09:00"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| available_balance | number | 사용 가능 잔액 (음수 가능) |
| total_earned | number | 누적 적립 금액 |
| total_used | number | 누적 차감 금액 |
| last_purchase_at | string | 마지막 구매 시각 (없으면 null) |
| expires_at | string | 적립금 전체 만료 예정 시각 (없으면 null) |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | POINT_AMOUNT_INVALID |
amount 가 없거나 0 이하 |
| 500 | SERVER_ERROR |
현재는 검증을 통과한 모든 요청 (위 현재 상태 참고) |
인증·대상 회원 오류는 위 인증 방식 표를 봅니다.
응답 형식은 오류를 봅니다.
변경 이력
- 2026-09-28 인증을 clientKey(쇼핑몰 세션)에서 Basic 인증 + supervisor scope 로 변경, 대상 회원을 이 몰 회원으로 확인(
ex_uid·별칭 지원, 없는 회원404, 누락400) - 2026-09-23 문서 최초 작성
POST /v1/points/reclaim
회원의 적립금을 지정한 금액만큼 회수합니다. 잔액보다 많이 회수하면 잔액이 음수가 될 수 있습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:point_reclaim - 회원 JWT(
Bootpay-User-JWT): 필요 없음 (보내도 대상 회원은user_id로 정해집니다)
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | O | 대상 회원 — issue 와 같음 | |
| body | amount | integer | O | 회수 금액. 1 이상 | |
| body | reason | string | admin_reclaim |
회수 사유 |
응답
200 OK — 처리 후 잔액. 형식은 POST /v1/points/issue 응답과 같습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | POINT_AMOUNT_INVALID |
amount 가 없거나 0 이하 |
| 404 | POINT_BALANCE_NOT_FOUND |
이 몰에서 적립금 기록이 없는 회원 |
| 500 | SERVER_ERROR |
현재는 검증을 통과한 모든 요청 |
변경 이력
- 2026-09-28 인증을 clientKey(쇼핑몰 세션)에서 Basic 인증 + supervisor scope 로 변경, 대상 회원을 이 몰 회원으로 확인(
ex_uid·별칭 지원, 없는 회원404, 누락400) - 2026-09-23 문서 최초 작성
POST /v1/points/expire
회원의 사용 가능 잔액 전부를 만료 처리합니다. 금액은 받지 않습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:point_expire - 회원 JWT(
Bootpay-User-JWT): 필요 없음 (보내도 대상 회원은user_id로 정해집니다)
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | O | 대상 회원 — issue 와 같음 | |
| body | reason | string | admin_expire |
만료 사유 |
응답
200 OK — 처리 후 잔액. 형식은 POST /v1/points/issue 응답과 같습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | POINT_BALANCE_NOT_FOUND |
이 몰에서 적립금 기록이 없는 회원 |
| 400 | POINT_AMOUNT_INVALID |
만료시킬 잔액이 없음 (사용 가능 잔액이 0 이하) |
| 500 | SERVER_ERROR |
현재는 검증을 통과한 모든 요청 |
변경 이력
- 2026-09-28 인증을 clientKey(쇼핑몰 세션)에서 Basic 인증 + supervisor scope 로 변경, 대상 회원을 이 몰 회원으로 확인(
ex_uid·별칭 지원, 없는 회원404, 누락400) - 2026-09-23 문서 최초 작성
