---
name: bootpay-commerce
description: Bootpay Commerce(api.bootapi.com) 쇼핑몰을 Next.js 같은 서버 앱에서 @bootpay/backend-js 의 BootpayCommerce 로 연동할 때 사용한다. 상품·카탈로그 조회, 장바구니 서버 견적, 회원 로그인(Commerce JWT), 주문 준비(POST /v1/orders/prepare → hosted 주문서 URL), 결제 결과 확인, generate_commerce_code, 사용자가 이미 준 Commerce client_key/secret_key 재사용, 관리자 설정의 읽기/변경 경계를 다룬다. 브라우저 PG 결제창(Bootpay.requestPayment)이나 generate_payment_code 흐름에는 쓰지 않는다.
---

# Bootpay Commerce 연동

Commerce 쇼핑몰(상품·장바구니·회원·주문)을 **서버에서** 공식 Node SDK `@bootpay/backend-js`(검증 기준 2.13.1)의
`BootpayCommerce` 로 연동하는 절차다. 결제는 가맹점이 PG 결제창을 직접 띄우지 않고, 서버가 주문을 준비한 뒤
API 가 돌려준 hosted 주문서 URL 로 이동한다.

## 언제 쓰나

- "Bootpay 커머스로 쇼핑몰 만들어줘", "Commerce API 로 상품/장바구니/주문 붙여줘", "Next.js 스토어프런트"
- `generate_commerce_code`, `commerce_*` 도구, `BootpayCommerce`, `api.bootapi.com`, `/v1/orders/prepare` 가 나오는 작업
- 사용자가 Commerce client_key/secret_key 를 이미 주고 기존 설정으로 연동하려는 경우

쓰지 않는 경우: 가맹점 화면에서 PG 결제창을 띄우는 일반 결제·빌링·본인인증은 `generate_payment_code` 흐름(MCP instructions)을 따른다.
두 흐름의 키와 인증을 섞지 않는다(아래 표).

## 설치·배포 경로

- npm 패키지 `@bootpay/mcp` 에 `skills/bootpay-commerce/` 가 함께 배포된다(package.json `files` 에 `skills` 포함 버전부터).
- Claude Code 에 설치: 패키지를 받아 이 폴더를 skills 디렉터리로 복사한다.

  ```bash
  npm pack @bootpay/mcp@latest
  tar -xzf bootpay-mcp-*.tgz package/skills/bootpay-commerce
  mkdir -p ~/.claude/skills && cp -R package/skills/bootpay-commerce ~/.claude/skills/
  ```

  프로젝트 단위로 쓰려면 `~/.claude/skills/` 대신 저장소의 `.claude/skills/` 에 복사한다.
- MCP 서버가 연결돼 있으면 같은 내용의 내장 가이드를 `get_doc` 으로도 읽을 수 있다(아래 references 표).

## 호출 구조 — 브라우저 → 쇼핑몰 서버 → Commerce (필수)

쇼핑몰의 모든 기능(회원·마이페이지·주문·취소·장바구니·구독)은 이 3단계로 만든다. 어떤 프레임워크든 같다.

```
브라우저(프론트엔드)  →  쇼핑몰 서버(Next.js Route Handler·Server Action / Nuxt server route·Nitro)  →  Bootpay Commerce v1
```

- 브라우저는 Commerce v1 을 직접 부르지 않는다. secret_key 를 쓰는 `BootpayCommerce` 호출은 쇼핑몰 서버 코드에만 둔다.
  범용 프록시(브라우저가 경로·본문을 정해 그대로 중계)를 만들지 않는다. 기능마다 서버 엔드포인트를 따로 둔다.
- secret_key(Basic) 호출은 **가맹점 권한**이다. 회원을 지정하지 않은 호출은 이 몰의 모든 회원·주문을 다룰 수 있으므로,
  구매자 화면 기능은 회원을 함께 보내 commerce 가 그 회원의 것인지 확인하게 하고, 회원을 받지 않는 API 의 소유 확인은 쇼핑몰 서버가 한다.
- 회원 지정: Bootpay-User-JWT 또는 user_id(24자리 회원 ID 또는 가맹점 외부 ID ex_uid) 또는 login_id 중 하나 — JWT 우선, 함께 보낸 값이 다른 회원이면 403 USER_NOT_MATCH(2302), user_id·login_id 는 secret_key(Basic) 서버 호출에서만 받는다. 값은 쇼핑몰 서버가 자기 로그인 세션에서 꺼내고 브라우저가 보낸 값을 그대로 쓰지 않는다.
- user_id·login_id 모드는 commerce 2026-09-28 계약이며 운영 배포 후 적용 — 그 전 운영에서는 JWT 모드만 동작하므로 기본값으로 켜지 않는다.
- 예외: users/session 은 JWT 전용(user_id 계열 400), password-recovery 는 user_id 계열 거절.

  | 모드 | 보내는 곳 | 조건 | 오류 |
  |---|---|---|---|
  | JWT | 헤더 `Bootpay-User-JWT` | 로그인 API 가 준 `token` | 무효·만료 401 `USER_JWT_INVALID`(419)/`USER_SESSION_INVALID`(420) |
  | `user_id` | GET·DELETE 는 쿼리, 그 밖은 본문 | secret_key(Basic) 서버 호출. 별칭 `user_ex_uid`·`user_external_uid`·`user_uid` | 없는·탈퇴 회원 404 `USER_NOT_FOUND`(2300), client_key 단독 400 `API_PARAM_INVALID`(-48, `reason=merchant_auth_required`) |
  | `login_id` | `user_id` 와 같음 | 로그인 아이디로 지정 | `user_id` 와 함께면 같은 회원이어야 함(아니면 403 2302) |

  셋 다 없을 때의 응답은 API 마다 다르다(장바구니·마이페이지 주문 401 `USER_SESSION_INVALID`, 구독 마이페이지 400 `REQUIRED_PARAMETER_IS_MISSING`(131)).
  모드별 상세·lenient API(견적·결제 준비·리뷰·구독 쿠폰 미리보기)·자동 로그인 URL 조건은 [contracts.md §3](references/contracts.md).
- 구매자 취소(`order/cancel`·취소 철회, `order/subscription/cancel`)는 **회원(JWT 또는 `user_id`)을 함께 보낸다.** commerce 가 그 회원 주문인지 확인하고(다른 회원·비회원 주문 404)
  구매자 규칙을 적용한다 — `cancel_immediately`·`force`·`cancel_requester`·`reason_key` 는 무시되고, 즉시 취소 여부는 서버가 정한다(배송 준비 전 유예 구간이면 즉시, 그 밖에는 승인 대기).
  회원 없이 부르면 가맹점 취소이므로 구매자 화면에 연결하지 않는다. commerce 운영 배포 전에는 이 확인이 없으므로 서버가 먼저 `GET orders/{order_number}`(회원 JWT)로 본인 주문인지 확인한다(배포 후에는 선택).
- 구매자 화면 기능을 운영 API 로 대신하지 않는다. 쿠폰 발급·포인트 지급·구독 관리 같은 가맹점 운영 자동화는 [merchant-operations.md](references/merchant-operations.md)를 따른다 — 운영 API 의 `user_id` 는 호출한 회원이 아니라 대상 회원이다.
- 생성 코드·리뷰·완료 검증에서 이 구조를 확인한다: 브라우저 번들에 Commerce 호출·secret_key 가 없고, 회원 값이 요청 본문이 아니라 서버 세션에서 온다.

## 시작 순서 — 증거 확인 → 읽기 → 계약 검증 → 구현

1. **이미 주어진 것부터 확인한다**
   - 자격증명: 사용자가 Commerce client_key/secret_key 를 줬는가? 줬다면 그 키를 쓴다. 관리자 로그인(`browser_login`),
     프로젝트 선택·생성, 키 발급(`create_commerce_keys`), 결제수단/샌드박스/쇼핑몰명 변경을 요구하지 않는다.
     이미 받은 권한을 다시 확인하는 절차를 만들지 않는다.
   - mode: 사용자가 준 키의 환경(기본 `production`). 운영/테스트 모드를 대신 바꾸지 않는다.
   - 프로젝트 증거: 앱 서버에서 그 키로 `GET /v1/store` 를 호출해 상점 이름을 확인한다. 관리자 세션의 프로젝트와 같다고 가정하지 않는다.
2. **필요한 설정만 읽는다**
   - 키가 주어진 경우: `generate_commerce_code(framework, credential_source="provided", client_key="<client_key>")`.
     secret_key 는 도구 인자로 넘기지 않는다 — 앱 서버 환경변수 `BOOTPAY_SECRET_KEY` 에만 둔다.
   - 키가 없는 경우: `browser_login` → `browser_select_project` → `generate_commerce_code(framework)`.
     기본 `auto_setup=false` 는 관리자 설정을 GET 으로만 읽고 쓰기 요청을 보내지 않는다(`preflight.performed_writes: 0`).
3. **프론트 규칙과 v1 계약을 확인한다** — [storefront-development.md](references/storefront-development.md)의 현재 invoice HTML/CSS 규칙과 공개 API 경계를 먼저 읽는다.
   기존 프레임워크를 유지하고 invoice 내부 `mall/*`·인증·숫자 enum을 복사하지 않는다. [contracts.md](references/contracts.md)의 raw 응답·Basic 인증·JWT·견적 토큰 계약과 대조한다.
   어긋나면 코드로 덮지 말고 gap task 로 남긴다(contracts.md 마지막 절).
4. **필수 14개 기능을 순서대로 구현한다** — [required-features.md](references/required-features.md)를 먼저 읽는다. 회원가입·로그인·마이페이지·본인 주문·배송지·회원정보 수정·비밀번호 변경/찾기·탈퇴가 모두 기본 기능이고 2026-09-21 기준 공개 v1 계약이 있다. 선택 기능으로 빼서 완료 처리하지 않는다. 계정 API가 404/403(-47)이면 기능 부재가 아니라 대상 환경의 배포·api_scopes 동기화 문제다. 생성 코드와 references의 계약을 따른다. 필수 쇼핑 흐름은 [storefront-baseline.md](references/storefront-baseline.md).
   신규 결제는 `cart/order-preview`의 `checkout_ready/quote_token` → 동일 구매자·기기로 prepare → 구매자 `orders/{id}/result` 순서다.
   **배송지 정책** — 결제 요청(`orders/prepare`)에 배송지·우편번호는 필요 없다. 배송지와 제주·도서산간 추가비는 호스팅 주문서가 입력받아 확정한다(결제 전 배송지 반영 시 배송비·총액 재계산). 쇼핑몰(장바구니·바로 구매·결제 버튼)은 주소를 묻거나 확인하거나 배송지 등록을 요구하지 않고, 배송지 때문에 결제 요청을 막지 않는다. `cart/order-preview` 는 추가비 정책 상점에서 우편번호가 없으면 `requires_address`(토큰 없음)를 주므로, 서버가 지역 추가비가 붙지 않는 고정 내륙 우편번호로 견적한다(생성 코드 `BASE_QUOTE_ZIPCODE`) — 우편번호 없이 만든 주문과 같고 주문서에서 다시 계산된다.
   Next.js 외 생성기는 현재 실행 코드 대신 구현 가이드를 반환한다. 선택한 프레임워크에서 명시적인 BFF를 구현하며 브라우저 JWT·범용 프록시가 있던 과거 샘플을 복사하지 않는다.
   장바구니 결제는 서버가 `paid === true` 를 확인한 뒤 이번 주문 줄만 장바구니에서 뺀다(전체 비우기·바로 구매의 장바구니 변경 금지).
   회원 서버 장바구니는 견적에 `cart_item_id` 를 보내면 결제 완료 시 commerce-api 가 그 줄을 정리하므로 클라이언트는 `DELETE` 없이 `GET /v1/cart` 로 다시 읽는다.

## 생성된 Next.js 앱을 로컬에서 실행할 때

- 개발 모드(`next dev`)는 `APP_ORIGIN` 과 포트·주소가 달라도(예: `next dev -p 3300`, LAN IP 접속) 요청 Host 와 같은 Origin 을 허용하고,
  서버 콘솔에 `app_origin_mismatch` 경고로 기대값·실제값과 `.env.local` 의 `APP_ORIGIN` 을 고치라는 안내를 한 번 남긴다. 운영(`next start`)은 `APP_ORIGIN` 과 같은 Origin 의
  상태 변경 요청만 받고 나머지는 403 `INVALID_ORIGIN` 이다. 로그인이 막힌다고 운영 Origin 검사를 지우지 않는다.
- 회원 모드 `generate_commerce_code(member_mode)`: `bootpay_jwt`(기본·권장)는 로그인 JWT 를 서버 세션에 두고 `Bootpay-User-JWT` 로 보낸다.
  `own_login` 은 `users/login` 응답의 `user_id` 만 서버 세션에 봉인하고(JWT 는 버림) 모든 회원 요청에 그 `user_id` 를 넣는다(GET/DELETE 쿼리, 그 밖은 본문). `Bootpay-User-JWT` 는 보내지 않고 브라우저에는 원문 id 대신 해시를 내린다.
  secret_key 가 새면 임의 회원으로 행동할 수 있고 commerce 운영 배포 전에는 운영에서 동작하지 않을 수 있어(운영 배포 후 적용) 기본값이 아니며, 사용자가 자체 로그인 세션을 명시했을 때만 쓴다.
  `own_login` 에는 `/b` 자동 로그인(`use_auto_login=false`)·`users/session` 이 없다. 본인 프로필(`users/me`)은 서버 세션의 `user_id` 로 조회(GET 쿼리)·수정(PATCH 본문)하므로 `[required:profile-update]` 가 남지 않는다. 비밀번호 변경·탈퇴(`user_id`)·비밀번호 찾기(`login_id`)도 유지된다.
  오류 매핑: 2302 → 다시 로그인, 2300 → 세션에서 회원을 지운 뒤 로그인, 420 → 로그인 필요. 상세: [storefront-development.md](references/storefront-development.md).
- 결제 준비(`orders/prepare`)의 복귀 주소는 쇼핑몰에 등록된 https 도메인이어야 한다(18162). `APP_ORIGIN` 이 http(로컬)이면 생성 앱은 prepare 를 부르지 않고
  503 `CHECKOUT_RETURN_URL_NOT_REGISTERED`(재시도 불가)를 낸다 — "잠시 후 다시 시도"로 안내하지 않는다. 로컬에서 결제까지 검증하는 절차(https 터널 + 도메인 등록)는
  [storefront-development.md §3](references/storefront-development.md), 등록은 사용자 요청 시 `register_checkout_return_domain`.

## 읽기와 변경의 경계

| 도구 | 성격 | 규칙 |
|---|---|---|
| `generate_commerce_code` (`auto_setup=false`, 기본) | 읽기 | 차이는 `configuration_changes` 제안으로만 돌려준다. `app_origin`(https 배포·터널 주소)을 넘기면 결제 복귀 도메인 등록 여부를 점검한다 |
| `generate_commerce_code` (`auto_setup=true`) | 쓰기 | 사용자가 설정 변경을 명시 요청했을 때만. 누락된 커머스 키·결제 위젯과 사용자가 지정한 pg/method/sandbox/mall_name 만 적용하고 `applied_changes`·`apply_target` 을 보여 준다. `app_origin` 을 넘기면 결제 복귀 도메인을 등록한 뒤 `.env.example` 의 `APP_ORIGIN` 을 채운다 |
| `get_commerce_context`, `get_commerce_keys` | 읽기 | 키가 없어도 만들지 않는다. secret_key 는 마스킹 |
| `create_commerce_keys` | 쓰기 | 사용자가 새 키 발급을 요청했을 때만. 기존 키가 있으면 `allow_additional=true` 없이는 발급하지 않는다 |
| `browser_select_payment_method` | 쓰기 | 사용자가 결제수단·쇼핑몰명을 새로 고르기로 동의했을 때만 |
| `commerce_prepare_order` | 쓰기 | 실제 주문을 만든다. 같은 구매 시도에는 같은 `idempotency_key`(`Idempotency-Key` 헤더로만 전송). 응답을 못 받으면 `order_created: "unknown"` — 새 키로 다시 만들지 않는다. `user_id` 만 있고 `use_auto_login=true` 면 `USER_JWT_REQUIRED`(호스팅 주문서 로그인 인계는 JWT 필요) |
| `commerce_get_order_status` | 읽기 | 재사용·만료 판단의 기준(`GET /v1/orders/{order_number}`). `checkout_state` 가 `expired` 면 다음 사용자 클릭에서만 새 시도, `reusable` 이면 같은 url 재사용, `settled` 면 결과 확인, `unconfirmed` 면 대기. 회원 확인은 하지 않는다 |
| `commerce_get_order_result` | 읽기 | 회원(JWT 또는 `user_id` — 운영 배포 후) 또는 비회원 `result_token`+`device_uuid`로 구매자 결과를 조회한다. 회원(`user_jwt`·`user_id`·`login_id`)을 주면 commerce 가 소유를 확인하고 타인 주문은 `ORDER_NOT_OWNED` 다 — 서버가 `GET orders` 로 먼저 본인 확인할 필요는 없다. 구독 주문 결과(`commerce_get_order_subscription_result`)는 회원 지정이 필요하다. 구매자 자격 없는 기존 가맹점 조회와 구분한다 |
| `list_checkout_return_domains(url)` | 읽기 | 결제 복귀 도메인(18162) 확인. 결제 후 돌아올 수 있는 https 호스트를 출처별로 보여 주고, url 을 주면 허용 여부를 판정한다 |
| `register_checkout_return_domain`, `unregister_checkout_return_domain` | 쓰기 | 사용자가 등록·해제를 요청했을 때만. `confirm` 없이 먼저 불러 before/after·영향(CORS·소셜 로그인 허용 목록 공유)을 보여 주고, 동의를 받으면 `confirm=true`로 다시 부른다. 기존 도메인은 보존한다. http·localhost·IP 는 등록되지 않으니 https 터널 주소를 쓴다 |
| `commerce_preview_guest_order` | 읽기 | 회원/기기·우편번호를 전달해 서버 견적을 받는다. 견적과 prepare 는 같은 회원(또는 같은 `device_uuid`)으로 부른다. 회원 장바구니 결제는 `cart_item_id` 를 보내면 결제 완료 시 commerce 가 그 줄을 정리한다. `checkout_ready`일 때만 `quote_token`으로 주문 준비, `amounts:null`이면 진행 불가 |
| `commerce_calculate_price` | 읽기 | `estimatedTotal`(`kind: "local_estimate"`)은 화면 참고용 추정치. 신규 주문은 `order-preview`의 `amounts`와 `quote_token`을 사용 |

- `commerce_prepare_order`·`commerce_get_order_status`·`commerce_get_order_result`·`commerce_calculate_price` 는 Commerce Remote MCP 도구다. stdio Commerce 도구(13개)에는 없다.
- 공지사항·FAQ·1:1 문의·상품문의·상품평 도구(`commerce_*_notice(s)`·`*_faq(s)`·`*_inquiry`·`*_product_qna(s)`·`*_product_review`·`commerce_list_my_reviews`·`commerce_get_review`)도 Remote 전용이며 공개 `/v1/*` 만 호출한다.
  읽기는 기본 고객 조회, `as_operator=true` 일 때만 `Bootpay-Role: supervisor` 운영자 조회다. 작성·수정·삭제·답변은 사용자가 요청했을 때만 부르고, 구매자 화면 기능을 운영자 모드로 대신하지 않는다.
  생성 앱의 [필수 기능 14개](references/required-features.md)에는 포함하지 않는다 — 요청받았을 때 `generate_commerce_code(features=[…])`(nextjs)로 선택 기능을 얹는다.
  (`reviews`·`product-qna`·`notices`·`faq`·`inquiries`·`wishlist`·`benefits`, 판정: [storefront-baseline.md 선택 기능](references/storefront-baseline.md))
- `sandbox` 를 생략하면 운영/테스트 모드는 그대로다. 사용자가 명시한 값이 현재와 다를 때만 바뀐다.
- 관리자 API 가 401 이면 현재 프로젝트에서 멈추고 다른 프로젝트로 전환하지 않는다. 403 은 권한 부족으로 보고하고 재로그인·설정 변경을 자동 실행하지 않는다.
- 도구 annotation(`readOnlyHint` 등)은 클라이언트용 힌트다. 권한 검사를 대신하지 않는다.

## 일반 PG 결제와 Commerce 인증을 섞지 않는다

| 구분 | 일반 PG 결제 | Commerce |
|---|---|---|
| MCP 도구 | `generate_payment_code` | `generate_commerce_code`, `commerce_*` |
| 키 | 결제용 키체인(`list_keychains(source="core")`) | 커머스용 키체인(`get_commerce_keys`, 관리자 → API 연동키 → 커머스) |
| 결제 시작 | 브라우저에서 PG 결제창 호출 후 서버 승인 | 서버가 `POST /v1/orders/prepare` → 응답 `url` 로 이동(hosted 주문서) |
| 서버 인증 | 결제 API 규칙(`get_doc` 결제 문서) | `BootpayCommerce` 가 모든 요청에 `Authorization: Basic base64(client_key:secret_key)` |
| 회원 식별 | 해당 없음 | Commerce 로그인으로 받은 JWT 를 `Bootpay-User-JWT` 헤더로, 또는 서버 세션의 `user_id`·`login_id`(운영 배포 후) — 위 호출 구조의 회원 지정 규칙 |

- Commerce 에서 `getAccessToken()`/`withToken()` 으로 토큰을 발급받는 코드를 만들지 않는다. Basic 인증으로 충분하다.
- 결제 위젯 `user_token` 과 Commerce 회원 JWT 는 다른 값이다.

## 비밀값

- secret_key·회원 JWT·비회원 `result_token`은 서버에 보관한다. 브라우저 번들(`NEXT_PUBLIC_*`), localStorage, 로그, 문서 예시에 넣지 않는다. hosted URL의 `__s`는 브라우저 이동에 필요한 bearer이며 URL 원문을 로그·저장소·문서에 남기지 않는다.
- 예시는 항상 `<client_key>`, `<secret_key>` 같은 자리표시자를 쓴다.
- 새로 발급한 키의 secret_key 는 발급 응답에서 1회만 보인다. 사용자에게 서버 환경변수에 저장하도록 안내하고 대화에 다시 적지 않는다.

## references

| 문서 | 내용 | MCP 내장 가이드 |
|---|---|---|
| [required-features.md](references/required-features.md) | 회원가입·로그인·마이페이지 포함 필수 기능·API gap·완료 기준 | `get_doc("commerce/required-features")` |
| [storefront-development.md](references/storefront-development.md) | 현재 invoice 프론트 규칙, 내부/public 경계, v1 견적·구매자 결과·지원 범위 | `get_doc("commerce/storefront-development")` |
| [contracts.md](references/contracts.md) | SDK 2.13.1 raw 응답, Basic 인증, 회원 지정(JWT·`user_id`·`login_id`)·오류 코드, endpoint·옵션·금액, hosted 결제, pending 결과, gap task 절차 | — |
| [merchant-operations.md](references/merchant-operations.md) | 가맹점 운영 API(쿠폰·포인트·구독 관리·SDK·청구서·회원 그룹·관리자 리뷰) 인증·scope·대상 회원 경계 | `get_doc("commerce/merchant-operations")` |
| [product-block-rendering.md](references/product-block-rendering.md) | 상품 상세 블록 본문·중간 이미지·공유 CSS 렌더 | `get_doc("product/block-rendering")` |
| [hosted-checkout-session.md](references/hosted-checkout-session.md) | hosted 주문서 세션(`/b` 브리지)·만료 주문 재시도 | `get_doc("commerce/hosted-checkout-session")` |
| [storefront-baseline.md](references/storefront-baseline.md) | 기본 쇼핑몰 필수 UX·바로 구매·완료 검증 | `get_doc("commerce/storefront-baseline")` |
