마켓플레이스

그룹 생성

같은 기업에 속한 회원을 하나로 묶는 단위예요.

기업 고객 그룹을 생성해요. 동일 기업 소속 사용자를 하나의 그룹으로 통합 관리할 수 있어요.

API 엔드포인트

POSThttps://api.bootapi.com/v1/user-groupsBasic Auth

필요 scope: user:user_group_create. Bootpay-Role 헤더로 역할 부분을 바꿀 수 있어요. v1 회원 그룹 API 상세 명세에서 인증과 응답 필드를 확인해요.

그룹 유형 (corporate_type)

키 값 설명
individual 1 개인 그룹 — 회원 가입 시 자동 생성되는 개인 전용 그룹
business 2 기업 그룹 — 동일 기업 소속 사용자를 통합 관리, 기업 구독·결제 일괄 처리
department 3 부서 그룹 — 기업 내 부서 단위

요청 파라미터

파라미터 타입 필수 설명
company_name String 선택 회사명 (서버가 필수 검사를 하지 않으므로 보내는 것을 권장해요)
business_number String 필수 사업자등록번호. 하이픈 없이 저장되며 프로젝트 안에서 중복될 수 없어요
manager_phone String 선택 담당자 연락처
manager_email String 선택 담당자 이메일
registration_number String 선택 법인등록번호
business_type String 선택 업종
corporate_established String 선택 설립일
manager_name String 선택 담당자명
phone String 선택 전화번호
email String 선택 이메일
zipcode String 선택 우편번호
address String 선택 주소
address_detail String 선택 상세주소
uid String 선택 가맹점 고유값. ex_uid·external_uid 로도 보낼 수 있고 프로젝트 안에서 중복될 수 없어요
bank / bank_code String 선택 계좌번호 / 은행 코드
auth_bank Boolean 선택 계좌 인증 여부
pccc String 선택 개인통관고유부호
use_subscription_aggregate_transaction Boolean 선택 합산 결제 사용 여부 (기본 false)
subscription_month_day / subscription_week_day Integer 선택 월·주 합산 결제일 (기본 1)
limit_month_purchase / limit_week_purchase Number 선택 월·주 구매 한도 (기본 0)
limit_message String 선택 한도 초과 시 안내 문구

생성 요청은 use_limit 를 받지 않아요. 구매 한도를 켜려면 생성 후 구매 한도 설정을 호출해요.

코드 예제

const { BootpayCommerce } = require('@bootpay/backend-js')

const commerce = new BootpayCommerce({
    client_key: 'your-commerce-client-key',
    secret_key: 'your-commerce-secret-key',
    mode: 'production'
})

const response = await commerce.userGroup.create({
    company_name: '(주)부트페이',
    business_number: '1234567890',
    manager_name: '김철수',
    phone: '0212345678',
    email: 'company@example.com'
})
console.log('user_group_id:', response.user_group_id)javascript

응답

성공 응답

{
  "user_group_id": "67e2052b03d0cb4e4117b0af",
  "corporate_type": 2,
  "phone": "0212345678",
  "email": "company@example.com",
  "company_name": "(주)부트페이",
  "business_number": "1234567890",
  "manager_name": "김철수",
  "sub_group_type": 1,
  "sub_group_type_label": "부서",
  "sub_group_manager_label": "부서장",
  "use_sub_group": false,
  "use_limit": false,
  "limit_month_purchase": 0.0,
  "limit_week_purchase": 0.0,
  "subscribed_month_limit": 0.0,
  "subscribed_week_limit": 0.0
}json

응답에 status 는 없어요. 주소(zip·addr1·addr2), registration_number·business_type·business_category, 통합 결제 설정(use_subscription_aggregate_transaction·subscription_month_day·subscription_week_day), limit_message 도 함께 와요.

에러 응답

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error_code": "USER_GROUP_BUSINESS_NUMBER_ALREADY_EXISTS",
  "message": "중복된 사업자번호를 가진 그룹이 이미 존재합니다."
}json

그룹 상태 (status)

키 값 설명
active 1 활성
inactive 0 비활성
deleted -1 삭제됨
이 응답의 유형 값은 숫자예요

그룹 생성 응답의 corporate_type 은 2(기업)처럼 숫자로 내려와요. 그룹 목록 응답에서는 문자열(enum)이에요. 전체 목록은 커머스 Enum에서 확인해요.

에러 코드

공통 에러

인증·권한 관련 에러는 에러 코드표를 참고해요.

코드 메시지 대처 방법
USER_GROUP_EXTERNAL_UID_EXIST 중복된 사업자 UNIQ ID예요. 다른 ex_uid를 사용해요
USER_GROUP_BUSINESS_NUMBER_ALREADY_EXISTS 중복된 사업자번호를 가진 그룹이 이미 있어요. 기존 그룹을 확인해요
USER_BUSINESS_NUMBER_BLANK 기업회원은 사업자 등록번호를 입력해야 해요. business_number를 입력해요

user_group_id를 고객 등록 시 user_group_id 파라미터에 전달하면 해당 고객을 기업 그룹에 소속시킬 수 있어요.