# 가맹점 운영 API 경계 — 인증·scope·대상 회원

기준: commerce-api `docs/api/v1`·`config/api_scopes.yml` 2026-09-28 변경 이력(SEC-1·SEC-4·MI 트랙). **운영 배포 후 적용**이며,
운영 scope 동기화 전에는 등록되지 않은 scope 도 통과하므로 scope 거절이 나타나지 않을 수 있다. 문서 상태가 바뀌면 이 기준일을 함께 고친다.

MCP 에는 운영 API 도구가 없다. 에이전트가 가맹점 서버·운영 자동화 코드에서 이 API 를 직접 부를 때 이 문서를 따른다.

## 1. 먼저 가를 것 — 구매자 기능인가, 운영 기능인가

구매자 화면 기능을 운영 API 로 대신하지 않는다. 쿠폰함·적립금·구독 마이페이지처럼 로그인한 구매자 본인이 보는 화면은 구매자 API 와
회원 지정 규칙(SKILL.md 호출 구조, `contracts.md` §3)으로 만든다.

| 화면·기능 | 쓸 API | 쓰지 않을 API |
|---|---|---|
| 내 쿠폰함·쿠폰 받기 | `/v1/coupon`·`/v1/coupon/available`·`/v1/coupon/download` (구매자) | `/v1/coupons`(운영 검색) |
| 내 적립금 | `/v1/point/balance`·`/v1/point/transactions` (구매자) | `/v1/points/*`(지급·회수·소멸) |
| 내 구독 | `/v1/my-page/order-subscription*` (구매자) | `/v1/order_subscriptions`(운영 목록·양도) |
| 회원에게 쿠폰 발급·적립금 지급·구독 관리·청구서·회원 그룹 | 이 문서의 운영 API — 가맹점 서버·운영 도구에서만 | 브라우저 호출, 구매자 요청을 그대로 중계 |

운영 API 결과(다른 회원 쿠폰·전체 구독 목록 등)를 구매자 화면에 그대로 내리지 않는다.

## 2. 인증 — secret_key 서버 호출 + scope

- `Authorization: Basic base64(client_key:secret_key)`(또는 그 키로 발급한 레거시 Bearer). 스토어프론트용 공개 client_key(`Bootpay-Client-Key` 헤더)만으로는 부를 수 없다 —
  `Authorization` 이 없거나 Basic·Bearer 가 아니면 400 `TOKEN_AUTHORIZE_TYPE_INVALID`(1702).
- 조회·변경은 인증한 프로젝트 안에서만 한다. 다른 쇼핑몰의 쿠폰·템플릿·구독·카탈로그 ID 는 없는 리소스와 같은 404 다.
- 키체인 키는 API 마다 scope 를 받아 둬야 한다. supervisor 키체인이 아니면 관리자 → API 연동키 → 커머스 키에서 필요한 scope 를 부여받아야 호출할 수 있고,
  미부여면 401 `API_SCOPE_INVALID`(-47). 현재 키는 `get_commerce_keys`로 확인한다(조회 전용 — 키를 만들거나 권한을 바꾸지 않는다).
- `Bootpay-Role` 헤더를 임의로 바꾸지 않는다. SDK 기본값(`user`)을 쓴다.
- 브라우저에서 부르지 않는다. secret_key 를 쓰는 호출은 가맹점 서버·운영 도구에만 둔다.

### 2026-09-28 신규 scope 키 (31개)

| 그룹 | scope 키 |
|---|---|
| `coupon_operation` (16) | `supervisor:coupon_search`, `supervisor:coupon_detail`, `supervisor:coupon_available`, `supervisor:coupon_downloadable_for_product`, `supervisor:coupon_preview`, `supervisor:coupon_template_list`, `supervisor:coupon_template_read`, `supervisor:coupon_template_create`, `supervisor:coupon_template_update`, `supervisor:coupon_template_delete`, `supervisor:coupon_template_zone`, `supervisor:coupon_template_zone_reorder`, `supervisor:coupon_template_zone_preview`, `supervisor:coupon_template_issue`, `supervisor:coupon_policy_detail`, `supervisor:coupon_policy_update` |
| `point_operation` (3) | `supervisor:point_issue`, `supervisor:point_reclaim`, `supervisor:point_expire` |
| `user` (4) | `user:user_token`, `user:user_wallet`, `user:user_session_detail`, `user:user_session_delete` |
| `user_group` (7) | `user:user_group_delete`, `user:user_group_address_create`, `user:user_group_department_list`, `user:user_group_invitation_list`, `user:user_group_invitation_create`, `user:user_group_invitation_delete`, `user:user_group_invitation_resend` |
| `coupon` (1) | `user:coupon_subscription_preview` |

## 3. 대상 회원 — `user_id`·`as_user_id`·`new_user_id`

운영 API 의 `user_id` 는 호출한 회원이 아니라 **지급·발급·조회할 대상 회원**이다. 호출자 세션과 무관하고 세션을 바꾸지 않는다.
회원 JWT 는 쓰지 않는다(보내도 대상은 `user_id` 로 정해진다).

- 24자리면 Bootpay 회원 ID(`_id`), 그 밖의 값은 이 몰의 외부 회원 ID(`ex_uid`). 별칭 `user_ex_uid`·`user_external_uid`·`user_uid`, 로그인 아이디는 `login_id`.
- 이 몰의 회원이 아니거나(다른 몰 회원 포함) 탈퇴한 회원이면 404 `USER_NOT_FOUND`(2300). 필수인데 빠지면 400 `REQUIRED_PARAMETER_IS_MISSING`(131).
- **목록 필터도 fail-close 다.** 없는 회원을 필터로 주면 전체 목록이나 빈 목록이 아니라 404 가 온다 — 오류로 처리하고 필터 없이 다시 부르지 않는다.
- `user_id` 와 `login_id` 를 함께 보냈는데 다른 회원이면 403 `USER_NOT_MATCH`(2302).
- 값은 운영자가 고른 회원이나 가맹점 서버 데이터에서 온다. 구매자 브라우저가 보낸 회원 값을 대상 회원으로 쓰지 않는다.

```http
POST /v1/points/issue
Authorization: Basic <base64(client_key:secret_key)>
Content-Type: application/json

{"user_id": "<대상 회원 _id 또는 ex_uid>", "amount": 1000, "reason": "<지급 사유>"}
```

→ 없는 회원 404 `USER_NOT_FOUND`, 누락 400 `REQUIRED_PARAMETER_IS_MISSING`, client_key 만 400 `TOKEN_AUTHORIZE_TYPE_INVALID`, scope 없는 키체인 401 `API_SCOPE_INVALID`.
(단, 아래 §4 대로 적립금 API 는 현재 검증을 통과해도 500 이다.)

## 4. 리소스별 변경 요약 (2026-09-28)

| 리소스 | 이전 | 지금 |
|---|---|---|
| `/v1/coupons` (검색·상세·available·downloadable_for_product·preview) | 공개 client_key | Basic + `supervisor:coupon_*`, 프로젝트 범위. 대상 회원 `ex_uid` 지원, 없는 회원 404. preview 는 대상 회원의 쿠폰만 계산 |
| `/v1/coupon_templates` (CRUD·issue·zone·zone/reorder·zone/preview) | 공개 client_key, 생성 항상 500 | Basic + `supervisor:coupon_template_*`, 프로젝트 범위. `issue` 의 `user_id`·`zone/preview` 의 `as_user_id` 가 대상 회원(없으면 404, 누락 400) |
| `/v1/coupon_policies` | 공개 client_key, 항상 500 | Basic + `supervisor:coupon_policy_detail/update`. 다른 몰 템플릿 지정 404. **PUT 은 저장 후 감사 기록 단계에서 현재 500** |
| `/v1/points/issue·reclaim·expire` | 공개 client_key, 항상 500 | Basic + `supervisor:point_*`, 대상 회원 확인. **현재 검증을 통과한 요청도 500 — 수정 전에는 연동에 쓰지 않는다** |
| `/v1/sdk/coupons/manual-issue`·`/v1/sdk/coupons/:id`·`/v1/sdk/users/:user_id/coupons` | 형식 오류 500, 다른 몰 회원 발급 가능 | 대상 회원 404/400, 프로젝트의 템플릿·쿠폰만 |
| `/v1/invoices` | client_key 로 회원 대상·`use_auto_login` 청구서 생성 가능 | client_key 방식의 회원 대상·`use_auto_login` 은 400 `API_PARAM_INVALID`(`reason=merchant_auth_required`) — 서버(Basic) 호출로 옮긴다. 목록 `user_id` 를 못 찾으면 404 |
| `/v1/user-groups/**` | 로그인 ID 로도 회원 추가, 초대 항상 500 | 대상 회원은 `_id`·`ex_uid` 만(로그인 ID 동작 없어짐), scope 7종 추가. 초대 생성·삭제·재발송은 회원(JWT 또는 `user_id`) 선택, 없으면 가맹점 권한 |
| `/v1/order_subscriptions` (목록·transfer·requests·ing·charge·`:id/coupons`) | `user_id` 필터 fail-open, requests 목록 항상 404 | 필터 404, `new_user_id` 검증, requests 경로 수정, 회원을 주면 구독 소유 대조(403 `SUBSCRIPTION_DENIED`), coupons 프로젝트 범위 |
| `/v1/order-subscription-requests` | 회원 모드 항상 500 | 회원 모드는 JWT 또는 `user_id` 로 동작, 관리 모드 `user_id` 없는 회원 404 |
| `/v1/catalogs` 쓰기 | 판매자 기준 | 인증한 프로젝트 기준(같은 판매자의 다른 프로젝트도 404), `add_products` 는 넣지 못한 ID 를 `rejected_product_ids` 로 응답 |
| `/v1/admin/reviews` | 신고 목록·처리 항상 500 | 신고(`reports`)·처리(`process`) 경로 제거, 다른 몰 후기 404, `user_id` 필터는 대상 회원(없으면 404) |

- 구독 일시정지·재개는 `/v1/my-page/order-subscription/:id/pause·resume` 이 아니라 `POST /v1/order_subscriptions/requests/ing/pause`·`PUT .../requests/ing/resume` 이다(회원을 함께 보내면 소유 대조).
- **현재 500 인 경로에서 재시도하지 않는다.** 저장은 됐는데 500 이 오는 경로(쿠폰 정책 PUT 등)가 있으므로 같은 요청을 반복하면 중복 지급·중복 변경이 될 수 있다. 결과를 조회로 확인하고 commerce 수정을 기다린다.
- `POST /v1/users/wallet` 은 모델 결함으로 현재 500 이다(commerce 보류 항목).

## 5. 금지

- 공개 client_key 로 운영 API 를 부르는 코드, 브라우저에서 운영 API 를 부르는 코드를 만들지 않는다.
- `Bootpay-Role` 을 바꿔 scope 검사를 피하지 않는다.
- 구매자 쿠폰함·적립금·구독 화면을 운영 목록 API 로 만들지 않는다.
- scope 거절(401 `API_SCOPE_INVALID`)을 다른 키·다른 프로젝트로 자동 우회하지 않는다. 필요한 scope 를 사용자에게 알리고 권한 부여는 사용자가 한다.
- 예시·로그에 실제 키·회원 ID 를 남기지 않는다(자리표시자).
