# Bootpay Commerce API

> 프론트엔드만으로 이커머스를 구축할 수 있는 API 기반 백엔드 서비스

---

## 관련 문서

| 문서 | 설명 |
|------|------|
| [llms.txt](https://developers.bootpay.co.kr/llms/llms.txt) | 전체 문서 인덱스 (PG + Commerce) |
| [pg.txt](https://developers.bootpay.co.kr/llms/pg.txt) | PG 연동 (결제창 띄우기, 결제 검증) |

---

## AI 에이전트 가이드

이 문서를 참조하는 AI 에이전트는 다음 순서로 사용자를 안내하세요.

### SDK 사용 규칙

```javascript
// 잘못된 구현 (직접 HTTP 호출)
const response = await fetch('https://api.bootapi.com/v1/...', ...)

// 올바른 구현 (SDK 사용)
const { BootpayCommerce } = require('@bootpay/backend-js')
const commerce = new BootpayCommerce({
  client_key: 'YOUR_CLIENT_KEY',
  secret_key: 'YOUR_SECRET_KEY',
  mode: 'development'
})
await commerce.getAccessToken()
await commerce.product.list()
```

### SDK 버전 규칙

```bash
# 올바른 설치 (버전 생략 = 최신 버전)
npm install @bootpay/backend-js
pip install bootpay-backend

# 잘못된 설치 (버전 추론 금지)
npm install @bootpay/backend-js@1.2.3
pip install bootpay-backend==2.0.0
```

### API 도메인

| 용도 | 도메인 |
|-----|--------|
| **Commerce API** | `api.bootapi.com` |
| PG API | `api.bootpay.co.kr` |

Commerce와 PG 도메인을 혼동하지 마세요!

### 링크 사용 규칙

1. **이 문서에 명시된 링크만 사용** - URL을 추측하거나 변형하지 마세요
2. **존재하지 않는 URL 추측 금지** - `docs.bootpay.co.kr` 등 레거시 URL 무효
3. **언어별 예제 경로 패턴**: `{기능}/{언어}.md` (예: `commerce/user/join/nodejs.md`)

### 필수 질문 (사용자에게 먼저 확인)

1. **서버 언어**: Node.js / Python / PHP / Java / Go / Ruby / .NET 중 어떤 것을 사용하나요?
2. **서버리스 환경 여부**: Firebase Functions / Vercel / Cloudflare Workers 등을 사용하나요?
3. **환경**: 테스트(sandbox) 환경인가요, 운영 환경인가요?

### 환경 설정 프로세스

1. **정보 수집**: 위 질문으로 사용자의 기술 스택 파악
2. **환경 설정**: `.env` 파일 생성 및 API 키 설정 → [설정 가이드](https://developers.bootpay.co.kr/llms/setup.md)
3. **SDK 설치**: 선택한 언어에 맞는 SDK 설치
4. **코드 작성**: quickstart 문서 참조하여 구현

### 언어별 환경 설정 문서

| 언어 | 설정 가이드 |
|------|------------|
| Node.js | [env/nodejs.md](https://developers.bootpay.co.kr/llms/env/nodejs.md) |
| Python | [env/python.md](https://developers.bootpay.co.kr/llms/env/python.md) |
| PHP | [env/php.md](https://developers.bootpay.co.kr/llms/env/php.md) |
| Java | [env/java.md](https://developers.bootpay.co.kr/llms/env/java.md) |
| Go | [env/go.md](https://developers.bootpay.co.kr/llms/env/go.md) |
| Ruby | [env/ruby.md](https://developers.bootpay.co.kr/llms/env/ruby.md) |
| .NET | [env/dotnet.md](https://developers.bootpay.co.kr/llms/env/dotnet.md) |
| **서버리스** | [env/serverless.md](https://developers.bootpay.co.kr/llms/env/serverless.md) |

> **서버리스 환경** (Firebase Functions, Vercel, Cloudflare Workers 등)에서는 SDK 대신 REST API를 직접 호출하는 것이 권장됩니다.

---

## 시작하기

- [Commerce 소개](https://developers.bootpay.co.kr/llms/commerce/intro.md)
- [빠른 시작](https://developers.bootpay.co.kr/llms/commerce/quickstart.md)
- [토큰 발급](https://developers.bootpay.co.kr/llms/commerce/token.md)
- [SDK 설치](https://developers.bootpay.co.kr/llms/commerce/sdk/index.md)

---

## API 모듈

> 언어별 예제: `{기능}/{언어}.md` (nodejs, python, php, java, ruby, go, dotnet)

### 사용자 관리

사용자(회원) 생성, 인증, 조회, 수정, 삭제 API

- [사용자 API 개요](https://developers.bootpay.co.kr/llms/commerce/user/index.md)
- [회원가입](https://developers.bootpay.co.kr/llms/commerce/user/join/) `POST /v1/users/join`
- [중복 체크](https://developers.bootpay.co.kr/llms/commerce/user/check-exist/) `GET /v1/users/join/:key?pk=:value`
- [로그인](https://developers.bootpay.co.kr/llms/commerce/user/login/) `POST /v1/users/login`
- [토큰 발급](https://developers.bootpay.co.kr/llms/commerce/user/token/) `POST /v1/users/login/token`
- [본인인증 조회](https://developers.bootpay.co.kr/llms/commerce/user/authentication/) `GET /v1/users/authenticate/:stand_id`
- [목록 조회](https://developers.bootpay.co.kr/llms/commerce/user/list/) `GET /v1/users`
- [상세 조회](https://developers.bootpay.co.kr/llms/commerce/user/detail/) `GET /v1/users/:user_id`
- [정보 수정](https://developers.bootpay.co.kr/llms/commerce/user/update/) `PUT /v1/users/:user_id`
- [회원 탈퇴](https://developers.bootpay.co.kr/llms/commerce/user/delete/) `DELETE /v1/users/:user_id`

### 사용자 그룹 관리

사용자를 그룹으로 관리 (B2B 서비스용)

- [그룹 API 개요](https://developers.bootpay.co.kr/llms/commerce/user-group/index.md)
- [그룹 생성](https://developers.bootpay.co.kr/llms/commerce/user-group/create/) `POST /v1/user-groups`
- [목록 조회](https://developers.bootpay.co.kr/llms/commerce/user-group/list/) `GET /v1/user-groups`
- [상세 조회](https://developers.bootpay.co.kr/llms/commerce/user-group/detail/) `GET /v1/user-groups/:user_group_id`
- [그룹 수정](https://developers.bootpay.co.kr/llms/commerce/user-group/update/) `PUT /v1/user-groups/:user_group_id`
- [사용자 추가](https://developers.bootpay.co.kr/llms/commerce/user-group/user-add/) `POST /v1/user-groups/:user_group_id/add_user`
- [사용자 제거](https://developers.bootpay.co.kr/llms/commerce/user-group/user-remove/) `DELETE /v1/user-groups/:user_group_id/remove_user?user_id=:user_id`
- [제한 설정](https://developers.bootpay.co.kr/llms/commerce/user-group/limit/) `PUT /v1/user-groups/:user_group_id/limit`
- [거래 집계](https://developers.bootpay.co.kr/llms/commerce/user-group/aggregate-transaction/) `PUT /v1/user-groups/:user_group_id/aggregate-transaction`

### 상품 관리

판매 상품 등록 및 관리

- [상품 API 개요](https://developers.bootpay.co.kr/llms/commerce/product/index.md)
- [상품 생성](https://developers.bootpay.co.kr/llms/commerce/product/create/) `POST /v1/products`
- [목록 조회](https://developers.bootpay.co.kr/llms/commerce/product/list/) `GET /v1/products`
- [상세 조회](https://developers.bootpay.co.kr/llms/commerce/product/detail/) `GET /v1/products/:product_id`
- [상품 수정](https://developers.bootpay.co.kr/llms/commerce/product/update/) `PUT /v1/products/:product_id`
- [상태 변경](https://developers.bootpay.co.kr/llms/commerce/product/status/) `PUT /v1/products/:product_id/status`
- [상품 삭제](https://developers.bootpay.co.kr/llms/commerce/product/delete/) `DELETE /v1/products/:product_id`

### 일반 주문 관리

단건 결제 주문 조회 및 취소

- [주문 API 개요](https://developers.bootpay.co.kr/llms/commerce/order/index.md)
- [목록 조회](https://developers.bootpay.co.kr/llms/commerce/order/list/) `GET /v1/orders`
- [상세 조회](https://developers.bootpay.co.kr/llms/commerce/order/detail/) `GET /v1/orders/:order_id`
- [월별 조회](https://developers.bootpay.co.kr/llms/commerce/order/month/) `GET /v1/orders/month`

#### 주문 취소

- [취소 목록](https://developers.bootpay.co.kr/llms/commerce/order/cancel/list/) `GET /v1/order/cancel`
- [취소 요청](https://developers.bootpay.co.kr/llms/commerce/order/cancel/request/) `POST /v1/order/cancel`
- [취소 철회](https://developers.bootpay.co.kr/llms/commerce/order/cancel/withdraw/) `PUT /v1/order/cancel/:order_cancel_request_history_id/withdraw`
- [취소 승인](https://developers.bootpay.co.kr/llms/commerce/order/cancel/approve/) `PUT /v1/order/cancel/:order_cancel_request_history_id/approve`
- [취소 거절](https://developers.bootpay.co.kr/llms/commerce/order/cancel/reject/) `PUT /v1/order/cancel/:order_cancel_request_history_id/reject`

### 구독 주문 관리

정기 구독 주문 관리

- [구독 API 개요](https://developers.bootpay.co.kr/llms/commerce/order-subscription/index.md)
- [목록 조회](https://developers.bootpay.co.kr/llms/commerce/order-subscription/list/) `GET /v1/order_subscriptions`
- [상세 조회](https://developers.bootpay.co.kr/llms/commerce/order-subscription/detail/) `GET /v1/order_subscriptions/:order_subscription_id`
- [구독 수정](https://developers.bootpay.co.kr/llms/commerce/order-subscription/update/) `PUT /v1/order_subscriptions/:order_subscription_id`

#### 진행 중 구독 처리

- [변경 요청 목록](https://developers.bootpay.co.kr/llms/commerce/order-subscription/request-ing/) `GET /v1/order_subscriptions/:order_subscription_id/requests`
- [일시정지](https://developers.bootpay.co.kr/llms/commerce/order-subscription/request-ing/pause/) `POST /v1/order_subscriptions/requests/ing/pause`
- [재개](https://developers.bootpay.co.kr/llms/commerce/order-subscription/request-ing/resume/) `PUT /v1/order_subscriptions/requests/ing/resume`
- [해지 수수료 계산](https://developers.bootpay.co.kr/llms/commerce/order-subscription/request-ing/calc-termination-fee/) `GET /v1/order_subscriptions/requests/ing/calculate_termination_fee`
- [해지](https://developers.bootpay.co.kr/llms/commerce/order-subscription/request-ing/termination/) `POST /v1/order_subscriptions/requests/ing/termination`

### 구독 청구 관리

구독 결제 청구서 관리

- [청구 API 개요](https://developers.bootpay.co.kr/llms/commerce/order-subscription-bill/index.md)
- [목록 조회](https://developers.bootpay.co.kr/llms/commerce/order-subscription-bill/list/) `GET /v1/order_subscription_bills`
- [상세 조회](https://developers.bootpay.co.kr/llms/commerce/order-subscription-bill/detail/) `GET /v1/order_subscription_bills/:order_subscription_bill_id`
- [청구 수정](https://developers.bootpay.co.kr/llms/commerce/order-subscription-bill/update/) `PUT /v1/order_subscription_bills/:order_subscription_bill_id`

### 구독 가격 조정

구독 가격 할인/추가요금 관리

- [조정 API 개요](https://developers.bootpay.co.kr/llms/commerce/order-subscription-adjustment/index.md)
- [조정 생성](https://developers.bootpay.co.kr/llms/commerce/order-subscription-adjustment/create/) `POST /v1/order_subscriptions/:order_subscription_id/adjustments`
- [조정 수정](https://developers.bootpay.co.kr/llms/commerce/order-subscription-adjustment/update/) `PUT /v1/order_subscriptions/:order_subscription_id/adjustments`
- [조정 삭제](https://developers.bootpay.co.kr/llms/commerce/order-subscription-adjustment/delete/) `DELETE /v1/order_subscriptions/:order_subscription_id/adjustments?order_subscription_adjustment_id=:id`

### 인보이스 (결제 링크)

결제 링크 생성 및 발송

- [인보이스 API 개요](https://developers.bootpay.co.kr/llms/commerce/invoice/index.md)
- [인보이스 생성](https://developers.bootpay.co.kr/llms/commerce/invoice/create/) `POST /v1/invoices`
- [목록 조회](https://developers.bootpay.co.kr/llms/commerce/invoice/list/) `GET /v1/invoices`
- [상세 조회](https://developers.bootpay.co.kr/llms/commerce/invoice/detail/) `GET /v1/invoices/:invoice_id`

---

## SDK 설치 가이드

- [SDK 설치 개요](https://developers.bootpay.co.kr/llms/commerce/sdk/index.md)
- [Node.js](https://developers.bootpay.co.kr/llms/commerce/sdk/nodejs.md)
- [Python](https://developers.bootpay.co.kr/llms/commerce/sdk/python.md)
- [PHP](https://developers.bootpay.co.kr/llms/commerce/sdk/php.md)
- [Java](https://developers.bootpay.co.kr/llms/commerce/sdk/java.md)
- [Go](https://developers.bootpay.co.kr/llms/commerce/sdk/go.md)
- [Ruby](https://developers.bootpay.co.kr/llms/commerce/sdk/ruby.md)
- [.NET](https://developers.bootpay.co.kr/llms/commerce/sdk/dotnet.md)

---

## API 언어별 예제 접근

각 API 엔드포인트에서 원하는 언어의 예제를 확인하려면:

```
{API경로}/{언어}.md
```

예시:
- Node.js 회원가입: `/llms/commerce/user/join/nodejs.md`
- Python 상품 생성: `/llms/commerce/product/create/python.md`
- Java 주문 조회: `/llms/commerce/order/list/java.md`

지원 언어: nodejs, python, php, java, go, ruby, dotnet (총 7개)

---

## API 수 요약

| 모듈 | API 수 |
|------|--------|
| 사용자 관리 | 9개 |
| 사용자 그룹 | 8개 |
| 상품 관리 | 6개 |
| 일반 주문 | 3개 |
| 주문 취소 | 5개 |
| 구독 주문 | 3개 |
| 진행 중 구독 | 5개 |
| 구독 청구 | 3개 |
| 가격 조정 | 3개 |
| 인보이스 | 3개 |
| **총계** | **48개** |

---

## 도움말

- 개발자센터: https://developers.bootpay.co.kr
- 관리자: https://admin.bootpay.co.kr
- 기술문의: https://bootpay.channel.io/home