핵심 요약
먼저 정할 것은 email · phone · 외부 회원번호(external_uid) 중 무엇을 기준 키로 쓸지예요. 여기가 정해지면 중복 체크와 SSO 흐름이 따라서 단순해져요. 같은 이메일이나 전화번호로 중복 가입이 자주 생긴다면 check-exist 를 가입 앞단에 넣고, 자체 로그인 시스템이 이미 있어 checkout 에서 부트페이 고객 세션만 이어 붙이면 되는 경우라면 login-token 이 핵심이에요.
이 문서가 회원관리 전체를 대체하지는 않아요. 구매자 식별을 commerce 에 연결하는 기준만 다뤄요. 대신 그 기준을 안정적으로 잡아 두면 일반 쇼핑몰, 구독, B2B 마켓플레이스가 모두 같은 기반 위에서 움직여요.
이 기능이 왜 필요한지·무엇을 먼저 정할지는 블로그에서 다뤄요.
- 결제만 붙이면 되나요, 주문까지 해야 하나요? — 고객 식별을 commerce에 맡길지 결정하는 판단 틀
- 주문 취소 정책 설계 — 고객 응대 기준과 함께 보는 취소 정책
- 플랫폼 수수료 설계 — 그룹·거래처별 정산이 있을 때
1고객 모델
customer 모델은 결제만을 위한 임시 입력값이 아니라, 주문과 구독을 묶는 구매자 식별 단위예요.
기본 필드는 다음과 같아요.
| 필드 | 역할 | 비고 |
|---|---|---|
email |
대표 식별자 | 로그인 ID 또는 알림 채널로 활용 |
phone |
보조 식별자 | 본인 확인, 알림, 중복 체크 |
external_uid · individual_extension |
서비스별 확장 필드 | external_uid 는 외부 회원번호, individual_extension 은 사번·회원등급 같은 자유 형식 객체 |
핵심은 어떤 값을 canonical 키로 쓸지 정하는 것이에요.
- 이메일을 기준으로 묶을 것인가
- 전화번호를 1차 식별자로 둘 것인가
- 외부 회원번호를
external_uid로 넣을 것인가
이 기준이 모호하면 중복 고객이 쉽게 생기고, 주문 이력과 구독 이력이 갈라져요.
관련 문서:
2중복 체크
check-exist는 고객을 실제 생성하기 전에 특정 키가 이미 존재하는지 확인하는 단계예요. 이 문서는 가입 성공 API가 아니라 방어용 API라고 이해하면 돼요.
중복 체크가 필요한 대표 상황은 다음과 같아요.
- 자체 회원가입 폼에서 이메일 중복을 바로 막아야 할 때
- 전화번호가 이미 Bootpay customer에 등록되어 있는지 확인해야 할 때
- 외부 회원번호나 사업자번호를 유일 키로 관리할 때
흐름은 단순해요.
- 프론트 또는 서버에서 가입 전 값을 받아요.
check-exist로 동일 키 존재 여부를 조회해요.- 없으면 등록을 진행하고, 있으면 기존 계정 연결이나 로그인 흐름으로 보내요.
관련 문서:
중복 체크는 고객 경험보다 데이터 정합성을 위한 단계예요. 특히 구독 서비스에서는 중복 고객이 곧 중복 과금 리스크로 이어질 수 있어요.
3로그인 토큰으로 SSO
login-token은 이미 가맹점이 알고 있는 고객을 Bootpay checkout 세션에 연결할 때 써요. 자체 로그인과 Bootpay customer를 이어 주는 얇은 다리라고 보면 돼요.
이 기능이 필요한 장면은 다음과 같아요.
- 가맹점 서비스에 로그인된 사용자가 checkout으로 넘어갈 때
- checkout 화면에서 고객 정보를 다시 입력받고 싶지 않을 때
- 고객별 가격, 그룹 정책, 구독 상태를 바로 반영하고 싶을 때
SSO 관점에서 보면 흐름은 아래와 같아요.
- 가맹점 서버가 현재 로그인 사용자를 확인해요.
- 해당 사용자를 Bootpay customer와 매핑해요.
login-token을 발급해 checkout 요청에 연결해요.- checkout은 그 고객 컨텍스트를 기준으로 동작해요.
관련 문서:
SSO를 붙이면 단순 편의성만 좋아지는 것이 아니에요. 주문 조회, 그룹 정책, 구독 승인 화면이 같은 고객 기준으로 묶여요.
4쇼핑몰 회원 흐름
여기까지가 가맹점 서버가 고객 원장을 다루는 이야기라면, 아래는 구매자가 직접 쓰는 회원 기능이에요. 외부 쇼핑몰(BFF)이 화면을 만들 때 쓰는 공개 계약이며, 모두 서버 Basic 인증 위에서 동작해요.
| 화면 | API | 고객 JWT |
|---|---|---|
| 가입 | 쇼핑몰 회원가입 — 정책 조회 → 가입 → 이메일 인증 | 불필요 |
| 로그인 | 로그인·세션 | 로그인 후 발급 |
| 마이페이지 | 본인 프로필 | 필요 |
| 비밀번호 변경 | 비밀번호 | 필요 |
| 비밀번호 찾기 | 비밀번호 | 불필요 |
| 배송지 | 배송주소·쿠폰 | 본인 고정 |
| 탈퇴 | 회원 탈퇴 | 필요 |
두 가지를 구분해서 기억하면 돼요.
- 관리자 계약(
/v1/users/:user_id,user:user_detail·user:user_update·user:user_delete)은 상점의 아무 고객이나 읽고 고칠 수 있어요. 가맹점 서버 내부에서만 쓰세요. - 프로필·비밀번호·탈퇴 계약(
/v1/users/me/*)은 본인 전용 scope를 요구해요. JWT를 보내면 그 회원으로 대상을 고정하고, 가맹점 서버는 JWT 없이user_id로 이 몰의 회원을 지정할 수도 있어요. 이때 본인 확인은 쇼핑몰 서버의 책임이에요.
쇼핑몰 BFF에 관리자 권한 키를 주면 "본인만"이라는 제약이 가맹점 코드에만 남아요. 권한 키를 나눠서 발급하세요.
비밀번호 변경·재설정·탈퇴가 성공하면 그 회원의 기존 고객 JWT가 전부 무효가 돼요. 응답의 requires_login: true를 받으면 세션 쿠키를 지우고 로그인으로 보내요.
5다음 단계
고객 구조를 정했다면 아래 순서로 문서를 읽으면 돼요.
- 쇼핑몰을 직접 만든다면 쇼핑몰 회원가입 → 로그인·세션 → 본인 프로필 순서로 읽어요.
- 기존 회원을 이관한다면 중복 확인 → 고객 등록 → 고객 수정로 고객 원장을 만들어요.
- 자체 로그인이 이미 있다면 로그인 토큰으로 checkout 연결을 완성해요.
- 조직 단위 관리가 필요하면 B2B 마켓플레이스 이해하기로 넘어가요.
customer를 먼저 정리해 두면 checkout과 subscription에서 고객 식별을 다시 설계할 일이 줄어들어요.
