회원 그룹

회원 그룹은 구매 주체 단위입니다. 개인 회원도 내부적으로 개인 그룹 하나를 갖고, 기업(사업자) 은 여러 회원이 함께 속하는 그룹입니다. 기업 아래에는 부서(또는 지점) 그룹을 둘 수 있습니다. 이 문서의 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)은 선택, 없으면 가맹점 권한. scope user: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 email 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) 하나로. scope user: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)은 선택, 없으면 가맹점 권한. scope user:user_group_invitation_delete 검사 추가

함께 보기