쇼핑몰 구매자(회원)의 가입·이메일 인증·로그인·세션·내 정보·비밀번호·탈퇴·배송지와, 가맹점 서버가 회원을 옮기거나 관리하는 API 입니다.
모든 API 는 프로젝트 인증(Basic)이 필요합니다. 구매자 본인 API 는 여기에 더해 로그인으로 받은 JWT 를 Bootpay-User-JWT 헤더로 보냅니다 — 회원 JWT. 인증 절에 user_id 를 받는다고 적힌 본인 API 는 secretKey 인증일 때 JWT 대신 user_id(또는 login_id)로도 회원을 정할 수 있습니다(둘 다 오면 JWT 우선, 다른 회원이면 403 USER_NOT_MATCH). 예외로 세션 API(GET·DELETE /v1/users/session)는 JWT 전용입니다.
자주 쓰는 흐름
가입 → 로그인 → 내 정보
GET /v1/users/signup-policy로 가입 화면이 그릴 약관·필수 입력과policy_version을 받습니다.POST /v1/users/signup으로 가입합니다. 가입은 JWT 를 발급하지 않습니다(requires_login: true).- 응답
status가standby면 이메일 인증이 필요합니다. 회원이 메일 링크를 누르면POST /v1/users/authenticate로 인증을 완료합니다. 메일을 다시 보내려면POST /v1/users/authenticate/:id/resend를 씁니다.
- 응답
POST /v1/users/login으로 로그인해token을 받습니다.- 이후 본인 API(
GET /v1/users/me등)에Bootpay-User-JWT: <token>을 붙여 호출합니다. 로그아웃은DELETE /v1/users/session입니다.- 쇼핑몰 서버가 자기 로그인 세션으로 회원을 관리한다면 로그인 응답의
user_id를 저장하고,user_id를 받는 본인 API(비밀번호 변경·탈퇴·배송지·결제 토큰·지갑 등 각 API 의 인증 절 참고)에 JWT 대신user_id를 보내도 됩니다(secretKey 인증일 때만).
- 쇼핑몰 서버가 자기 로그인 세션으로 회원을 관리한다면 로그인 응답의
비밀번호 찾기 (로그아웃 상태, 3단계)
POST /v1/users/password-recovery/requests— 아이디와 수단(email/phone)을 보내면 등록된 연락처로 인증코드가 갑니다.challenge_id를 받습니다.POST /v1/users/password-recovery/verifications—challenge_id+ 인증코드로 일회성reset_token을 받습니다.PUT /v1/users/password-recovery/password—reset_token으로 새 비밀번호를 저장합니다. 이 회원의 기존 로그인은 모두 끊깁니다.
탈퇴 후 재가입 제한
탈퇴한 회원은 탈퇴 후 최소 7일 동안 같은 가입 정보로 다시 가입할 수 없습니다. 쇼핑몰 설정으로 이 기간을 더 길게 늘릴 수 있고, 7일보다 짧게 줄일 수는 없습니다. 실제 적용 기간은 GET /v1/users/me/withdrawal 의 rejoin_restriction.days 로 탈퇴 전에 안내할 수 있습니다.
제한 기간 안의 가입은 400 MEMBER_LEFT_RECENTLY 로 거절되며, payload 에 다음 값이 옵니다.
| 필드 | 설명 |
|---|---|
| rejoin_available_at | 재가입 가능 시각 (ISO 8601) |
| rejoin_block_code | 문의 코드 (RJ-XXXX-XXXX). 구매자가 판매자에게 이 코드를 알려주면 판매자가 제한을 풀 수 있습니다 |
가입 API 두 가지
POST /v1/users/signup— 구매자 신규 가입. 약관 동의·가입 방식·중복·재가입 제한·이메일 인증을 모두 거칩니다. 브라우저 입력을 서버가 넘기는 용도입니다.POST /v1/users/join— 가맹점이 기존 회원을 부트페이로 옮기는 동기화용. 약관·재가입 제한·이메일 인증을 거치지 않으므로 공개 가입 화면에 쓰지 마세요.
값 코드
| 필드 | 값 |
|---|---|
| membership_type | 1 회원, 2 비회원 |
| corporate_type | 1 개인, 2 기업, 3 부서 |
| status | 1 정상, 0 사용 중지, -1 탈퇴 |
| gender | -1 알 수 없음, 0 비공개, 1 남성, 2 여성 |
GET /v1/users/signup-policy
가입 화면을 그리기 전에 부릅니다. 가입 방식, 필수 입력, 회원가입 약관 목록과 정책 지문(policy_version)을 줍니다. POST /v1/users/signup 은 이 응답과 같은 목록으로 약관 동의를 검증합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_signup_policy - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
파라미터 없음.
응답
200 OK
{
"signup_enabled": true,
"membership_type": "id",
"supported_member_types": ["individual"],
"fields": {
"name": { "required": true },
"email": { "required": true },
"phone": { "required": true },
"address": { "required": false }
},
"terms": [
{
"term_id": "66f0...",
"required": true,
"title": "이용약관",
"desc": "",
"content": "<p>...</p>",
"use_url": false,
"url": null,
"sort": 1,
"updated_at": "2026-09-01T10:00:00+09:00"
}
],
"policy_version": "3f9a0c1b2d4e5f60"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| signup_enabled | boolean | 가입 가능 여부. 쇼핑몰이 비활성이면 응답 대신 442 MALL_INACTIVE 가 오므로 응답에서는 항상 true 입니다 |
| membership_type | string | 로그인 식별자. id(아이디 가입) | email(이메일 가입) |
| supported_member_types | string[] | 이 API 로 가입할 수 있는 회원 유형. 현재 individual(개인)만 |
| fields | object | 입력 항목별 필수 여부 (name·email·phone·address) |
| terms | array | 회원가입 약관. sort, term_id 순 |
| terms[].term_id | string | 약관 ID — 가입 시 term_ids 로 보냅니다 |
| terms[].required | boolean | 필수 동의 여부 |
| terms[].title / desc / content | string | 제목·요약·본문(HTML) |
| terms[].use_url / url | boolean / string | use_url 이 true 면 본문 대신 외부 URL 약관입니다 (content 가 비어 있음) |
| terms[].sort | integer | 표시 순서 |
| terms[].updated_at | string | 약관 변경 시각 |
| policy_version | string | 약관 목록과 필수 입력 설정의 지문(16자). 가입 요청에 그대로 보내면 그 사이 정책이 바뀌었는지 서버가 확인합니다 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 442 | MALL_INACTIVE |
쇼핑몰이 비활성 상태 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-21 추가
POST /v1/users/signup
구매자 신규 가입. 쇼핑몰 가입 정책(약관·가입 방식·중복·재가입 제한·이메일 인증)을 거칩니다. JWT 는 발급하지 않습니다 — 가입 후 POST /v1/users/login 으로 로그인합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_create - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | login_id | string | 아이디 가입 몰 O | 영문·숫자 5~30자. 이메일 가입 몰에서는 쓰지 않습니다 | |
| body | password | string | O | 8자 이상, 72바이트 이하. 앞뒤 공백은 제거됩니다 | |
| body | string | 이메일 가입 몰 O | 100자 이하. 이메일 가입 몰에서는 로그인 식별자입니다 | ||
| body | name | string | O | 50자 이하 | |
| body | phone | string | 설정에 따라 | 숫자 8~15자리(하이픈 허용, 저장 시 제거). fields.phone.required 가 true 면 필수 |
|
| body | address | object | 설정에 따라 | { zipcode, address, address_detail }. fields.address.required 가 true 면 zipcode·address 필수. 이 세 키 외에는 받지 않습니다 |
|
| body | address.zipcode | string | 5자리(구 우편번호 123-456 허용) |
||
| body | address.address / address.address_detail | string | 각 100자 이하 | ||
| body | term_ids | string[] | 필수 약관이 있으면 O | 동의한 약관 ID. 배열 또는 쉼표로 구분한 문자열 | |
| body | policy_version | string | GET /v1/users/signup-policy 에서 받은 값. 보내면 정책이 바뀌었는지 확인하고, 안 보내면 확인하지 않습니다 |
다음 키는 보내면 거절합니다(400 API_PARAM_INVALID, payload.rejected_params): uid, ex_uid, external_uid, user_id, login_pw, user_group_id, is_group_admin, group, corporate_type, membership_type, status, role, join_at, extra.
응답
200 OK
가입 완료:
{
"status": "finish",
"user_id": "66f1...",
"requires_login": true
}json이메일 인증 대기:
{
"status": "standby",
"user_standby_id": "66f1...",
"verification_context": "9c1e...",
"requires_login": true
}json| 필드 | 타입 | 설명 |
|---|---|---|
| status | string | finish 가입 완료 | standby 이메일 인증 대기 | pending_approval 판매자 승인 대기 |
| user_id | string | 만들어진 회원 ID (finish·pending_approval) |
| user_standby_id | string | 인증 대기 ID (standby). /v1/users/authenticate/:id 의 :id 입니다 |
| verification_context | string | 인증 대기 소유 증명 값 (standby). 이 응답에서 한 번만 주므로 보관했다가 재발송·상태 조회에 보냅니다 |
| requires_login | boolean | 항상 true — 로그인은 따로 합니다 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | API_PARAM_INVALID |
받지 않는 키를 보냄(payload.rejected_params), address 가 객체가 아님 |
| 400 | USER_NAME_BLANK |
이름 없음 |
| 400 | CUSTOMER_FIELD_TOO_LONG |
길이 초과 (payload.field, payload.max_length) |
| 400 | USER_PASSWORD_FORMAT_INVALID |
비밀번호 8자 미만 |
| 400 | REQUIRED_PARAMETER_IS_MISSING |
전화번호 수집 몰인데 phone 없음 (payload.field) |
| 400 | CUSTOMER_PHONE_INVALID |
전화번호 형식 오류 |
| 400 | USER_ADDRESS_BLANK |
주소 수집 몰인데 우편번호·주소 없음 |
| 400 | ADDRESS_ZIPCODE_INVALID |
우편번호 형식 오류 |
| 400 | USER_ID_BLANK / USER_ID_INVALID / USER_ID_EXIST |
(아이디 가입 몰) 아이디 없음 / 형식 오류 / 이미 사용 중 |
| 400 | USER_EMAIL_BLANK / USER_EMAIL_INVALID / USER_EMAIL_EXIST |
이메일 없음 / 형식 오류 / (이메일 가입 몰) 이미 사용 중 |
| 400 | USER_PASSWORD_BLANK |
비밀번호 없음 |
| 400 | MEMBER_LEFT_RECENTLY |
탈퇴 후 재가입 제한 기간 — 탈퇴 후 재가입 제한 |
| 409 | SIGNUP_POLICY_VERSION_CHANGED |
policy_version 이 현재 정책과 다름. payload.policy_version 에 현재 값. 정책을 다시 조회해 동의를 받으세요 |
| 442 | TERM_NOT_FOUND |
목록에 없는 약관 ID (payload.term_ids) |
| 442 | REQUIRED_PARAMETER_IS_MISSING |
필수 약관 미동의 (payload.field: "term_ids", payload.missing_term_ids) |
| 442 | MALL_INACTIVE |
쇼핑몰이 비활성 상태 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-21 약관 동의·
policy_version·address검증 추가, 인증 대기 응답에verification_context추가 - 2026-09-14 추가
GET /v1/users/authenticate/:id
가입 이메일 인증 대기 상태를 조회합니다. 인증 메일을 보낸 뒤 화면이 완료 여부를 확인할 때 씁니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope: scope 검사 없음
- 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 가입 응답의 user_standby_id |
|
| query | verification_context | string | 가입 응답의 값. 보내면 일치하는지 확인합니다 |
응답
200 OK
{
"status": 3,
"auth_email": false,
"pending_approval": false,
"email": "gos***@example.com",
"client_key": "68a1...",
"user_standby_id": "66f1...",
"verification_state": "pending",
"requires_login": true
}json| 필드 | 타입 | 설명 |
|---|---|---|
| verification_state | string | pending 대기 | verified 인증 완료 | expired 만료. 화면 분기에는 이 값을 쓰세요 |
| auth_email | boolean | 이메일 인증 완료 여부 |
| pending_approval | boolean | 인증은 끝났고 판매자 승인을 기다리는 중 |
| string | 일부를 가린 이메일 (이메일 인증 몰에서만) | |
| client_key | string | 프로젝트 clientKey |
| user_standby_id | string | 인증 대기 ID |
| status | integer | 내부 상태 숫자 (하위 호환용) |
| requires_login | boolean | 항상 true — 인증이 끝나도 토큰은 주지 않습니다 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_STAND_BY_NOT_FOUND |
이 프로젝트에 없는 ID |
| 400 | SIGNUP_CONTEXT_INVALID |
verification_context 불일치 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-21 프로젝트 범위 조회,
verification_state·requires_login추가
POST /v1/users/authenticate
인증 메일 링크의 토큰으로 이메일 인증을 완료합니다. 인증이 끝나면 회원이 만들어집니다(판매자 승인이 필요한 경우 승인 대기 상태로). 토큰은 발급하지 않습니다.
인증 링크는 메일 발송 후 30분 동안 유효합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope: scope 검사 없음
- 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | token_key | string | O | 인증 링크 경로 끝의 값(Base64) 그대로 |
응답
200 OK — GET /v1/users/authenticate/:id 와 같은 형식입니다. 이미 인증된 토큰이면 현재 상태를 그대로 돌려줍니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | API_PARAM_INVALID |
token_key 가 Base64 가 아님 (payload.field) |
| 404 | USER_STAND_BY_NOT_FOUND |
이 프로젝트에 없는 토큰 |
| 400 | USER_EMAIL_AUTHENTICATE_EXPIRED |
인증 시간(30분) 만료 |
| 500 | USER_EMAIL_AUTHENTICATE_PROCESS_ERROR |
인증 처리 중 서버 오류 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-21 인증된 프로젝트의 토큰만 처리
POST /v1/users/authenticate/:id/resend
인증 메일을 다시 보냅니다. 직전 발송 후 1분이 지나야 다시 보낼 수 있습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_signup_resend - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 가입 응답의 user_standby_id |
|
| body | verification_context | string | O | 가입 응답의 verification_context |
응답
200 OK
{
"accepted": true,
"resend_after": "2026-09-23T10:01:00+09:00"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| accepted | boolean | 항상 true |
| resend_after | string | 다음 재발송 가능 시각 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | SIGNUP_CONTEXT_INVALID |
verification_context 없음 또는 불일치 |
| 404 | USER_STAND_BY_NOT_FOUND |
이 프로젝트에 없는 ID |
| 400 | USER_EMAIL_AUTHENTICATE_EXPIRED |
인증 시간 만료 또는 이미 인증됨 — 만료면 가입부터 다시 진행 |
| 400 | USER_EMAIL_RECENTLY_SENT |
1분 안에 다시 요청 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-21 추가
POST /v1/users/login
아이디(이메일 가입 몰은 이메일)와 비밀번호로 로그인해 회원 JWT 를 받습니다.
로그인 세션은 발급 후 1일 동안 유효합니다. 만료·로그아웃·비밀번호 변경 뒤에는 본인 API 가 401 USER_SESSION_INVALID 를 주므로 다시 로그인합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_login_token - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | login_id | string | O | 아이디 또는 이메일. id 키로 보내도 됩니다 |
|
| body | password | string | O | 비밀번호 |
이 API 는 회원을 증명하는 단계라 Bootpay-User-JWT·user_id 를 읽지 않습니다.
응답
200 OK
{
"token": "eyJhbGciOiJSUzI1NiJ9...",
"user_id": "66f1..."
}json| 필드 | 타입 | 설명 |
|---|---|---|
| token | string | 회원 JWT. Bootpay-User-JWT 헤더에 넣습니다 |
| user_id | string | 회원 ID. JWT 대신 user_id 로 회원 API 를 부르는 쇼핑몰 서버는 이 값을 자기 로그인 세션에 저장합니다 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_LOGIN_FAILED |
없는 계정, 비밀번호 불일치, 사용 중지된 계정 (구분하지 않습니다) |
| 400 | USER_PENDING_APPROVAL |
판매자 승인 대기 중인 계정 |
| 404 | USER_LOGIN_SERVER_ERROR |
서버 오류로 로그인 실패 |
| 442 | MALL_INACTIVE |
쇼핑몰이 비활성 상태 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 응답에
user_id추가 - 2026-09-23 문서 최초 작성
GET /v1/users/session
현재 JWT 의 로그인 회원 요약(이름·연락처는 가린 값)을 줍니다. 헤더 표시·로그인 여부 확인용입니다. 수정 폼을 채우려면 GET /v1/users/me 를 씁니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_session_detail - 회원 JWT(
Bootpay-User-JWT): 선택 — 없거나 무효면 오류 없이null을 돌려줍니다
이 API 는 JWT 전용입니다. 대상이 회원이 아니라 "이 JWT 세션"이므로 user_id 로 회원을 정하지 않습니다. 가맹점 서버가 회원 정보를 보려면 GET /v1/users/:id 를 씁니다.
요청
파라미터 없음. user_id·user_ex_uid·user_external_uid·user_uid 를 보내면 400 API_PARAM_INVALID 로 거절합니다(payload.rejected_params).
응답
200 OK — 로그인 상태가 아니면 본문이 null 입니다.
{
"user_id": "66f1...",
"name": "홍*동",
"phone": "010****5678",
"email": "gos***@example.com",
"identification": "gosomi84",
"user_groups": [
{ "user_group_id": "66f1...", "corporate_type": 1 }
],
"membership_type": 1,
"is_ex": false,
"pending_corporate_approval": false,
"current_user_group": { "user_group_id": "66f1...", "corporate_type": 1 }
}json| 필드 | 타입 | 설명 |
|---|---|---|
| user_id | string | 회원 ID |
| name / phone / email | string | 일부를 가린 값 |
| identification | string | 화면에 보여줄 로그인 식별자 |
| user_groups | array | 소속 그룹(개인·기업·부서). 기업·부서면 그룹 정보와 role 이 더 붙습니다 |
| membership_type | integer | 1 회원, 2 비회원 |
| is_ex | boolean | 외부 동기화(POST /v1/users/join)로 들어온 회원 |
| pending_corporate_approval | boolean | 기업 가입 승인 대기 중 |
| current_user_group | object | null | 현재 선택된 그룹 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | API_PARAM_INVALID |
user_id 계열 파라미터를 보냄 — payload.rejected_params |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 scope
user:user_session_detail신설,user_id계열 파라미터 거절 - 2026-09-23 문서 최초 작성
DELETE /v1/users/session
로그아웃. 이 JWT 의 이 쇼핑몰 세션을 지웁니다. 이후 같은 JWT 로 본인 API 를 부르면 401 USER_SESSION_INVALID 가 옵니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_session_delete - 회원 JWT(
Bootpay-User-JWT): 필수 (유효하지 않으면401 USER_SESSION_INVALID)
이 API 는 JWT 전용입니다. 지울 세션은 JWT 가 정하므로 user_id 로는 로그아웃할 수 없습니다.
요청
파라미터 없음. user_id·user_ex_uid·user_external_uid·user_uid 를 보내면 400 API_PARAM_INVALID 로 거절합니다(payload.rejected_params) — 로그아웃되지 않습니다.
응답
200 OK — 본문은 boolean 입니다. 같은 JWT 에 다른 쇼핑몰의 세션이 남아 있으면 true, 없으면 false 입니다. 어느 쪽이든 이 쇼핑몰에서는 로그아웃됐습니다.
falsejson오류
| HTTP | error_code | 언제 |
|---|---|---|
| 401 | USER_SESSION_INVALID |
JWT 없음, 이미 로그아웃·만료, 위조된 JWT |
| 400 | API_PARAM_INVALID |
user_id 계열 파라미터를 보냄 — payload.rejected_params |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 scope
user:user_session_delete신설,user_id계열 파라미터 거절 - 2026-09-23 문서 최초 작성
GET /v1/users/me
본인 프로필을 평문으로 줍니다. 수정 폼을 채우는 용도입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_me_detail - 회원:
Bootpay-User-JWT또는user_id·login_id중 하나 필수 — 회원 JWT. 둘 이상 보내면 JWT 가 우선이고, 서로 다른 회원이면403 USER_NOT_MATCH입니다.user_id·login_id는 secretKey(Basic)·Bearer 인증일 때만 받습니다. - 범위: scope 키는 본인 프로필 용도를 표시합니다.
user_id로 이 몰의 어느 회원이든 지정할 수 있으므로, 로그인한 회원 본인의 값인지 확인하는 책임은 쇼핑몰 서버에 있습니다.
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | user_id | string | JWT 없으면 O | 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다 |
|
| query | login_id | string | 로그인 아이디로 회원을 지정할 때. user_id 와 함께 보내면 같은 회원이어야 합니다 |
응답
200 OK
{
"user": {
"user_id": "66f1...",
"name": "홍길동",
"nickname": "길동",
"email": "gildong@example.com",
"phone": "01012345678",
"login_id": "gildong01",
"membership_type": 1,
"gender": 1,
"birth": "900101",
"created_at": "2026-09-01"
},
"editable_fields": ["name", "nickname", "gender", "birth"],
"profile_version": "a1b2c3d4e5f60718"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| user.user_id | string | 회원 ID |
| user.name / nickname / email / phone | string | 평문 값 |
| user.login_id | string | null | 로그인 아이디. 이메일 가입 몰이면 null |
| user.membership_type | integer | 1 회원 |
| user.gender | integer | 값 코드 |
| user.birth | string | 생년월일 6자리 (YYMMDD) |
| user.created_at | string | 가입일 (YYYY-MM-DD) |
| editable_fields | string[] | PATCH /v1/users/me 로 바꿀 수 있는 필드 |
| profile_version | string | 수정 시 함께 보내 동시 수정을 막는 버전 값 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 401 | USER_SESSION_INVALID |
JWT·user_id·login_id 모두 없음, 또는 JWT 세션 만료·로그아웃 |
| 401 | USER_JWT_INVALID |
위조·만료된 JWT |
| 403 | USER_NOT_MATCH |
JWT 회원과 user_id·login_id 회원이 다름 |
| 404 | USER_NOT_FOUND |
user_id·login_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님 |
| 400 | API_PARAM_INVALID |
secretKey 없이(client key 만으로) user_id·login_id 를 보냄 — payload.reason: merchant_auth_required |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을 JWT 또는
user_id·login_id로 정할 수 있게 변경(이전에는 JWT 전용) - 2026-09-21 추가
PATCH /v1/users/me
본인 프로필 수정. 보낸 필드만 바꾸고 보내지 않은 필드는 그대로 둡니다. 바꿀 필드가 없으면 저장하지 않고 현재 프로필을 돌려줍니다.
이메일·휴대폰은 로그인·본인확인 수단이라 이 API 로 바꿀 수 없습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_me_update - 회원:
Bootpay-User-JWT또는user_id·login_id중 하나 필수 — 회원 JWT. 둘 이상 보내면 JWT 가 우선이고, 서로 다른 회원이면403 USER_NOT_MATCH입니다.user_id·login_id는 secretKey(Basic)·Bearer 인증일 때만 받습니다. - 범위: scope 키는 본인 프로필 용도를 표시합니다.
user_id로 이 몰의 어느 회원이든 지정할 수 있으므로, 로그인한 회원 본인의 값인지 확인하는 책임은 쇼핑몰 서버에 있습니다.
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | JWT 없으면 O | 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다 |
|
| body | login_id | string | 로그인 아이디로 회원을 지정할 때(로그인 아이디를 바꾸는 값이 아닙니다). user_id 와 함께 보내면 같은 회원이어야 합니다 |
||
| body | name | string | 50자 이하. 빈 값 불가 | ||
| body | nickname | string | 30자 이하. 빈 문자열이면 닉네임을 비웁니다 | ||
| body | gender | string | -1, 0, 1, 2 중 하나 |
||
| body | birth | string | 숫자 6자리 (YYMMDD) | ||
| body | profile_version | string | 마지막으로 읽은 profile_version. 보내면 그 사이 다른 곳에서 바뀌었는지 확인합니다 |
다음 키는 보내면 거절합니다(400 API_PARAM_INVALID): uid, ex_uid, external_uid, login_pw, password, role, group, user_group_id, is_group_admin, corporate_type, membership_type, status, email, phone, tel, comment, join_at, extra. payload.rejected_params 에 거절한 키가, email·phone 이 포함되면 payload.verification_required 에 그 키가 옵니다.
응답
200 OK — GET /v1/users/me 와 같은 형식(바뀐 값과 새 profile_version).
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | API_PARAM_INVALID |
받지 않는 키(payload.rejected_params), gender·birth 형식 오류(payload.field) |
| 400 | USER_NAME_BLANK |
name 을 빈 값으로 보냄 |
| 400 | CUSTOMER_FIELD_TOO_LONG |
길이 초과 (payload.field, payload.max_length) |
| 409 | USER_PROFILE_VERSION_CHANGED |
profile_version 이 현재 값과 다름. payload.profile_version 에 현재 값. 다시 조회한 뒤 수정하세요 |
| 401 | USER_SESSION_INVALID |
JWT·user_id·login_id 모두 없음, 또는 JWT 세션 만료·로그아웃 |
| 401 | USER_JWT_INVALID |
위조·만료된 JWT |
| 403 | USER_NOT_MATCH |
JWT 회원과 user_id·login_id 회원이 다름 |
| 404 | USER_NOT_FOUND |
user_id·login_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님 |
| 400 | API_PARAM_INVALID |
secretKey 없이(client key 만으로) user_id·login_id 를 보냄 — payload.reason: merchant_auth_required |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을 JWT 또는
user_id·login_id로 정할 수 있게 변경(이전에는 JWT 전용,user_id·login_id는 거절 키였음) - 2026-09-21 추가
PUT /v1/users/me/password
본인 비밀번호 변경. 성공하면 이 회원의 모든 기기 로그인이 끊깁니다(요청한 기기 포함). 응답 뒤 다시 로그인하세요.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_me_password_update - 회원:
Bootpay-User-JWT또는user_id중 하나 필수 — 회원 JWT. 둘 다 보내면 JWT 가 우선이고,user_id가 다른 회원이면403 USER_NOT_MATCH입니다.user_id는 secretKey(Basic)·Bearer 인증일 때만 받습니다.
어느 방식이든 본인 확인은 current_password 가 합니다. Commerce 는 이 회원의 JWT 만 무효로 만들므로, user_id 로 부른 쇼핑몰 서버는 requires_login: true 를 받으면 자기 로그인 세션(쿠키 등)도 끊어야 합니다.
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | JWT 없으면 O | 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다 |
|
| body | current_password | string | O | 현재 비밀번호 | |
| body | new_password | string | O | 8자 이상, 72바이트 이하. 현재 비밀번호와 달라야 합니다 | |
| body | new_password_confirmation | string | 보내면 new_password 와 같은지 확인합니다 |
응답
200 OK
{
"changed": true,
"requires_login": true
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 409 | USER_PASSWORD_NOT_SET |
비밀번호가 없는 계정(간편 로그인 전용). 비밀번호 찾기로 설정합니다 |
| 400 | USER_PASSWORD_BLANK |
현재 또는 새 비밀번호 없음 |
| 400 | USER_LOGIN_PASSWORD_NOT_MATCH |
현재 비밀번호 불일치 |
| 400 | USER_PASSWORD_FORMAT_INVALID |
새 비밀번호 8자 미만, 또는 현재와 같은 값 |
| 400 | CUSTOMER_FIELD_TOO_LONG |
새 비밀번호 72바이트 초과 |
| 400 | USER_PASSWORD_CONFIRM_NOT_MATCH |
확인 값 불일치 |
| 401 | USER_SESSION_INVALID |
JWT·user_id 모두 없음, 또는 JWT 세션 만료·로그아웃 — 회원 JWT 참고 |
| 401 | USER_JWT_INVALID |
위조·만료된 JWT |
| 403 | USER_NOT_MATCH |
JWT 회원과 user_id 회원이 다름 |
| 404 | USER_NOT_FOUND |
user_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님 |
| 400 | API_PARAM_INVALID |
secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required |
검증에서 거절되면 비밀번호와 로그인 상태는 바뀌지 않습니다.
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 JWT 없이
user_id로도 회원을 정할 수 있게 변경 - 2026-09-21 추가
GET /v1/users/me/withdrawal
탈퇴 화면이 그릴 정보: 탈퇴 가능 여부, 막는 이유, 본인 확인 방식, 개인정보 보관기간 선택지, 재가입 제한 기간, 안내 문구.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_me_withdrawal_detail - 회원:
Bootpay-User-JWT또는user_id중 하나 필수 — 회원 JWT. 둘 다 보내면 JWT 가 우선이고,user_id가 다른 회원이면403 USER_NOT_MATCH입니다.user_id는 secretKey(Basic)·Bearer 인증일 때만 받습니다.
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | user_id | string | JWT 없으면 O | 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다 |
응답
200 OK
{
"withdrawable": false,
"blockers": [
{ "type": "order", "count": 1 }
],
"confirm_method": "password",
"retention_options": [
{ "retention_type": "immediate", "label": "바로 폐기", "description": "탈퇴 즉시 모든 개인정보가 삭제돼요" },
{ "retention_type": "year_1", "label": "1년 보관 후 삭제", "description": "문의·분쟁 대응을 위해 1년 보관 후 자동으로 삭제돼요" },
{ "retention_type": "year_3", "label": "3년 보관 후 삭제", "description": "3년 보관 후 자동으로 삭제돼요" }
],
"rejoin_restriction": { "enabled": true, "days": 30 },
"guide_message": "탈퇴하면 적립금과 쿠폰이 모두 사라지고 되돌릴 수 없어요. ..."
}json| 필드 | 타입 | 설명 |
|---|---|---|
| withdrawable | boolean | 지금 탈퇴할 수 있는지 |
| blockers | array | 막는 이유. type: subscription(이용 중인 정기구독) | order(진행 중인 주문), count: 건수 |
| confirm_method | string | 본인 확인 방식. password(비밀번호 계정) | phrase(간편 로그인 전용 계정) |
| confirm_phrase | string | phrase 방식일 때 입력해야 하는 문구 (탈퇴합니다). password 면 없음 |
| retention_options | array | 개인정보 보관기간 선택지 |
| rejoin_restriction | object | enabled(항상 true), days(재가입 제한 일수, 최소 7) — 탈퇴 후 재가입 제한 |
| guide_message | string | 탈퇴 전 유의사항. 쇼핑몰이 끄면 없음 |
| guide_message_after | string | 탈퇴 완료 화면 문구. 쇼핑몰이 끄면 없음 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 442 | WITHDRAWAL_NOT_ENABLED |
쇼핑몰이 회원 탈퇴 기능을 쓰지 않음 |
| 403 | USER_SESSION_INVALID |
비회원 |
| 401 | USER_SESSION_INVALID |
JWT·user_id 모두 없음, 또는 JWT 세션 만료·로그아웃 — 회원 JWT 참고 |
| 401 | USER_JWT_INVALID |
위조·만료된 JWT |
| 403 | USER_NOT_MATCH |
JWT 회원과 user_id 회원이 다름 |
| 404 | USER_NOT_FOUND |
user_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님 |
| 400 | API_PARAM_INVALID |
secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 JWT 없이
user_id로도 회원을 정할 수 있게 변경 - 2026-09-21 추가
POST /v1/users/me/withdrawal
본인 회원 탈퇴. 성공하면 현재 세션이 바로 끊기고, 이후 모든 본인 API 는 JWT 로 부르면 401 USER_SESSION_INVALID, 같은 user_id 로 부르면 404 USER_NOT_FOUND 를 줍니다. requires_login: true 를 받으면 저장한 JWT 와 쇼핑몰 서버의 로그인 세션을 지우고 로그인 화면으로 보내세요.
탈퇴 후 재가입은 탈퇴 후 재가입 제한을 따릅니다. 가맹점 관리용 DELETE /v1/users/:id 와 달리 진행 중 주문·구독 확인, 보관기간, 재가입 제한을 모두 거치므로 회원 본인의 탈퇴 버튼에는 이 API 를 쓰세요.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_me_withdrawal - 회원:
Bootpay-User-JWT또는user_id중 하나 필수 — 회원 JWT. 둘 다 보내면 JWT 가 우선이고,user_id가 다른 회원이면403 USER_NOT_MATCH입니다.user_id는 secretKey(Basic)·Bearer 인증일 때만 받습니다.
user_id로 부를 때 간편 로그인 전용 계정(confirm_method: phrase)은 비밀번호가 없어 Commerce 가 본인을 확인할 수 없습니다(확인 문구는 고정값). 이 회원이 로그인한 상태에서 직접 탈퇴를 요청했는지는 쇼핑몰 서버가 책임지고 확인해야 합니다. 탈퇴는 되돌릴 수 없습니다.
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | JWT 없으면 O | 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다 |
|
| body | reason | string | O | 탈퇴 사유. low_usage 자주 이용하지 않음, product 상품/서비스 불만족, benefit 가격/혜택 불만족, privacy 개인정보 우려, rejoin 새 계정으로 다시 가입 예정, etc 기타 |
|
| body | reason_text | string | 상세 사유 | ||
| body | retention_type | string | O | 개인정보 보관기간. immediate | year_1 | year_3 |
|
| body | password | string | password 방식 O |
현재 비밀번호 | |
| body | confirm_phrase | string | phrase 방식 O |
탈퇴합니다 |
응답
200 OK
{
"withdrawn": true,
"requires_login": true,
"purge_scheduled_at": "2027-09-23T10:00:00.000+09:00"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| withdrawn | boolean | 항상 true (실패는 오류로 옵니다) |
| requires_login | boolean | 항상 true |
| purge_scheduled_at | string | null | 보관 개인정보 파기 예정 시각. immediate 면 null |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | REQUIRED_PARAMETER_IS_MISSING |
reason 없음 또는 목록에 없는 값 |
| 400 | WITHDRAWAL_RETENTION_INVALID |
retention_type 없음 또는 잘못된 값 |
| 400 | WITHDRAWAL_CONFIRM_INVALID |
비밀번호 또는 확인 문구 불일치 |
| 442 | WITHDRAWAL_BLOCKED_ACTIVE_SUBSCRIPTION |
이용 중인 정기구독이 있음 |
| 442 | WITHDRAWAL_BLOCKED_ACTIVE_ORDER |
진행 중인 주문이 있음 |
| 442 | WITHDRAWAL_NOT_ENABLED |
쇼핑몰이 회원 탈퇴 기능을 쓰지 않음 |
| 403 | USER_SESSION_INVALID |
비회원 |
| 401 | USER_SESSION_INVALID |
JWT·user_id 모두 없음, 또는 JWT 세션 만료·로그아웃 — 회원 JWT 참고 |
| 401 | USER_JWT_INVALID |
위조·만료된 JWT |
| 403 | USER_NOT_MATCH |
JWT 회원과 user_id 회원이 다름 |
| 404 | USER_NOT_FOUND |
user_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님 — 이미 탈퇴한 회원 포함 |
| 400 | API_PARAM_INVALID |
secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 JWT 없이
user_id로도 회원을 정할 수 있게 변경 - 2026-09-21 추가
POST /v1/users/password-recovery/requests
비밀번호 찾기 1단계. 이 쇼핑몰에 등록된 회원 연락처(이메일 또는 휴대폰)로 6자리 인증코드를 보냅니다.
계정이 있는지 드러내지 않기 위해 회원이 없어도, 연락처가 없어도, 발송이 실패해도 같은 응답을 줍니다. 받는 곳은 지정할 수 없습니다 — email, phone, contact 키를 보내면 거절합니다(세 단계 모두 같음).
회원은 login_id → challenge_id → reset_token 으로만 정해집니다. Bootpay-User-JWT 는 읽지 않고, user_id·user_ex_uid·user_external_uid·user_uid 키를 보내면 거절합니다(세 단계 모두 같음).
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_password_recovery - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | login_id | string | O | 로그인 아이디 (이메일 가입 몰은 이메일) | |
| body | channel | string | O | email | phone |
응답
200 OK
{
"accepted": true,
"retry_after": 60,
"challenge_id": "5c0e8f2a9b..."
}json| 필드 | 타입 | 설명 |
|---|---|---|
| accepted | boolean | 항상 true |
| retry_after | integer | 다시 요청할 수 있을 때까지 남은 초. 이 시간 안에 다시 요청하면 코드를 새로 보내지 않습니다 |
| challenge_id | string | 2단계에 보낼 값 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | API_PARAM_INVALID |
channel 이 email/phone 이 아님(payload.field), 받는 곳 키 또는 user_id 계열 키를 보냄(payload.rejected_params) |
| 400 | USER_LOGIN_ID_BLANK |
login_id 없음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28
user_id계열 키 거절(세 단계 모두) - 2026-09-21 추가
POST /v1/users/password-recovery/verifications
비밀번호 찾기 2단계. 인증코드를 확인하고 일회성 재설정 토큰을 줍니다. 인증코드는 발송 후 3분 안에 입력해야 하며, 여러 번 틀리면 이 요청은 더 쓸 수 없고 1단계부터 다시 해야 합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_password_recovery - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | challenge_id | string | O | 1단계 응답의 값 | |
| body | code | string | O | 받은 6자리 인증코드 |
응답
200 OK
{
"reset_token": "eyJhbGciOiJIUzI1NiJ9...",
"expires_at": "2026-09-23T01:10:00Z"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| reset_token | string | 3단계에 보낼 일회성 토큰 |
| expires_at | string | 토큰 만료 시각 (UTC, 발급 후 10분) |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | FIND_PASSWORD_VERIFY_CODE_BLANK |
code 없음 |
| 404 | VERIFICATION_CODE_EXPIRED |
없는·이미 쓴·다른 쇼핑몰의 challenge_id |
| 400 | VERIFICATION_CODE_EXPIRED |
코드 불일치 또는 3분 경과 |
| 400 | VERIFICATION_ATTEMPT_EXCEEDED |
시도 횟수 초과 — 1단계부터 다시 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-21 추가
PUT /v1/users/password-recovery/password
비밀번호 찾기 3단계. 재설정 토큰으로 새 비밀번호를 저장합니다. 회원은 토큰이 정하므로 아이디를 보내지 않습니다. 성공하면 이 회원의 기존 로그인이 모두 끊기고, 회원에게 변경 알림이 갑니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_password_recovery - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | reset_token | string | O | 2단계 응답의 값. 한 번만 쓸 수 있습니다 | |
| body | new_password | string | O | 8자 이상, 72바이트 이하 | |
| body | new_password_confirmation | string | 보내면 new_password 와 같은지 확인합니다 |
응답
200 OK
{
"changed": true,
"requires_login": true
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 401 | FIND_PASSWORD_RESET_TOKEN_INVALID |
토큰 없음·위조·만료·다른 쇼핑몰의 토큰, 탈퇴한 회원 |
| 410 | FIND_PASSWORD_RESET_TOKEN_USED |
이미 사용한 토큰 |
| 400 | USER_PASSWORD_BLANK |
새 비밀번호 없음 |
| 400 | USER_PASSWORD_FORMAT_INVALID |
8자 미만 |
| 400 | CUSTOMER_FIELD_TOO_LONG |
72바이트 초과 |
| 400 | USER_PASSWORD_CONFIRM_NOT_MATCH |
확인 값 불일치 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-21 추가
GET /v1/users/address
회원 배송지 목록. 기본 배송지가 먼저, 그다음 최근 사용 순입니다. 페이지를 나누지 않습니다.
배송지 API 4종은 회원을 두 방식 중 하나로 정합니다.
- JWT:
Bootpay-User-JWT를 보냅니다. 대상은 JWT 의 회원입니다.user_id를 함께 보내면 본인일 때만 허용합니다(다르면403 USER_NOT_MATCH). - user_id: JWT 없이
user_id로 회원을 지정합니다. secretKey(Basic)·Bearer 인증일 때만 받습니다. 탈퇴한 회원은 찾지 않습니다.
scope 는 두 방식 모두 필요합니다. JWT 도 user_id 도 없으면 401 USER_SESSION_INVALID 입니다. 다른 회원의 배송지 ID 는 없는 배송지와 같은 404 로 답합니다.
user_id 는 24자리 회원 ID 형식이면 회원 ID, 아니면 가맹점 회원 고유 ID(external_uid)로 찾습니다. user_ex_uid·user_external_uid·user_uid 키도 받습니다. 로그인 아이디로 지정하려면 user_id 대신 login_id 를 보냅니다(둘 다 보내면 같은 회원이어야 합니다).
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_detail(JWT·user_id모두) - 회원:
Bootpay-User-JWT또는user_id중 하나 필수 — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | user_id | string | JWT 없으면 O | 회원 ID 또는 가맹점 회원 고유 ID(external_uid) |
응답
200 OK
{
"list": [
{
"address_id": "66f2...",
"address_uid": "shop-addr-1",
"alias_name": "집",
"name": "홍길동",
"phone": "01012345678",
"zipcode": "06236",
"address": "서울 강남구 테헤란로 1",
"address_detail": "101호",
"is_default": true
}
],
"count": 1
}json| 필드 | 타입 | 설명 |
|---|---|---|
| list[].address_id | string | 배송지 ID |
| list[].address_uid | string | null | 등록 시 보낸 가맹점 배송지 고유 ID |
| list[].alias_name | string | 별칭 |
| list[].name / phone | string | 받는 사람 이름·연락처 |
| list[].zipcode / address / address_detail | string | 우편번호·주소·상세주소 |
| list[].is_default | boolean | 기본 배송지 여부 (회원당 최대 1개) |
| count | integer | 배송지 수 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 401 | USER_SESSION_INVALID |
JWT 도 user_id 도 없음, 또는 JWT 세션이 유효하지 않음 |
| 401 | USER_JWT_INVALID |
위조·만료된 JWT |
| 403 | USER_NOT_MATCH |
JWT 회원과 user_id 회원이 다름 |
| 404 | USER_NOT_FOUND |
(user_id) 없는 회원 또는 탈퇴한 회원 |
| 400 | API_PARAM_INVALID |
secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 JWT 방식에도 scope 를 요구,
user_ex_uid·user_external_uid·user_uid키 추가 - 2026-09-14 추가 (구매자·서버 호출 분리)
POST /v1/users/address
배송지 추가. 회원의 첫 배송지는 자동으로 기본 배송지가 됩니다. 호출 방식은 GET /v1/users/address를 봅니다.
address_uid 를 보내면 재시도에 안전합니다. 같은 회원이 같은 address_uid·같은 내용으로 다시 보내면 새로 만들지 않고 기존 address_id 를 돌려줍니다. 내용이 다르거나 다른 회원이 쓰는 address_uid 면 409 입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_create(JWT·user_id모두) - 회원:
Bootpay-User-JWT또는user_id중 하나 필수 — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | JWT 없으면 O | 회원 ID 또는 external_uid |
|
| body | name | string | O | 받는 사람. 50자 이하 | |
| body | phone | string | O | 숫자 8~15자리 (하이픈 허용) | |
| body | zipcode | string | O | 5자리 (구 우편번호 123-456 허용) |
|
| body | address | string | O | 200자 이하 | |
| body | address_detail | string | O | 200자 이하 | |
| body | alias_name | string | 배송지 |
별칭. 50자 이하 | |
| body | is_default | boolean | false | true 면 기본 배송지로 지정 | |
| body | address_uid | string | 가맹점 배송지 고유 ID. 100자 이하. ex_uid, external_uid, uid 키도 받습니다 |
응답
200 OK
{
"address_id": "66f2..."
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | API_PARAM_INVALID |
필수 필드 누락 |
| 400 | CUSTOMER_PHONE_INVALID |
전화번호 형식 오류 |
| 400 | ADDRESS_ZIPCODE_INVALID |
우편번호 형식 오류 |
| 400 | CUSTOMER_FIELD_TOO_LONG |
길이 초과 (payload.field, payload.max_length) |
| 409 | ADDRESS_ALREADY_EXISTS |
address_uid 가 다른 내용·다른 회원·삭제된 배송지에 이미 쓰임 |
| 404 | USER_GROUP_NOT_FOUND |
회원의 개인 그룹을 찾거나 만들 수 없음 |
| 401 / 403 / 404 | USER_SESSION_INVALID · USER_JWT_INVALID / USER_NOT_MATCH / USER_NOT_FOUND |
GET /v1/users/address 와 같음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 JWT 방식에도 scope 를 요구
- 2026-09-14
address_uid재시도 처리, 입력 형식 검증 추가
PUT /v1/users/address/:address_id
배송지 수정. 보낸 필드만 바꿉니다. PATCH 도 같습니다. 이미 주문에 쓰인 배송지를 고쳐도 기존 주문의 배송지는 바뀌지 않습니다. 호출 방식은 GET /v1/users/address를 봅니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_update(JWT·user_id모두) - 회원:
Bootpay-User-JWT또는user_id중 하나 필수 — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | address_id | string | O | 배송지 ID | |
| body | user_id | string | JWT 없으면 O | 회원 ID 또는 external_uid |
|
| body | name / phone / zipcode / address / address_detail | string | 보낸 값만 반영. 빈 값으로 지울 수 없습니다 | ||
| body | alias_name | string | 빈 값이면 무시 | ||
| body | is_default | boolean | true 기본 배송지로 지정, false 해제 |
바꿀 필드와 is_default 가 모두 없으면 400 API_PARAM_INVALID 입니다.
응답
200 OK
{
"address_id": "66f2..."
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | ADDRESS_NOT_FOUND |
없는·삭제된·다른 회원의 배송지 |
| 400 | API_PARAM_INVALID |
바꿀 값이 없음, 필수 필드를 빈 값으로 보냄 |
| 400 | CUSTOMER_PHONE_INVALID / ADDRESS_ZIPCODE_INVALID / CUSTOMER_FIELD_TOO_LONG |
형식·길이 오류 |
| 401 / 403 / 404 | USER_SESSION_INVALID · USER_JWT_INVALID / USER_NOT_MATCH / USER_NOT_FOUND |
GET /v1/users/address 와 같음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 JWT 방식에도 scope 를 요구
- 2026-09-14 추가
DELETE /v1/users/address/:address_id
배송지 삭제. 기본 배송지를 지우면 가장 최근에 쓴 배송지가 기본 배송지가 됩니다. 기존 주문의 배송지에는 영향이 없습니다. 호출 방식은 GET /v1/users/address를 봅니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_update(JWT·user_id모두) - 회원:
Bootpay-User-JWT또는user_id중 하나 필수 — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | address_id | string | O | 배송지 ID | |
| query | user_id | string | JWT 없으면 O | 회원 ID 또는 external_uid |
응답
200 OK
{
"success": true
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | ADDRESS_NOT_FOUND |
없는·이미 삭제된·다른 회원의 배송지 |
| 401 / 403 / 404 | USER_SESSION_INVALID · USER_JWT_INVALID / USER_NOT_MATCH / USER_NOT_FOUND |
GET /v1/users/address 와 같음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 JWT 방식에도 scope 를 요구
- 2026-09-14 추가
POST /v1/users/join
가맹점의 기존 회원을 부트페이 회원으로 옮깁니다(외부 동기화). 약관 동의·탈퇴 후 재가입 제한·이메일 인증을 거치지 않으므로 서버 간 이관 전용입니다. 구매자 신규 가입은 POST /v1/users/signup 을 씁니다. JWT 는 발급하지 않습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_create - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | name | string | O | 이름 | |
| body | ex_uid | string | 가맹점 회원 고유 ID. 프로젝트 안에서 중복 불가. external_uid, uid 키도 받습니다 |
||
| body | login_id | string | 아이디 가입 몰 O | 영문·숫자 5~30자 | |
| body | login_email | string | 이메일 가입 몰 O | email 값 |
로그인 이메일 |
| body | login_pw | string | O | 8자 이상. extra.skip_password 가 true 면 생략 가능(비밀번호 없는 계정) |
|
| body | string | 연락 이메일 | |||
| body | phone / tel | string | 휴대폰·전화번호 | ||
| body | nickname | string | 닉네임 | ||
| body | comment | string | 판매자 메모 | ||
| body | gender | integer | 값 코드 | ||
| body | birth | string | 생년월일 6자리 | ||
| body | individual_extension | object | 가맹점 정의 추가 정보 | ||
| body | join_at | string | 요청 시각 | 원래 가입일 (시각 문자열) | |
| body | user_group_id | string | 추가로 소속시킬 그룹 ID | ||
| body | is_group_admin | boolean | false | 그 그룹의 관리자로 지정 | |
| body | extra | object | skip_password 만 사용 |
응답
200 OK — 회원 상세. 형식은 GET /v1/users/:id 와 같습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | API_PARAM_INVALID |
name 없음 |
| 400 | USER_EXTERNAL_UID_EXIST |
이미 쓰는 ex_uid |
| 400 | USER_ID_BLANK / USER_ID_INVALID / USER_ID_EXIST |
(아이디 가입 몰) 아이디 없음 / 형식 오류 / 이미 사용 중 |
| 400 | USER_EMAIL_BLANK / USER_EMAIL_INVALID / USER_EMAIL_EXIST |
로그인 이메일 없음 / 형식 오류 / 이미 사용 중 |
| 400 | USER_PASSWORD_FORMAT_INVALID |
login_pw 없음 또는 8자 미만 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
GET /v1/users/join/:id
가입 전 중복 확인. :id 에 확인 종류를, pk 에 확인할 값을 넣습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_check_exist - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | email-exist | id-exist | phone-exist | uid-exist(회원 ID·external_uid) | group-business-number-exist(기업 사업자번호) |
|
| query | pk | string | O | 확인할 값 |
phone-exist: 하이픈·공백을 빼고 비교합니다.010-1234-5678과01012345678은 같은 번호입니다.email-exist: 앞뒤 공백만 빼고 가입 때 받은 값과 그대로 비교합니다. 이메일을 수집하지 않는 몰에서 가입한 회원은 찾지 못해false가 옵니다.
응답
200 OK
{
"exist": true,
"data": null
}json| 필드 | 타입 | 설명 |
|---|---|---|
| exist | boolean | 이미 있으면 true |
| data | object | null | group-business-number-exist 로 찾은 기업 그룹 정보. 다른 종류는 null |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | API_PARAM_INVALID |
pk 없음, 지원하지 않는 확인 종류 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28
phone-exist가 항상false이던 결함 수정(저장 해시와 같은 방식으로 비교) - 2026-09-23 문서 최초 작성
GET /v1/users/join/:id/detail
회원 ID·external_uid·로그인 아이디로 회원 상세를 조회합니다. 탈퇴한 회원도 조회됩니다(status: -1).
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_detail - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 회원 ID 또는 external_uid |
응답
200 OK — 형식은 GET /v1/users/:id 와 같습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | USER_NOT_FOUND |
없는 회원 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
POST /v1/users/login/token
서버 전용. 비밀번호 없이 회원을 지정해 회원 JWT 를 발급합니다. 가맹점이 자체 로그인을 끝낸 회원을 부트페이 쇼핑몰 세션으로 넘길 때 씁니다. 이 API 를 부를 수 있는 키는 어떤 회원으로든 로그인할 수 있으므로 secretKey 를 절대 브라우저·앱에 두지 마세요.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_login_token - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | O | 회원이면 회원 ID 또는 로그인 아이디(이메일 가입 몰은 이메일). 비회원이면 가맹점이 정한 비회원 고유 ID | |
| body | membership_type | string | member |
member | guest |
|
| body | corporate_type | string | individual |
individual | corporate — 세션을 열 그룹 (회원만) |
membership_type: "guest" 이면 user_id 로 비회원을 찾고, 없으면 그 ID 로 비회원을 새로 만든 뒤 토큰을 발급합니다.
응답
200 OK
{
"token": "eyJhbGciOiJSUzI1NiJ9..."
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | REQUIRED_PARAMETER_IS_MISSING |
user_id 없음 — payload.field: user_id |
| 400 | INVOICE_TARGET_NOT_FOUND |
(회원) 해당하는 정상 회원이 없음 |
| 400 | USER_CORPORATE_TYPE_INVALID |
corporate_type 이 individual/corporate 가 아님 |
| 400 | MALL_CORPORATE_TYPE_NOT_ALLOWED |
기업 회원을 받지 않는 쇼핑몰에 corporate 요청 |
| 400 | USER_GROUP_NOT_FOUND |
요청한 유형의 그룹이 회원에게 없음 |
| 400 | USER_PENDING_APPROVAL |
판매자 승인 대기 중인 계정 |
| 404 | USER_LOGIN_FAILED |
사용 중지된 계정 등 로그인 불가 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28
user_id누락 응답을404 API_PARAM_INVALID→400 REQUIRED_PARAMETER_IS_MISSING으로 변경 - 2026-09-23 문서 최초 작성
POST /v1/users/token
로그인 회원의 부트페이 결제 사용자 토큰과 결제 위젯 키를 받습니다. 저장된 결제수단을 여는 토큰이므로 서버에서만 호출하세요.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_token - 회원:
Bootpay-User-JWT또는user_id중 하나 필수 — 회원 JWT. 둘 다 보내면 JWT 가 우선이고,user_id가 다른 회원이면403 USER_NOT_MATCH입니다.user_id는 secretKey(Basic)·Bearer 인증일 때만 받습니다.
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | JWT 없으면 O | 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다 |
응답
200 OK
{
"user_token": "...",
"application_id": "...",
"normal_widget_key": "...",
"subscription_widget_key": "..."
}json| 필드 | 타입 | 설명 |
|---|---|---|
| user_token | string | 부트페이 결제 사용자 토큰 |
| application_id | string | 결제 연동 application ID |
| normal_widget_key / subscription_widget_key | string | 일반·정기 결제 위젯 키 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 401 | USER_SESSION_INVALID |
JWT·user_id 모두 없음, 또는 JWT 세션 만료·로그아웃 |
| 401 | USER_JWT_INVALID |
위조·만료된 JWT |
| 403 | USER_NOT_MATCH |
JWT 회원과 user_id 회원이 다름 |
| 404 | USER_NOT_FOUND |
user_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님 |
| 400 | API_PARAM_INVALID |
secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required |
| 400 | USER_NO_LOGIN_ID |
로그인 아이디가 없는 계정 |
| 500 | API_NOT_PERMIT |
부트페이 결제 서버가 토큰 발급을 거절 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을
Bootpay-User-JWT또는user_id로 정하도록 변경(이전에는 항상 401), scopeuser:user_token신설 - 2026-09-23 문서 최초 작성
POST /v1/users/wallet
회원 그룹의 결제수단(지갑) 목록을 돌려줍니다. 부트페이 결제 서버가 새 지갑을 알려 주면 반영한 뒤 돌려줍니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_wallet - 회원:
Bootpay-User-JWT또는user_id중 하나 필수 — 회원 JWT. 둘 다 보내면 JWT 가 우선이고,user_id가 다른 회원이면403 USER_NOT_MATCH입니다.user_id는 secretKey(Basic)·Bearer 인증일 때만 받습니다.
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | JWT 없으면 O | 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다 |
|
| body | corporate_type | integer | O | 지갑을 볼 그룹. 1 개인, 2 기업 |
응답
200 OK — 지갑 목록 배열. 등록된 지갑이 없으면 []. 빌링키는 포함하지 않습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 401 | USER_SESSION_INVALID |
JWT·user_id 모두 없음, 또는 JWT 세션 만료·로그아웃 |
| 401 | USER_JWT_INVALID |
위조·만료된 JWT |
| 403 | USER_NOT_MATCH |
JWT 회원과 user_id 회원이 다름 |
| 404 | USER_NOT_FOUND |
user_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님 |
| 400 | API_PARAM_INVALID |
secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required |
| 404 | USER_GROUP_NOT_FOUND |
요청한 유형의 그룹이 없음 |
| 500 | API_NOT_PERMIT |
부트페이 결제 서버가 요청을 거절 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을
Bootpay-User-JWT또는user_id(또는login_id) 로 정하도록 변경(이전에는 항상 401), scopeuser:user_wallet신설 - 2026-09-28 응답을 지갑 목록으로 고정(이전에는 없는 메서드 호출로 항상 500)
- 2026-09-23 문서 최초 작성
GET /v1/users
회원 목록(판매자·서버용). 정상 상태 회원만, 최근 가입 순입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_list - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | type | string | user |
user 회원 검색 | user_group 그룹 소속 회원 |
|
| query | keyword | string | type=user: 회원 ID, 또는 이름·전화번호·이메일 전체 값(부분 일치 안 됨, 하이픈·대소문자 차이는 허용). type=user_group: 그룹 ID |
||
| query | membership_type | integer | 전체 | 1 회원, 2 비회원 |
|
| query | page | integer | 1 | 1 이상 | |
| query | limit | integer | 24 | 최대 100 |
이 API 는 페이지네이션 공통 규칙과 다릅니다. 기본 limit 이 24 이고, page·limit 에 1 미만 값을 보정하지 않으므로 1 이상 값을 보내세요.
응답
200 OK
{
"list": [
{
"user_id": "66f1...",
"login_id": "gildong01",
"name": "홍길동",
"phone": "01012345678",
"email": "gildong@example.com",
"membership_type": 1,
"corporate_type": 1,
"status": 1,
"user_groups": [],
"social_login_providers": [],
"created_at": "2026-09-01T10:00:00+09:00",
"updated_at": "2026-09-01T10:00:00+09:00"
}
],
"count": 1
}jsonlist 항목은 GET /v1/users/:id 응답에서 deletable 을 뺀 형식입니다. count 는 조건에 맞는 전체 수입니다.
오류
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-03
keyword가 하이픈·대소문자가 다른 표기도 찾도록 변경
GET /v1/users/:id
회원 상세(판매자·서버용). 탈퇴한 회원은 400 USER_DELETED 입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_detail - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 회원 ID 또는 external_uid |
응답
200 OK — 값이 없는 필드는 응답에서 빠집니다.
{
"user_id": "66f1...",
"external_uid": "shop-user-1",
"login_id": "gildong01",
"login_types": [1],
"name": "홍길동",
"phone": "01012345678",
"email": "gildong@example.com",
"membership_type": 1,
"corporate_type": 1,
"gender": 1,
"birth": "900101",
"comment": "VIP",
"tags": [],
"auth_sms": false,
"auth_phone": false,
"auth_email": true,
"count": 3,
"status": 1,
"user_groups": [
{
"user_group_id": "66f1...",
"corporate_type": 1,
"zip": "06236",
"addr1": "서울 강남구 테헤란로 1",
"addr2": "101호"
}
],
"social_login_providers": [],
"created_at": "2026-09-01T10:00:00+09:00",
"updated_at": "2026-09-20T12:00:00+09:00"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| user_id | string | 회원 ID |
| external_uid | string | 가맹점 회원 고유 ID |
| login_id | string | 로그인 아이디 |
| login_types | integer[] | 가입 방식 |
| name / phone / email | string | 평문 값 |
| membership_type / corporate_type / gender / status | integer | 값 코드 |
| birth | string | 생년월일 6자리 |
| comment | string | 판매자 메모 |
| tags / metadata / individual_extension | array / object | 판매자·가맹점이 붙인 태그와 추가 정보 |
| auth_sms / auth_phone / auth_email | boolean | 인증 완료 여부 |
| count | integer | 결제 횟수 |
| user_groups | array | 소속 그룹(개인·기업·부서)과 그룹 연락처·주소 |
| social_login_providers | array | null | 연결된 간편 로그인 공급자 코드. 일반 가입이면 [] |
| removed_at | string | 탈퇴 시각 (탈퇴 회원) |
| withdrawal_reason / withdrawal_reason_text | string | 셀프 탈퇴 사유 (탈퇴 회원) |
| withdrawal_retention_type | string | 탈퇴 시 선택한 보관기간 (탈퇴 회원) |
| purged_at | string | 개인정보 파기 완료 시각 |
| withdrawal_block_code | string | 재가입 문의 코드 RJ-XXXX-XXXX (탈퇴 회원) |
| deletable | boolean | (비회원만) 청구서·주문 이력이 없어 삭제할 수 있는지 |
| created_at / updated_at | string | 생성·수정 시각 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | USER_NOT_FOUND |
없는 회원 |
| 400 | USER_DELETED |
탈퇴한 회원 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
PUT /v1/users/:id
회원 정보 수정(판매자·서버용). 값이 있는 필드만 바꾸며, 빈 값으로 지울 수 없습니다. PATCH 도 같습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_update - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 회원 ID 또는 external_uid |
|
| body | name | string | 이름 | ||
| body | phone / tel | string | 휴대폰·전화번호 (하이픈 제거 후 저장) | ||
| body | string | 이메일. 이메일 수집 몰이면 형식을 확인합니다 | |||
| body | nickname | string | 닉네임 | ||
| body | gender | integer | 값 코드 | ||
| body | birth | string | 생년월일 6자리 | ||
| body | comment | string | 판매자 메모 | ||
| body | bank_username / bank_account / bank_code | string | 환불 계좌 예금주·계좌번호·은행 코드 | ||
| body | login_id | string | 로그인 아이디 (형식·중복을 확인하지 않습니다) | ||
| body | password | string | 새 비밀번호. login_pw 키도 받습니다. 형식을 확인하지 않고, 기존 로그인을 끊지 않습니다 |
||
| body | phone_hash / email_hash | string | 로그인·검색용 연락처 값 | ||
| body | marketing_accept_type | integer | 마케팅 수신 동의 유형 |
group.company_name, group.business_number, group.registration_number, login_type, term_ids 는 받지만 반영하지 않습니다.
응답
200 OK — 수정된 회원 상세. 형식은 GET /v1/users/:id 와 같습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_NOT_FOUND |
없는 회원 |
| 400 | USER_EMAIL_INVALID |
이메일 형식 오류 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
DELETE /v1/users/:id
회원을 탈퇴 상태(status: -1)로 바꿉니다(판매자·서버용). 이 회원의 기존 로그인은 모두 거부됩니다.
본인 탈퇴(POST /v1/users/me/withdrawal)와 달리 진행 중 주문·구독 확인, 개인정보 파기·보관 처리, 탈퇴 후 재가입 제한을 거치지 않습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_delete - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 회원 ID 또는 external_uid |
응답
200 OK — 탈퇴 처리된 회원 상세. 형식은 GET /v1/users/:id 와 같습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | USER_NOT_FOUND |
없는 회원 |
| 400 | USER_DELETED |
이미 탈퇴한 회원 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
