회원 그룹은 구매 주체 단위입니다. 개인 회원도 내부적으로 개인 그룹 하나를 갖고, 기업(사업자) 은 여러 회원이 함께 속하는 그룹입니다. 기업 아래에는 부서(또는 지점) 그룹을 둘 수 있습니다. 이 문서의 API 로 기업 그룹을 만들고, 구매 한도·합산 결제일을 정하고, 구성원·배송지·초대를 관리합니다.
그룹 유형 (corporate_type)
| 숫자 | 목록 응답 문자열 | 뜻 |
|---|---|---|
| 1 | individual |
개인 |
| 2 | business |
기업 |
| 3 | department |
부서·지점 (기업의 하위 그룹) |
요청 파라미터로 보낼 때는 숫자를 씁니다. 목록(GET /v1/user-groups)의 항목은 문자열로, 생성·상세 응답은 숫자로 나갑니다.
그룹 안의 역할
| 역할 | 할 수 있는 일 |
|---|---|
| 기업 관리자 | 기업 전체 부서에 초대 생성·취소·재발송 |
| 부서장(지점장) | 자기 부서에 한해 초대 생성·취소·재발송 |
| 구성원 | 그룹 소속으로 구매. 그룹 관리 권한 없음 |
대부분의 API 는 가맹점 서버가 secretKey 로 호출하는 관리용이라 호출하는 회원의 역할을 보지 않습니다. 역할을 확인하는 API 는 각 절의 인증에 따로 적었습니다. POST /v1/user-groups/:user_group_id/user 로 추가한 회원은 구성원이 됩니다.
그룹 ID
:id·:user_group_id 에는 그룹 ID(user_group_id)를 넣습니다. 구성원 추가·제거와 배송지 등록은 생성 때 지정한 가맹점 고유값(uid)도 받습니다.
PUT /v1/user-groups/:id/limit
기업 그룹의 구매 한도(월·주)를 설정합니다. 한도를 넘는 정기구독 결제는 실패하고, 이때 limit_message 를 안내 문구로 씁니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
manager:limit(Bootpay-Role헤더와 무관하게 이 값으로 검사합니다) - 회원 JWT: 필요 없음. 호출자의 그룹 역할을 보지 않습니다
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 그룹 ID | |
| body | use_limit | boolean | 한도 사용 여부. JSON boolean 으로 보내세요. 문자열 "false" 는 켠 것으로 검증됩니다 |
||
| body | limit_month_purchase | number | 0 | 월 구매 한도 | |
| body | limit_week_purchase | number | 0 | 주 구매 한도 | |
| body | limit_message | string | 한도 초과 시 안내 문구. 보내지 않으면 기존 값 유지 |
limit_month_purchase·limit_week_purchase는 보내지 않으면 0 으로 저장됩니다. 기존 값을 유지하려면 현재 값을 다시 보내세요.use_limit가 참이면 월·주 한도가 모두 0 보다 커야 하고, 이미 구독 중인 금액(subscribed_month_limit·subscribed_week_limit)보다 작을 수 없습니다.
응답
200 OK
{
"use_limit": true,
"limit_month_purchase": 3000000.0,
"limit_week_purchase": 1000000.0,
"subscribed_month_limit": 450000.0,
"subscribed_week_limit": 0.0,
"limit_message": "월 구매 한도를 초과했습니다. 담당자에게 문의하세요."
}json| 필드 | 타입 | 설명 |
|---|---|---|
| use_limit | boolean | 한도 사용 여부 |
| limit_month_purchase | number | 월 구매 한도 |
| limit_week_purchase | number | 주 구매 한도 |
| subscribed_month_limit | number | 이미 구독 중인 금액(월) |
| subscribed_week_limit | number | 이미 구독 중인 금액(주) |
| limit_message | string | 한도 초과 안내 문구 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | USER_GROUP_NOT_FOUND |
없는 그룹 ID |
| 401 | USER_GROUP_NOT_AUTHORIZED |
다른 프로젝트의 그룹 |
| 400 | USER_GROUP_PURCHASE_LIMIT_REQUIRED |
한도를 켜면서 월 또는 주 한도가 0 이하 |
| 400 | USER_GROUP_PURCHASE_LIMIT_BELOW_SUBSCRIBED |
한도가 이미 구독 중인 금액보다 작음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
PUT /v1/user-groups/:id/aggregate-transaction
기업 그룹의 정기구독을 정해진 날 한 번에 합산 결제할지와 그 결제일을 설정합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
manager:aggregate_transaction(Bootpay-Role헤더와 무관) - 회원 JWT: 필요 없음. 호출자의 그룹 역할을 보지 않습니다
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 그룹 ID | |
| body | use_subscription_aggregate_transaction | boolean | 합산 결제 사용 여부 | ||
| body | subscription_month_day | integer | 월간 구독 합산 결제일(일자) | ||
| body | subscription_week_day | integer | 주간 구독 합산 결제 요일 |
보내지 않은 값은 바꾸지 않습니다. 결제일 값의 범위는 서버가 검사하지 않으니 유효한 값을 보내세요.
응답
200 OK
{
"use_subscription_aggregate_transaction": true,
"subscription_month_day": 25,
"subscription_week_day": 1
}json| 필드 | 타입 | 설명 |
|---|---|---|
| use_subscription_aggregate_transaction | boolean | 합산 결제 사용 여부 |
| subscription_month_day | integer | 월간 합산 결제일 |
| subscription_week_day | integer | 주간 합산 결제 요일 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | USER_GROUP_NOT_FOUND |
없는 그룹 ID |
| 401 | USER_GROUP_NOT_AUTHORIZED |
다른 프로젝트의 그룹 |
변경 이력
- 2026-09-23 문서 최초 작성
GET /v1/user-groups
프로젝트의 그룹 목록을 조회합니다. 기본은 기업 그룹만 나옵니다. 삭제된 그룹은 빠집니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_list(Bootpay-Role헤더를 보내면user자리가 그 값으로 바뀝니다) - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | keyword | string | 그룹 ID(정확히 일치) 또는 연락처·이메일·기업명·사업자번호·담당자명 등으로 검색 | ||
| query | corporate_type | integer | 2 | 그룹 유형 숫자 (1 개인, 2 기업, 3 부서). 문자열(business)은 쓰지 마세요 |
|
| query | page | integer | 1 | 페이지 | |
| query | limit | integer | 24 | 페이지 크기 |
이 API 는 공통 페이지네이션 보정 규칙을 쓰지 않습니다. 기본 limit 이 24 이고 상한이 없습니다. 1 이상 100 이하로 보내세요.
응답
200 OK
{
"list": [
{
"user_group_id": "66f0c1...",
"project_id": "5f...",
"corporate_type": "business",
"status": "active",
"company_name": "주식회사 부트",
"business_number": "1088603663",
"manager_name": "홍길동",
"phone": "01012345678",
"email": "buyer@example.com",
"use_subscription_aggregate_transaction": false,
"subscription_month_day": 1,
"subscription_week_day": 1,
"use_limit": false,
"limit_month_purchase": 0.0,
"limit_week_purchase": 0.0
}
],
"count": 1
}json| 필드 | 타입 | 설명 |
|---|---|---|
| list[].user_group_id | string | 그룹 ID |
| list[].seller_id / project_id | string | 판매자·프로젝트 ID |
| list[].user_id | string | 대표 회원 ID (있을 때) |
| list[].corporate_type | string | individual / business / department |
| list[].status | string | active / inactive / deleted |
| list[].sub_group_type | integer | 하위 조직 유형 (1 부서, 2 지점) |
| list[].require_department | boolean | 가입 시 부서 선택 필수 여부 |
| list[].company_name | string | 기업명 |
| list[].business_number | string | 사업자등록번호 (하이픈 없이 저장) |
| list[].registration_number | string | 법인등록번호 |
| list[].ceo_name | string | 대표자명 |
| list[].business_type / business_category | string | 업태 / 종목 |
| list[].manager_name | string | 담당자명 |
| list[].phone / email | string | 연락처 / 이메일 |
| list[].zipcode / address / address_detail | string | 주소 |
| list[].bank / bank_code | string | 계좌번호 / 은행 코드 |
| list[].auth_bank / auth_company | boolean | 계좌 인증 / 사업자 확인 여부 |
| list[].pccc | string | 개인통관고유부호 |
| list[].point / accumulation | number | 포인트 / 적립금 |
| list[].use_subscription_aggregate_transaction, subscription_month_day, subscription_week_day | 합산 결제 설정 | |
| list[].use_limit, limit_month_purchase, limit_week_purchase, subscribed_month_limit, subscribed_week_limit, limit_message | 구매 한도 설정 | |
| list[].count | integer | 결제 횟수 |
| list[].last_updated_at | string | 마지막 갱신 시각 (ISO 8601) |
| count | integer | 조건에 맞는 전체 개수 |
값이 없는(null) 필드는 응답에서 빠집니다.
오류
공통 오류만 있습니다. 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
POST /v1/user-groups
기업 그룹을 새로 만듭니다. 대표 회원 없이 기업 정보만 만들고, 회원은 구성원 추가나 초대로 채웁니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_create(Bootpay-Role로 역할 부분 변경 가능) - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | business_number | string | O | 사업자등록번호. 하이픈은 빼고 저장합니다. 프로젝트 안에서 중복 불가 | |
| body | company_name | string | 기업명 (서버가 필수 검사를 하지 않지만 보내는 것을 권장합니다) | ||
| body | uid | string | 가맹점 고유값. ex_uid·external_uid 로 보내도 됩니다. 프로젝트 안에서 중복 불가 |
||
| body | registration_number | string | 법인등록번호 | ||
| body | corporate_established | string | 설립일 | ||
| body | business_type | string | 업태 | ||
| body | manager_name / manager_phone / manager_email | string | 담당자 정보 | ||
| body | phone / email | string | 기업 연락처 / 이메일 | ||
| body | zipcode / address / address_detail | string | 주소 | ||
| body | bank / bank_code | string | 계좌번호 / 은행 코드 | ||
| body | auth_bank | boolean | 계좌 인증 여부 | ||
| body | pccc | string | 개인통관고유부호 | ||
| body | use_subscription_aggregate_transaction | boolean | false | 합산 결제 사용 | |
| body | subscription_month_day / subscription_week_day | integer | 1 | 합산 결제일 | |
| body | limit_month_purchase / limit_week_purchase | number | 0 | 구매 한도 금액 | |
| body | limit_message | string | 한도 초과 안내 문구 |
생성 시에는 use_limit 를 받지 않습니다. 한도를 켜려면 만든 뒤 PUT /v1/user-groups/:id/limit 을 호출하세요.
응답
200 OK
{
"user_group_id": "66f0c1...",
"corporate_type": 2,
"phone": "0212345678",
"email": "biz@example.com",
"zip": "06236",
"addr1": "서울 강남구 테헤란로 1",
"addr2": "10층",
"company_name": "주식회사 부트",
"business_number": "1088603663",
"manager_name": "홍길동",
"registration_number": "1101110000000",
"business_type": "서비스",
"business_category": null,
"sub_group_type": 1,
"sub_group_type_label": "부서",
"sub_group_manager_label": "부서장",
"use_sub_group": false,
"use_subscription_aggregate_transaction": false,
"subscription_month_day": 1,
"subscription_week_day": 1,
"use_limit": false,
"limit_month_purchase": 0.0,
"limit_week_purchase": 0.0,
"subscribed_month_limit": 0.0,
"subscribed_week_limit": 0.0,
"limit_message": null
}json| 필드 | 타입 | 설명 |
|---|---|---|
| user_group_id | string | 만든 그룹 ID |
| corporate_type | integer | 2 (기업) |
| phone / email | string | 연락처 / 이메일 |
| zip / addr1 / addr2 | string | 우편번호 / 주소 / 상세주소 (요청 키와 이름이 다릅니다) |
| company_name, business_number, manager_name, registration_number, business_type, business_category | string | 기업 정보 |
| sub_group_type | integer | 하위 조직 유형 (1 부서, 2 지점) |
| sub_group_type_label / sub_group_manager_label | string | 부서/지점, 부서장/지점장 |
| use_sub_group | boolean | 부서·지점 기능 사용 여부 |
| 합산 결제·한도 필드 | 한도·합산 결제 API 응답과 같음 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | USER_BUSINESS_NUMBER_BLANK |
business_number 없음 |
| 400 | USER_GROUP_BUSINESS_NUMBER_ALREADY_EXISTS |
같은 사업자번호의 기업 그룹이 이미 있음 |
| 400 | USER_GROUP_EXTERNAL_UID_EXIST |
같은 uid 의 그룹이 이미 있음 |
변경 이력
- 2026-09-23 문서 최초 작성
GET /v1/user-groups/:id
그룹 한 건의 정보를 조회합니다. 응답 필드는 그룹 유형에 따라 다릅니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_detail(Bootpay-Role로 역할 부분 변경 가능) - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 그룹 ID |
응답
200 OK — 기업 그룹의 예
{
"company_name": "주식회사 부트",
"business_number": "1088603663",
"manager_name": "홍길동",
"registration_number": "1101110000000",
"business_type": "서비스",
"business_category": null,
"sub_group_type": 1,
"sub_group_type_label": "부서",
"sub_group_manager_label": "부서장",
"use_sub_group": false,
"use_subscription_aggregate_transaction": false,
"subscription_month_day": 1,
"subscription_week_day": 1,
"use_limit": false,
"limit_month_purchase": 0.0,
"limit_week_purchase": 0.0,
"subscribed_month_limit": 0.0,
"subscribed_week_limit": 0.0,
"limit_message": null
}json유형별로 앞부분이 다릅니다. 합산 결제·한도 필드는 모든 유형에 붙습니다.
| 유형 | 추가 필드 |
|---|---|
| 개인(1) | point, accumulation, pccc |
| 기업(2) | 위 예시의 기업 정보 필드 |
| 부서(3) | name(부서명), company_name(부서명), 기업 정보 필드, parent_corporate(상위 기업의 user_group_id·company_name·business_number·manager_name·phone·email) |
이 응답에는 user_group_id·연락처·주소가 없습니다. 필요하면 목록 API 를 쓰세요.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | USER_GROUP_NOT_FOUND |
없거나 삭제된 그룹 |
| 401 | USER_GROUP_NOT_AUTHORIZED |
다른 프로젝트의 그룹 |
변경 이력
- 2026-09-23 문서 최초 작성
PUT /v1/user-groups/:id
그룹 정보를 수정합니다. 보낸 값만 바꿉니다. PATCH 도 같습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_update(Bootpay-Role로 역할 부분 변경 가능) - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 그룹 ID | |
| body | company_name, business_number, registration_number, corporate_established, business_type | string | 기업 정보 | ||
| body | manager_name / manager_phone / manager_email | string | 담당자 정보 | ||
| body | phone / email | string | 연락처 / 이메일 | ||
| body | zipcode / address / address_detail | string | 주소 | ||
| body | bank / bank_code | string | 계좌번호 / 은행 코드 | ||
| body | pccc | string | 개인통관고유부호 | ||
| body | corporate_type | integer | 그룹 유형. 보내면 유형이 바뀝니다. 유형을 바꿀 의도가 없으면 보내지 마세요 |
합산 결제(use_subscription_aggregate_transaction, subscription_month_day, subscription_week_day)와 한도(use_limit, limit_*) 값은 이 API 로 바꿀 수 없어 무시됩니다. 전용 API 를 쓰세요.
응답
200 OK — GET /v1/user-groups/:id 와 같은 형태
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | USER_GROUP_NOT_FOUND |
없거나 삭제된 그룹 |
| 401 | USER_GROUP_NOT_AUTHORIZED |
다른 프로젝트의 그룹 |
변경 이력
- 2026-09-23 문서 최초 작성
DELETE /v1/user-groups/:id
그룹을 삭제 상태로 바꿉니다. 목록에서 빠지고 상세 조회는 USER_GROUP_NOT_FOUND 가 됩니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_delete(Bootpay-Role로 역할 부분 변경 가능) - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 그룹 ID |
응답
200 OK, 본문 없음
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_GROUP_NOT_FOUND |
없는 그룹 ID |
| 401 | USER_GROUP_NOT_AUTHORIZED |
다른 프로젝트의 그룹 |
| 400 | USER_GROUP_DELETE_UNABLE |
이미 삭제된 그룹 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 scope
user:user_group_delete검사 추가
POST /v1/user-groups/address
그룹 배송지(주소록)에 주소를 추가합니다. 그룹의 첫 주소는 기본 배송지가 됩니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_address_create(Bootpay-Role로 역할 부분 변경 가능) - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_group_id | string | O | 그룹 ID 또는 그룹 생성 때 지정한 uid |
|
| body | name | string | O | 받는 사람 | |
| body | phone | string | O | 받는 사람 연락처 | |
| body | zipcode | string | O | 우편번호 | |
| body | address | string | O | 주소 | |
| body | address_detail | string | O | 상세주소 | |
| body | alias_name | string | 배송주소 |
배송지 이름 | |
| body | address_uid | string | 주소의 가맹점 고유값. 같은 값으로 두 번 등록되지 않게 막는 용도. ex_uid·external_uid·uid 로 보내도 됩니다 |
그룹당 등록할 수 있는 주소 수에 제한이 있습니다(약 10개).
응답
200 OK
{
"address_id": "66f0c9..."
}json| 필드 | 타입 | 설명 |
|---|---|---|
| address_id | string | 만든 주소 ID |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | REQUIRED_PARAMETER_IS_MISSING (131) |
필수 값 중 하나가 비어 있음. payload.field 에 빠진 이름 |
| 404 | USER_GROUP_NOT_FOUND |
이 프로젝트에 없는 그룹 |
| 409 | ADDRESS_ALREADY_EXISTS |
같은 address_uid 의 주소가 이미 있음 |
| 400 | ADDRESS_LIMIT_EXCEEDED |
주소록 개수 한도 초과 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 scope
user:user_group_address_create검사 추가, 필수 값 누락을404 API_PARAM_INVALID에서400 REQUIRED_PARAMETER_IS_MISSING으로 변경
POST /v1/user-groups/:user_group_id/user
기업 그룹에 회원을 구성원으로 추가합니다. 전에 제거된 회원이면 다시 활성화합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
manager:user_group_add_user(Bootpay-Role로 역할 부분 변경 가능) - 회원 JWT: 읽지 않습니다. 추가할 회원은
user_id로 지정합니다(가맹점 서버 관리용 API).user_id는 호출한 회원이 아니라 그룹에 넣을 대상 회원이며,Bootpay-User-JWT를 같이 보내도 무시합니다
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | user_group_id | string | O | 기업 그룹 ID 또는 uid |
|
| body | user_id | string | O | 대상 회원. 24자리 ObjectId 형식이면 회원 _id, 아니면 가맹점 회원 ID(ex_uid). user_ex_uid 로 보내도 됩니다. 로그인 ID 로는 찾지 않습니다 |
응답
200 OK, 본문 없음
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | USER_GROUP_NOT_FOUND |
이 프로젝트에 없는 그룹 |
| 400 | USER_GROUP_IS_NOT_CORPORATE |
기업 그룹이 아님 |
| 400 | REQUIRED_PARAMETER_IS_MISSING (131) |
user_id 없음 |
| 404 | USER_NOT_FOUND (2300) |
이 몰의 회원이 아님(없는 회원·다른 몰 회원·탈퇴 회원) |
| 400 | USER_ALREADY_IN_GROUP |
이미 이 그룹의 활성 구성원 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28
user_id를 대상 회원으로 해석(_id·ex_uid, 탈퇴 제외). 없는 회원은400에서404 USER_NOT_FOUND로, 탈퇴 회원은 추가되지 않고404. 로그인 ID 로 찾던 동작은 없어짐
DELETE /v1/user-groups/:user_group_id/user/:id
그룹에서 회원을 제거합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
manager:user_group_remove_user(Bootpay-Role로 역할 부분 변경 가능) - 회원 JWT: 읽지 않습니다. 경로의
id는 그룹에서 뺄 대상 회원입니다. 탈퇴한 회원의 역할도 정리할 수 있도록 탈퇴 여부는 보지 않습니다
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | user_group_id | string | O | 그룹 ID 또는 uid |
|
| path | id | string | O | 제거할 회원 ID, 가맹점 고유값 또는 로그인 ID |
응답
200 OK
truejson오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | USER_GROUP_NOT_FOUND |
이 프로젝트에 없는 그룹 |
| 400 | USER_NOT_FOUND |
이 프로젝트에 없는 회원 |
| 400 | USER_NOT_IN_GROUP |
이 그룹에 속한 적이 없는 회원 |
변경 이력
- 2026-09-23 문서 최초 작성
GET /v1/user-groups/:user_group_id/department/public
회원가입 화면에서 기업을 고른 뒤 부서·지점을 선택하게 할 때 쓰는 공개 부서 목록입니다. 이름만 돌려줍니다.
인증
- secretKey 가 필요 없습니다. 쇼핑몰 화면에서 호출하는 공개 API 입니다.
- 쇼핑몰은
Bootpay-Client-Key헤더(clientKey)로 식별합니다. 부트페이 쇼핑몰 도메인에서 호출하면 도메인으로도 식별합니다. - 쇼핑몰에 허용된 도메인에서만 호출할 수 있습니다.
- scope 검사 없음, 회원 JWT 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| header | Bootpay-Client-Key | string | O | 쇼핑몰 clientKey | |
| path | user_group_id | string | O | 기업 그룹 ID |
응답
200 OK
{
"departments": [
{ "user_group_department_id": "66f0d1...", "name": "영업팀" }
]
}json| 필드 | 타입 | 설명 |
|---|---|---|
| departments[].user_group_department_id | string | 부서 그룹 ID |
| departments[].name | string | 부서·지점 이름 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | PROJECT_CLIENT_KEY_NOT_FOUND |
clientKey 가 없음 |
| 404 | PROJECT_CK_NOT_FOUND |
없는 clientKey |
| 401 | PROJECT_DO_NOT_PERMIT |
허용되지 않은 도메인에서 호출 |
| 404 | USER_GROUP_NOT_FOUND |
이 쇼핑몰에 없는 그룹 |
| 400 | USER_GROUP_IS_NOT_CORPORATE |
기업 그룹이 아님 |
변경 이력
- 2026-09-23 문서 최초 작성
GET /v1/user-groups/:user_group_id/department
기업의 활성 부서 목록을 관리용 정보(인원·한도·부서장)와 함께 조회합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_department_list(Bootpay-Role로 역할 부분 변경 가능) - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | user_group_id | string | O | 기업 그룹 ID |
응답
200 OK — 배열 (페이지네이션 없음)
[
{
"user_group_department_id": "66f0d1...",
"name": "영업팀",
"member_count": 12,
"use_limit": true,
"limit_month_purchase": 1000000.0,
"limit_week_purchase": 300000.0,
"limit_message": null,
"manager": {
"user_id": "66e1...",
"name": "김부장",
"email": "kim@example.com",
"phone": "01011112222"
}
}
]json| 필드 | 타입 | 설명 |
|---|---|---|
| user_group_department_id | string | 부서 그룹 ID |
| name | string | 부서·지점 이름 |
| member_count | integer | 활성 구성원 수 |
| use_limit, limit_month_purchase, limit_week_purchase, limit_message | 부서 구매 한도 | |
| manager | object | null | 부서장. 없으면 null |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_GROUP_NOT_FOUND |
이 프로젝트에 없는 그룹 |
| 400 | USER_GROUP_IS_NOT_CORPORATE |
기업 그룹이 아님 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 scope
user:user_group_department_list검사 추가
POST /v1/user-groups/:user_group_id/invitation/:id/resend
초대를 다시 보냅니다. 만료일을 지금부터 7일로 늘리고 상태를 대기로 되돌린 뒤 초대 메일을 다시 보냅니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_invitation_resend(Bootpay-Role로 역할 부분 변경 가능) - 회원(선택):
Bootpay-User-JWT헤더 또는user_id파라미터 중 하나 — 기업 관리자 회원이 마이페이지에서 직원을 초대할 때처럼 쇼핑몰 서버가 그 회원을 지정합니다. JWT 가 우선이고, 둘이 다른 회원이면403 USER_NOT_MATCH,user_id가 이 몰 회원이 아니면404 USER_NOT_FOUND- 회원이 있으면 그 회원의 그룹 역할로 권한을 판정합니다: 기업 관리자는 모든 초대, 부서장은 자기 부서 초대만 재발송할 수 있습니다. 그 외는
403 INVITATION_PERMISSION_DENIED - 회원이 없으면 가맹점 권한(scope)으로 처리하며 그룹 역할을 보지 않습니다
- 회원이 있으면 그 회원의 그룹 역할로 권한을 판정합니다: 기업 관리자는 모든 초대, 부서장은 자기 부서 초대만 재발송할 수 있습니다. 그 외는
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | user_group_id | string | O | 기업 그룹 ID | |
| path | id | string | O | 초대 ID (invitation_id) |
응답
200 OK
{
"invitation_id": "66f0e1...",
"expires_at": "2026-09-30T10:00:00+09:00",
"status": 1
}json| 필드 | 타입 | 설명 |
|---|---|---|
| invitation_id | string | 초대 ID |
| expires_at | string | 새 만료 시각 |
| status | integer | 초대 상태. 초대 목록 API 의 상태표를 봅니다 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_GROUP_NOT_FOUND |
이 프로젝트에 없는 그룹 |
| 400 | USER_GROUP_IS_NOT_CORPORATE |
기업 그룹이 아님 |
| 404 | INVITATION_NOT_FOUND |
이 그룹의 초대가 아님 |
| 403 | INVITATION_PERMISSION_DENIED |
재발송 권한 없음 |
| 400 | INVITATION_CANCELLED |
취소된 초대 |
| 400 | INVITATION_REJECTED |
거절된 초대 |
| 403 | USER_NOT_MATCH (2302) |
JWT 회원과 user_id 가 다름 |
| 404 | USER_NOT_FOUND (2300) |
user_id 가 이 몰의 회원이 아님 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 항상
500이던 결함 수정. 회원(JWT 또는user_id)은 선택, 없으면 가맹점 권한. scopeuser:user_group_invitation_resend검사 추가
GET /v1/user-groups/:user_group_id/invitation
기업 그룹의 초대 목록을 최신순으로 조회합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_invitation_list(Bootpay-Role로 역할 부분 변경 가능) - 회원 JWT: 읽지 않습니다. 호출자의 그룹 역할을 보지 않습니다
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | user_group_id | string | O | 기업 그룹 ID | |
| query | department_id | string | 이 부서로 보낸 초대만. 올바른 ID 형식이어야 합니다 | ||
| query | status | integer | 초대 상태 숫자 (아래 표) | ||
| query | page | integer | 1 | 페이지 | |
| query | limit | integer | 20 | 페이지 크기. 상한 보정이 없으니 100 이하로 보내세요 |
초대 상태
| status | 뜻 |
|---|---|
| 1 | 대기 |
| 2 | 수락 |
| 3 | 만료 |
| 4 | 취소 |
| 5 | 거절 |
응답
200 OK
{
"list": [
{
"invitation_id": "66f0e1...",
"invitation_code": "AB12CD34",
"invitation_url": "https://.../mall/{clientKey}/invite/AB12CD34",
"target_type": 1,
"email": "new@example.com",
"phone": null,
"name": "신입",
"status": 1,
"message": "환영합니다",
"expires_at": "2026-09-30T10:00:00+09:00",
"is_expired": false,
"created_at": "2026-09-23T10:00:00+09:00",
"accepted_at": null,
"inviter": { "user_id": "66e1...", "name": "홍길동" },
"accepted_user": null,
"corporate_name": "주식회사 부트",
"department_name": "영업팀",
"inviter_name": "홍길동"
}
],
"count": 1
}json| 필드 | 타입 | 설명 |
|---|---|---|
| invitation_id | string | 초대 ID |
| invitation_code | string | 초대 코드 |
| invitation_url | string | 초대 수락 주소 |
| target_type | integer | 1 (회원 그룹 초대) |
| email / phone / name | string | 초대 대상 |
| status | integer | 초대 상태 |
| message | string | 초대 메시지 |
| expires_at | string | 만료 시각 |
| is_expired | boolean | 만료 여부 |
| created_at / accepted_at | string | 생성 / 수락 시각 |
| inviter | object | null | 초대한 회원 (user_id, name) |
| accepted_user | object | null | 수락한 회원 (user_id, name, phone, email, login_id, comment) |
| corporate_name / department_name / inviter_name | string | 기업명 / 부서명 / 초대자 이름 |
| count | integer | 전체 개수 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_GROUP_NOT_FOUND |
이 프로젝트에 없는 그룹 |
| 400 | USER_GROUP_IS_NOT_CORPORATE |
기업 그룹이 아님 |
| 400 | API_PARAM_INVALID |
department_id 가 ID 형식이 아님 (payload.field: department_id) |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 scope
user:user_group_invitation_list검사 추가,department_id형식 오류를500에서400으로
POST /v1/user-groups/:user_group_id/invitation
기업(또는 그 부서)으로 회원을 초대합니다. 초대는 7일 뒤 만료되고, 수락하면 구성원이 됩니다.
초대를 만들면 초대 메일(또는 연락처 알림)이 바로 발송됩니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_invitation_create(Bootpay-Role로 역할 부분 변경 가능) - 회원(선택):
Bootpay-User-JWT헤더 또는user_id파라미터 중 하나 — 기업 관리자 회원이 마이페이지에서 직원을 초대할 때처럼 쇼핑몰 서버가 그 회원을 지정합니다. JWT 가 우선이고, 둘이 다른 회원이면403 USER_NOT_MATCH,user_id가 이 몰 회원이 아니면404 USER_NOT_FOUND- 회원이 있으면 그 회원의 그룹 역할로 권한을 판정합니다: 기업 관리자는 어느 부서로든, 부서장은
department_id가 자기 부서일 때만 초대할 수 있습니다. 그 외는403 INVITATION_PERMISSION_DENIED. 그 회원이 초대자로 기록됩니다 - 회원이 없으면 가맹점 권한(scope)으로 처리하며 그룹 역할을 보지 않습니다. 초대자는 비어 있고(목록의
inviter: null), 초대 알림에는 '관리자'로 표시됩니다
- 회원이 있으면 그 회원의 그룹 역할로 권한을 판정합니다: 기업 관리자는 어느 부서로든, 부서장은
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | user_group_id | string | O | 기업 그룹 ID | |
| body | string | △ | 초대 대상 이메일. email·phone 중 하나 필수 |
||
| body | phone | string | △ | 초대 대상 연락처 | |
| body | name | string | 초대 대상 이름 | ||
| body | department_id | string | 초대할 부서 그룹 ID | ||
| body | message | string | 초대 메시지 |
응답
200 OK
{
"invitation_id": "66f0e1...",
"invitation_code": "AB12CD34",
"expires_at": "2026-09-30T10:00:00+09:00",
"status": 1
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_GROUP_NOT_FOUND |
이 프로젝트에 없는 그룹 |
| 400 | USER_GROUP_IS_NOT_CORPORATE |
기업 그룹이 아님 |
| 404 | DEPARTMENT_NOT_FOUND |
이 기업의 활성 부서가 아님 |
| 403 | INVITATION_PERMISSION_DENIED |
초대 권한 없음 |
| 400 | INVITATION_EMAIL_OR_PHONE_REQUIRED |
email·phone 모두 없음 |
| 400 | INVITATION_ALREADY_PENDING |
같은 대상에게 대기 중인 초대가 있음 |
| 403 | USER_NOT_MATCH (2302) |
JWT 회원과 user_id 가 다름 |
| 404 | USER_NOT_FOUND (2300) |
user_id 가 이 몰의 회원이 아님 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 항상
500이던 결함 수정. 회원(JWT 또는user_id)은 선택, 없으면 가맹점 권한(초대자 없음). 권한 검사는 컨트롤러 기준(기업 관리자·부서장,403) 하나로. scopeuser:user_group_invitation_create검사 추가
DELETE /v1/user-groups/:user_group_id/invitation/:id
대기 중인 초대를 취소합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:user_group_invitation_delete(Bootpay-Role로 역할 부분 변경 가능) - 회원(선택):
Bootpay-User-JWT헤더 또는user_id파라미터 중 하나 — 기업 관리자 회원이 마이페이지에서 직원을 초대할 때처럼 쇼핑몰 서버가 그 회원을 지정합니다. JWT 가 우선이고, 둘이 다른 회원이면403 USER_NOT_MATCH,user_id가 이 몰 회원이 아니면404 USER_NOT_FOUND- 회원이 있으면 그 회원의 그룹 역할로 권한을 판정합니다: 기업 관리자는 모든 초대, 부서장은 자기 부서 초대만 취소할 수 있습니다
- 회원이 없으면 가맹점 권한(scope)으로 처리하며 그룹 역할을 보지 않습니다
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | user_group_id | string | O | 기업 그룹 ID | |
| path | id | string | O | 초대 ID |
응답
200 OK, 본문 없음
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_GROUP_NOT_FOUND |
이 프로젝트에 없는 그룹 |
| 400 | USER_GROUP_IS_NOT_CORPORATE |
기업 그룹이 아님 |
| 404 | INVITATION_NOT_FOUND |
이 그룹의 초대가 아님 |
| 403 | INVITATION_PERMISSION_DENIED |
취소 권한 없음 |
| 400 | INVITE_MEMBER_ALREADY_USE |
대기 상태가 아닌 초대 |
| 403 | USER_NOT_MATCH (2302) |
JWT 회원과 user_id 가 다름 |
| 404 | USER_NOT_FOUND (2300) |
user_id 가 이 몰의 회원이 아님 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 항상
500이던 결함 수정. 회원(JWT 또는user_id)은 선택, 없으면 가맹점 권한. scopeuser:user_group_invitation_delete검사 추가
