# Commerce 서버 연동 계약 — @bootpay/backend-js 2.13.1

이 문서의 근거는 `@bootpay/backend-js` 2.13.1 배포본 소스(`dist/lib/commerce-resource.js`, `dist/lib/commerce/modules/*`)와
2026-09-17 확인한 commerce-api v1의 controller/service와 격리 테스트다(§3 회원 지정은 commerce `docs/api/v1` 2026-09-28 계약). 운영 API 를 호출해 새로 확인한 값이 아니므로,
배포 상태와 다르면 마지막 절의 절차로 gap 을 남긴다. 키·JWT·주문번호는 모두 자리표시자다.

## 1. 클라이언트와 서버 인증

- 생성: `new BootpayCommerce({ client_key, secret_key, mode })`. `mode` 미지정이면 `production`.

  | mode | base URL |
  |---|---|
  | `production` | `https://api.bootapi.com/v1` |
  | `stage` | `https://stage-api.bootapi.com/v1` |
  | `development` | `https://dev-api.bootapi.com/v1` |

- SDK 요청 인터셉터가 **모든 요청**에 붙이는 헤더: `Authorization: Basic base64(client_key:secret_key)`,
  `BOOTPAY-SDK-TYPE: 301`, `BOOTPAY-SDK-VERSION`, `BOOTPAY-API-VERSION`, `BOOTPAY-ROLE`(기본 `user`),
  `Content-Type: application/json`(요청이 직접 지정하지 않았을 때).
- `getAccessToken()` / `withToken()` 으로 토큰을 받아 쓰는 코드를 만들지 않는다. Basic 인증으로 충분하다.
- 서버 전용: 모듈 첫 줄에 `import 'server-only'`. 환경변수는 `BOOTPAY_CLIENT_KEY`, `BOOTPAY_SECRET_KEY`, `BOOTPAY_MODE`.
  `NEXT_PUBLIC_` 접두사로 비밀값을 내보내지 않는다.
- 참고 구현은 `$http.defaults.timeout = 12000`, `$http.defaults.maxRedirects = 0` 으로 둔다(리다이렉트로 Authorization 이 다른 호스트에 가지 않게).

## 2. 응답은 upstream JSON 그대로 — envelope 를 가정하지 않는다

- 응답 인터셉터가 `response.data` 를 그대로 돌려준다. TypeScript 타입 `BootpayCommerceResponse<T>`(`{ success, data }`)와 **런타임 모양이 다르다.**
  상품 목록은 `{ list, count }` 가 바로 온다.
- 실패 시 HTTP 응답이 있으면 upstream 본문(`{ error_code, message }` 등)으로 reject, 응답이 없으면
  `{ error: 'Request Rest Api Failed to Bootpay Commerce Server, …' }` 로 reject 한다.
- 해석 규칙(`sdkBody`): `success === false` 이거나 숫자/문자열 `error_code`가 있으면 실패, `success === true` 이고 `data` 키가 있으면 `data`, 그 밖에는 원문.
- 로그에는 알려진 `error_code`만 남긴다. API는 숫자 대신 `ORDER_QUOTE_TOKEN_EXPIRED` 같은 이름을 직렬화할 수 있으므로 숫자·이름을 함께 해석한다. Axios config·headers·본문에는 Authorization·회원 JWT 가 들어 있으므로 기록하지 않는다.

## 3. 회원 지정 — `Bootpay-User-JWT` 또는 `user_id`·`login_id`

이 절이 회원 식별 규칙의 정본이다. SKILL.md·AGENTS.md·`get_doc` 가이드·MCP instructions 는 아래 세 문장을 그대로 인용한다.

- 회원 지정: 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). lenient API 는 아래 참고 |
| `user_id` | GET·DELETE 는 쿼리, 그 밖은 본문 | secret_key(Basic·Bearer) 인증에서만. 24자리면 Bootpay 회원 ID, 그 밖의 값은 이 몰의 외부 회원 ID(`ex_uid`). 별칭 `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` 와 함께면 같은 회원이어야 함 |
| 공통 | — | JWT 우선 | 다른 회원 403 `USER_NOT_MATCH`(2302). 셋 다 없음은 API 별(401 `USER_SESSION_INVALID`(420) 또는 400 `REQUIRED_PARAMETER_IS_MISSING`(131)) |

오류 코드 요약:

| HTTP | error_code | 숫자 | 언제 | 쇼핑몰 화면 처리 |
|---|---|---|---|---|
| 401 | `USER_SESSION_INVALID` | 420 | JWT 없음·로그아웃·만료·탈퇴 세션, 회원이 필수인 API 에 회원 없음 | 로그인 복귀 |
| 401 | `USER_JWT_INVALID` | 419 | 서명 불일치·변조·만료 JWT | 로그인 복귀 |
| 403 | `USER_NOT_MATCH` | 2302 | JWT 와 `user_id`/`login_id` 가 서로 다른 회원 | 서버 세션 결함 — 세션을 끊고 다시 로그인 |
| 404 | `USER_NOT_FOUND` | 2300 | `user_id`/`login_id` 가 이 몰 회원이 아니거나 탈퇴 | 로그인 만료로 처리(세션 정리) |
| 400 | `REQUIRED_PARAMETER_IS_MISSING` | 131 | 회원이 필수인데 셋 다 없음(구독 마이페이지 등) | 로그인 복귀 |
| 400 | `API_PARAM_INVALID` | -48 | client_key 만으로 부르면서 `user_id` 를 넣음(`reason=merchant_auth_required`) | 설정 결함 — secret_key(Basic) 서버 호출로 옮긴다 |

- **lenient API**(견적 `cart/order-preview`·결제 준비 `orders/prepare`·리뷰·구독 쿠폰 미리보기): 회원이 선택이다. JWT 가 무효면 비회원으로 처리하되, 무효 JWT 와 함께 `user_id` 를 보냈으면 그 회원으로 처리한다.
- **자동 로그인 URL**(`orders/prepare` 의 `use_auto_login:true` + `response_type:"url"`)은 유효한 회원 JWT 가 있어야 만든다. `user_id` 로만 지정하면 401 `USER_SESSION_INVALID` 다 — `user_id` 모드 주문은 `use_auto_login:false` 로 보낸다.
- **로그인 응답**: `POST users/login` 은 `{ token, user_id }` 를 준다(운영 배포 후). 자체 로그인 몰은 `user_id` 를 서버 세션에 보관해 JWT 없이 회원 API 를 부를 수 있다.
  비밀번호 변경·탈퇴 성공 시 그 회원의 모든 JWT 가 무효가 되므로 `user_id` 모드 쇼핑몰도 자기 세션을 끊는다.
- 로그인·가입 본문의 `login_id` 는 자격증명이지 회원 지정이 아니다.
- 운영 API(쿠폰 발급·포인트 지급·목록 필터)의 `user_id` 는 호출한 회원이 아니라 **대상 회원**이며 세션을 바꾸지 않는다 — [merchant-operations.md](merchant-operations.md).
- users/me(GET/PATCH)는 2026-09-28 부터 JWT 전용이 아니다(MI-27) — 다른 회원 본인 API 와 같은 규칙이고, PATCH 의 `user_id`·`login_id` 는 거절 키가 아니라 회원 지정이다.

### JWT 모드 — SDK 호출

- 로그인: `user.userLogin({ login_id, password })` → `{ token }`(운영 배포 후 `user_id` 포함). token 은 서버 세션(HttpOnly·암호화 쿠키)에만 둔다.
- 세션 확인: `user.userSession(jwt)` → `{ user_id, name, … }`, 로그아웃: `user.userLogout(jwt)`.
- SDK 모듈 메서드는 `Idempotency-Key`(미지정이면 호출마다 새 UUID)와, 값이 있을 때만 `Bootpay-User-JWT` 를 붙인다.
- `post()`/`get()` 을 직접 쓰는 경로(`orders/prepare`, `cart/order-preview`, `orders/{id}/result`)는 헤더를 직접 넘긴다.

```json
{
  "headers": {
    "Authorization": "Basic <base64(client_key:secret_key)>",
    "Bootpay-User-JWT": "<customer_jwt — 회원 요청일 때만>",
    "Idempotency-Key": "<같은 사용자 요청에서 파생한 안정 키>"
  }
}
```

- 결제 위젯 `user_token` 과 다른 값이다. JWT 를 URL·쿼리·localStorage 에 넣지 않는다.
- `user_id` 모드(운영 배포 후)는 헤더 대신 쿼리(GET·DELETE)나 본문(그 밖)에 `user_id`(또는 `login_id`)를 싣는다. 값은 자리표시자로만 기록하고 로그에 남기지 않는다.

## 4. 공개 v1 계약

프론트 규칙·내부 API 경계·상세 필드는 [storefront-development.md](storefront-development.md)를 먼저 읽는다.

| 용도 | 서버 SDK/REST 경로 | 응답 |
|---|---|---|
| 상점 정보 | `store.getStore()` → `GET /v1/store` | 상점·회원/비회원 정책 |
| 상품 목록 | `product.products({ page, limit, category_id?, keyword?, sort })` | `list/count/page/limit` |
| 공개 상품 상세 | `product.productDetail(id)` | v1이 프로젝트·노출 범위를 검증한 상세 |
| 가용성/표시 검증 | `post('cart/validate', { cart_items })` | `cart_items[].price/subtotal/is_available` — 결제 견적 토큰 아님 |
| 결제 견적 | `post('cart/order-preview', body, { headers })` | `checkout_ready/quote_token/expires_at/items/amounts/shipping_status/errors` |
| 주문 준비 | `post('orders/prepare', body, { headers })` | `order_number/url`, 비회원 `result_token/result_token_expires_at` |
| 주문 상태 | `GET /v1/orders/{order_number}` | `status/receipt_status` — 구매자 결과 API와 다른 용도 |
| 구매자 결과 | `get('orders/<order_number>/result', { headers })` | `payment_status/fulfillment_status/amounts/items/updated_at` |

정렬은 `position/-created_at/created_at/price/-price/-sold`. UI `newest/price_asc/price_desc`는 서버 값으로 바꾼다.
`commerce_calculate_price`는 로컬 추정이며 최종 금액이 아니다. 내부 invoice의 숫자 enum·`mall/*` 라우트를 복사하지 않는다.

## 5. 견적 토큰과 멱등 주문

```json
{
  "cart_items": [{ "product_id": "<product_id>", "product_option_id": "<option_id>", "quantity": 2 }],
  "shipping_address": { "zipcode": "12345" }
}
```

견적과 prepare는 같은 회원(JWT 또는 `user_id` — §3) 또는 안정적인 게스트 `Bootpay-Device-UUID`를 사용한다.
`checkout_ready === true`일 때만 토큰이 발급된다(10분). **배송지 정책** — 결제 요청(`orders/prepare`)에 배송지·우편번호는 필요 없다. 배송지와 제주·도서산간 추가비는 호스팅 주문서가 입력받아 확정한다(결제 전 배송지 반영 시 배송비·총액 재계산). 쇼핑몰(장바구니·바로 구매·결제 버튼)은 주소를 묻거나 확인하거나 배송지 등록을 요구하지 않고, 배송지 때문에 결제 요청을 막지 않는다. `cart/order-preview` 는 추가비 정책 상점에서 우편번호가 없으면 `requires_address`(토큰 없음)를 주므로, 서버가 지역 추가비가 붙지 않는 고정 내륙 우편번호로 견적한다(생성 코드 `BASE_QUOTE_ZIPCODE`) — 우편번호 없이 만든 주문과 같고 주문서에서 다시 계산된다.
참고(2026-10-01): commerce-api `order_quote_service.rb` 의 `ready` 가 `SHIPPING_CONFIRMED` 를 요구해 우편번호 없는 견적에 토큰을 주지 않는다 — 이 조건이 풀리면 고정 우편번호 없이 견적해도 된다. 생성 코드는 `checkout_ready:true` 인 `requires_address` 견적도 받는다.
`amounts:null`은 불가 상태다. 구형 `summary` 일부 합계로 대체하지 않는다. 상품+옵션 중복줄은 병합되므로 키로 대조한다.
금액은 `items[].unit_price/subtotal`과 `amounts.product_price/delivery_price/total_price`를 표시한다.

```json
{
  "quote_token": "<server_quote_token>",
  "uct": 1,
  "response_type": "url",
  "redirect_url": "https://<registered_merchant_host>/checkout/return",
  "use_auto_login": true
}
```

- `price/products`는 생략한다. 직접 보내면 견적의 상품·옵션·수량·금액과 일치해야 한다.
- `redirect_url`은 등록된 HTTPS 호스트만 허용한다. 로컬 HTTP 검증은 fixture로 하고 운영 허용으로 오해하지 않는다.
- 최초 prepare의 quote_token·본문·Idempotency-Key를 고정한다. 같은 키+같은 요청 재전송은 만료 후에도 같은 결과를 재생한다.
- 불명·timeout·처리 중에는 새 키/토큰으로 자동 생성하지 않는다. 명확한 견적 거부/만료·가격 변경은 재견적과 사용자 금액 확인 후 다음 클릭에서만 새 시도로 처리한다.
- 빈/무효 quote_token을 빼서 legacy 가격 계약으로 재시도하지 않는다. 기존 연동의 명시적 호환만 별도 유지한다.
- 회원은 `use_auto_login:true`. `/b`가 없으면 계약 오류이며 이미 만들어진 주문번호를 보존한다.
- API 반환 URL을 검사한 뒤 원문 그대로 이동한다. `__s`를 조립·로그 출력하지 않는다. [호스팅 세부](hosted-checkout-session.md).

## 6. 구매자 결과와 pending

- 회원(JWT 또는 `user_id` — §3) 또는 비회원 결과 토큰+같은 기기 UUID로 `orders/{order_number}/result`를 호출한다. 주문번호만으로 권한을 증명하지 않는다.
- 게스트 prepare의 `result_token`과 만료 시각은 서버 소유 기록에 저장한다. URL·브라우저 응답·localStorage·로그에 노출하지 않는다.
- `payment_status`: `pending/paid/partially_refunded/refunded/failed/cancelled`. paid만 완료이며 환불은 별도 표시한다.
  예전 `order/result/{id}`의 `sdk/payload.status`와 혼용하지 않는다.
- `Retry-After`를 존중한다(보통 3초, 입금 대기 60초). pending은 새 주문 생성 조건이 아니다.
- 게스트 토큰 무효는 401, 만료는 410, 회원의 다른 구매자 주문은 404다. 다른 계정이나 가맹점 권한으로 자동 우회하지 않는다.
- `commerce_get_order_status`는 재사용·만료 판단 도구이며 결과의 구매자 소유권을 증명하지 않는다. 비회원 결과는 result token 경로로 조회한다.

## 7. 서버 SDK 사용 예시

다음은 transport 예시다. 실제 BFF는 입력 검증·세션 소유 기록·동시 요청 제한·금액 확인을 포함한 생성 모듈을 사용한다.
SDK base URL에 `/v1`이 이미 있으므로 저수준 경로에 중복해서 붙이지 않는다.

```ts
import 'server-only';
import { BootpayCommerce } from '@bootpay/backend-js';

type Json = Record<string, unknown>;
const record = (value: unknown): Json =>
  value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Json : {};

export const sdkBody = (value: unknown): unknown => {
  const body = record(value);
  if (body.success === false || typeof body.error_code === 'number' || typeof body.error_code === 'string') throw new Error('Commerce request rejected');
  return body.success === true && Object.hasOwn(body, 'data') ? body.data : value;
};

export const readBuyerResult = async (
  sdk: BootpayCommerce,
  orderNumber: string,
  headers: Record<string, string>, // BFF 세션에서 만든 회원 JWT 또는 게스트 결과 토큰+기기 헤더
): Promise<Json> => {
  if (!/^[A-Za-z0-9_-]{1,128}$/.test(orderNumber)) throw new Error('Invalid order number');
  if (!headers['Bootpay-User-JWT'] && !(headers['Bootpay-Order-Result-Token'] && headers['Bootpay-Device-UUID'])) {
    throw new Error('Buyer session required');
  }
  const result = record(sdkBody(await sdk.get('orders/' + encodeURIComponent(orderNumber) + '/result', { headers })));
  if (result.order_number !== orderNumber) throw new Error('Order mismatch');
  return result; // payment_status를 검사하고 UI용 최소 데이터만 반환한다
};
```

## 8. MCP 도구·생성 코드와의 연결

- `generate_commerce_code(framework="nextjs")` 생성물은 다음 서버 모듈로 역할을 나눈다:
  `lib/commerce.ts`(`sdk`, `call`, `getStore`, `getCategories`, `getProducts`, `getProduct`, `quoteCart`, `loginCustomer`, `getCustomer`, `logoutCustomer`, `getOrderResult`),
  `lib/checkout.ts`(`trustedCheckoutUrl`, `assertAutoLoginHandoff`, `prepareOrder`, `assertCheckoutReusable`),
  `lib/checkout-ledger.ts`(`onceCheckout`, `findCheckout`, `rememberOrder`, `ownedOrder`).
- MCP 원격 회원 도구는 `user_jwt`·`user_id`·`login_id` 중 하나로 회원을 받는다(§3). 원격 MCP 는 client_key+secret_key 로 부르므로 가맹점 권한으로 회원을 지정한다 —
  쇼핑몰 서버 세션의 값만 넘긴다. users/session·password-recovery 도구는 §3 예외대로 동작한다.
- MCP `commerce_prepare_order` 는 `user_jwt` 가 있으면 `use_auto_login` 기본 `true`, 명시한 `false` 는 유지한다. `user_id` 로만 지정한 회원 주문은 자동 로그인 URL 을 만들 수 없다(§3).
  url 모드의 `true` 응답에 `/b` 가 없으면 `AUTO_LOGIN_BRIDGE_MISSING`. `idempotency_key` 는 `Idempotency-Key` 헤더로만 보내고,
  응답을 못 받으면 `order_created: "unknown"` 을 돌려준다 — 새 키로 다시 만들지 말고 같은 키로 재시도하거나 `commerce_get_order_status` 로 확인한다.
  `next_step_keys` 에는 응답에 실제로 있는 키만 담긴다. 실제 주문을 만들므로 진단만을 위해 반복 호출하지 않는다.
- 포인트·쿠폰 미리보기 도구(`commerce_preview_point_usage`·`commerce_calculate_point_limit`·`commerce_preview_coupon_discount`)는 서버 경로가 폐지되어 제거됐다.
- 관리자 설정 읽기/변경 경계(`credential_source`, `auto_setup`, `configuration_changes`)는 [SKILL.md](../SKILL.md).
- 상품 상세 본문 렌더는 [product-block-rendering.md](product-block-rendering.md), 필수 쇼핑 흐름은 [storefront-baseline.md](storefront-baseline.md).

## 9. 계약이 어긋날 때 — 문서 갱신과 gap task

1. **증거를 남긴다**: SDK 버전, 호출(메서드·경로·요청 키), HTTP status, 응답 키 목록. 값은 자리표시자로 바꾸고
   secret_key·JWT·`__s`·주문번호 원문·고객 정보는 적지 않는다.
2. **운영 데이터로 재현하지 않는다**: 주문·결제·회원 생성, 설정 변경을 진단 목적으로 실행하지 않는다. 네트워크 mock 이나 격리 환경을 쓴다.
3. **소속 저장소를 가른다**: API 동작 → `[commerce-api]`, SDK 타입·래퍼 → `[Node SDK]`, MCP 도구·생성기·가이드 → `[MCP]`. 한 task 는 한 저장소만 고친다.
4. **gap task 를 쓴다**: 요청 JSON·응답 JSON·인증·HTTP 오류·소유권·재시도 계약, 테스트 계획, 근거 파일:줄을 적는다.
   실행하지 않은 검증을 완료로 적지 않는다.
5. **생성 코드는 방어만 한다**: 형식 확인과 명확한 오류는 넣되, 없는 API 를 추측으로 구현하거나 결과를 꾸미지 않는다.
6. **같은 변경에서 문서를 맞춘다**: 계약이 바뀌면 이 문서, [SKILL.md](../SKILL.md), 대응하는 `get_doc` 내장 가이드, 생성기 테스트를 함께 고친다.
