> ## Documentation Index
> Fetch the complete documentation index at: https://docs.headlesscommerce.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 소개
> Headless Commerce — 상품, 장바구니, 체크아웃, 주문 관리를 위한 완전한 REST API. 어떤 프레임워크로든 스토어프론트를 구축하세요.
# 직접 만들 필요 없는 커머스 백엔드
상품, 장바구니, 체크아웃, 주문, 고객, 재고 — 하나의 REST API로 모두 해결.
스토어프론트에만 집중하세요. 커머스는 저희가 처리합니다.
AI 에이전트(Claude, Cursor, ChatGPT)를 연결하여 자연어로 스토어를 관리하세요.
Storefront와 Admin API의 100개 이상의 엔드포인트를 살펴보세요.
***
## 바이브 코딩 — 이 프롬프트를 AI 에이전트에 복사하세요
```text theme={null}
당신은 Headless Commerce API를 사용하여 이커머스 애플리케이션을 개발하는 개발자입니다.
## API 개요
- Base URL: https://api.headlesscommerce.io/v1
- 인증: Authorization: Bearer {API_KEY}
- Storefront API (pk_* 키): 고객용 — 상품, 장바구니, 체크아웃, 주문
- Admin API (sk_* 키): 서버 전용 — 상품 관리, 주문, 재고, 웹훅
- 키 유형: pk_test_* (개발 프론트엔드), pk_live_* (운영 프론트엔드), sk_test_* (개발 백엔드), sk_live_* (운영 백엔드)
- sk_* 키를 클라이언트 코드에 절대 노출하지 마세요
## SDK 설치
npm install @headless-commerce/sdk # TypeScript
pip install headless-commerce # Python
## SDK 초기화
// TypeScript — Storefront (클라이언트 안전)
import { createStorefrontClient } from '@headless-commerce/sdk';
const client = createStorefrontClient({ apiKey: 'pk_test_...' });
// TypeScript — Admin (서버 전용)
import { createAdminClient } from '@headless-commerce/sdk';
const admin = createAdminClient({ apiKey: 'sk_test_...' });
# Python
from headless_commerce import HeadlessCommerce
client = HeadlessCommerce(api_key="pk_test_...")
admin = HeadlessCommerce(api_key="sk_test_...")
## 핵심 흐름: 상품 → 장바구니 → 체크아웃
1. 상품 목록: const { data } = await client.products.list({ limit: 20 })
2. 장바구니 생성: const cart = await client.carts.create({ session_id: 'guest-123' })
3. 상품 추가: await client.carts.addItem(cart.id, { variant_id: 'var_xxx', quantity: 1 })
4. 체크아웃: const order = await client.carts.checkout(cart.id, {
email: 'customer@example.com',
shipping_address: { line1: '123 Main St', city: 'Seoul', country: 'KR' },
payment_method: 'stripe' // 또는 'tosspayments', 'manual'
})
## 결제 연동
- Stripe: payment_method: 'stripe' → client_secret 반환 → 클라이언트에서 Stripe.js로 확인
- TossPayments: payment_method: 'tosspayments' → toss_payment 반환 → TossPayments Widget SDK로 확인
## 웹훅
- 생성: POST /admin/webhooks { url, events: ['order.confirmed', 'payment.completed'] }
- 검증: X-Webhook-Signature 헤더의 HMAC-SHA256 서명
- 이벤트: order.created, order.confirmed, order.completed, order.cancelled, payment.completed, payment.failed, payment.refunded, product.created, product.updated, product.deleted, fulfillment.created, fulfillment.shipped, fulfillment.delivered, inventory.low, inventory.out_of_stock, customer.created
## 고객 인증
- 서버에서 JWT 생성: POST /admin/customers/{id}/token → { token, expires_at }
- 클라이언트 전달: X-Customer-Token: {jwt} + Authorization: Bearer pk_*
- 비회원 장바구니: session_id로 생성, 로그인 후 POST /carts/{id}/merge로 병합
## 주요 패턴
- 페이지네이션: 커서 기반, limit (1-100, 기본값 20) 및 starting_after 사용
- 에러: JSON { error: { type, code, message, details } } + 표준 HTTP 상태 코드
- 멱등성: 체크아웃/결제/환불 POST에 Idempotency-Key 헤더 (UUID), 24시간 캐시
## MCP 서버 (AI 에이전트 직접 연결)
URL: https://mcp.headlesscommerce.io/mcp
헤더: Authorization: Bearer sk_live_your_key
지원: 상품, 주문, 고객, 재고, 할인, 풀필먼트, 장바구니, 웹훅, 리전, 배송, 반품, 환불, 스토어 설정, 대시보드 통계
## 전체 API 문서: https://docs.headlesscommerce.io
## API 레퍼런스: https://docs.headlesscommerce.io/api-reference/introduction
이 컨텍스트를 활용하여 사용자가 요청하는 것을 구현하세요. 깔끔하고 프로덕션에 바로 사용할 수 있는 코드를 작성하세요.
```
***
## 플랫폼 한눈에 보기
Storefront & Admin **API 엔드포인트**
**거래 수수료** — 매출을 온전히 가져가세요
글로벌 **API 응답 시간** 중앙값
유료 플랜 **업타임 SLA**
***
## 60초 만에 개발 시작
1. [대시보드](https://app.headlesscommerce.io)에 로그인하세요
2. **설정 > API 키**로 이동하세요
3. **API 키 생성**을 클릭하세요
| 키 접두사 | 유형 | 용도 |
| - | - | - |
| `pk_test_*` | Publishable / Test | 개발용 프론트엔드 (브라우저에 노출해도 안전) |
| `pk_live_*` | Publishable / Live | 운영용 프론트엔드 |
| `sk_test_*` | Secret / Test | 개발용 백엔드 / 관리자 |
| `sk_live_*` | Secret / Live | 운영용 백엔드 / 관리자 |
시크릿 키(`sk_*`)를 클라이언트 코드에 절대 노출하지 마세요. 브라우저 및 모바일 애플리케이션에는 퍼블리셔블 키를 사용하세요.
```bash npm theme={null}
npm install @headless-commerce/sdk
```
```bash pnpm theme={null}
pnpm add @headless-commerce/sdk
```
```bash yarn theme={null}
yarn add @headless-commerce/sdk
```
```bash pip theme={null}
pip install headless-commerce
```
```bash poetry theme={null}
poetry add headless-commerce
```
```bash uv theme={null}
uv add headless-commerce
```
환경 변수를 설정하세요:
```bash .env theme={null}
# Storefront (클라이언트 안전)
NEXT_PUBLIC_HC_API_KEY=pk_test_...
# Admin (서버 전용)
HC_SECRET_KEY=sk_test_...
```
```typescript theme={null}
import { createStorefrontClient } from '@headless-commerce/sdk';
const client = createStorefrontClient({
apiKey: process.env.NEXT_PUBLIC_HC_API_KEY!,
// 기본적으로 https://api.headlesscommerce.io/v1 에 연결됩니다
});
```
관리자 작업에는 서버 측에서 시크릿 키를 사용하세요:
```typescript theme={null}
import { createAdminClient } from '@headless-commerce/sdk';
const admin = createAdminClient({
apiKey: process.env.HC_SECRET_KEY!,
});
```
```python theme={null}
from headless_commerce import HeadlessCommerce
# Storefront 클라이언트
client = HeadlessCommerce(api_key="pk_test_...")
# Admin 클라이언트
admin = HeadlessCommerce(api_key="sk_test_...")
```
또는 컨텍스트 매니저를 사용하여 자동으로 정리할 수 있습니다:
```python theme={null}
with HeadlessCommerce(api_key="sk_test_...") as admin:
products = admin.products.list()
```
**상품 목록 조회**
```typescript TypeScript theme={null}
const { data: products } = await client.products.list({ limit: 10 });
console.log(products);
```
```python Python theme={null}
products = client.products.list(limit=10)
print(products)
```
```bash cURL theme={null}
curl https://api.headlesscommerce.io/v1/storefront/products \
-H "Authorization: Bearer pk_test_your_key_here"
```
```json 응답 예시 theme={null}
{
"data": [
{
"id": "prod_abc123",
"name": "Classic T-Shirt",
"status": "active",
"type": "physical",
"variants": [
{ "id": "var_xxx", "name": "M / Black", "price": 2900 }
]
}
],
"has_more": false,
"next_cursor": null
}
```
**장바구니 생성**
```typescript TypeScript theme={null}
const cart = await client.carts.create({
session_id: 'guest-session-123',
});
console.log(cart.id); // cart_xxxxxxxx
```
```python Python theme={null}
cart = client.carts.create(session_id="guest-session-123")
print(cart["id"]) # cart_xxxxxxxx
```
```bash cURL theme={null}
curl -X POST https://api.headlesscommerce.io/v1/storefront/carts \
-H "Authorization: Bearer pk_test_your_key_here" \
-H "Content-Type: application/json" \
-d '{"session_id": "guest-session-123"}'
```
**상품 추가**
```typescript TypeScript theme={null}
await client.carts.addItem(cart.id, {
variant_id: products[0].variants[0].id,
quantity: 1,
});
```
```python Python theme={null}
client.carts.add_item(cart["id"], variant_id=products[0]["variants"][0]["id"], quantity=1)
```
```bash cURL theme={null}
curl -X POST https://api.headlesscommerce.io/v1/storefront/carts/{cart_id}/items \
-H "Authorization: Bearer pk_test_your_key_here" \
-H "Content-Type: application/json" \
-d '{"variant_id": "var_xxx", "quantity": 1}'
```
**체크아웃**
```typescript Stripe theme={null}
const order = await client.carts.checkout(cart.id, {
email: 'customer@example.com',
shipping_address: { line1: '123 Main St', city: 'Seoul', country: 'KR' },
payment_method: 'stripe',
});
// order.payment.client_secret을 Stripe.js와 함께 사용하여 결제를 완료하세요
console.log(order.payment.client_secret);
```
```typescript TossPayments theme={null}
const order = await client.carts.checkout(cart.id, {
email: 'customer@example.com',
shipping_address: { line1: '123 Main St', city: 'Seoul', country: 'KR' },
payment_method: 'tosspayments',
});
// order.toss_payment를 TossPayments SDK와 함께 사용하여 결제 UI를 표시하세요
const { order_id, order_name, amount } = order.toss_payment;
// 사용자가 TossPayments UI에서 결제를 완료한 후, 서버 측에서 확인하세요:
await client.payments.confirm({
payment_key: paymentKey, // TossPayments SDK 콜백에서 받은 값
order_id,
amount,
});
```
```bash cURL theme={null}
curl -X POST https://api.headlesscommerce.io/v1/storefront/carts/{cart_id}/checkout \
-H "Authorization: Bearer pk_test_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"email": "customer@example.com",
"payment_provider": "stripe",
"payment_method_id": "pm_xxx"
}'
```
이게 전부입니다 — 상품 탐색부터 주문 완료까지 네 단계면 충분합니다.
***
## 개발자를 위해 설계됨
고객용 앱을 위한 **Storefront API** (Publishable Key).
백오피스 관리를 위한 **Admin API** (Secret Key).
동일한 Base URL, 다른 권한 범위.
완전한 자동완성을 지원하는 TypeScript SDK.
`@headless-commerce/sdk`를 설치하고 타입 안전하게 바로 개발을 시작하세요.
주문 생성, 결제 완료, 재고 변동 등 실시간 이벤트를 구독하세요.
폴링 없이 반응형 워크플로우를 구축할 수 있습니다.
상품, 주문, 고객, 재고를 관리할 수 있는 완전한 관리자 대시보드가 포함되어 있습니다 — 별도 설정 불필요.
Claude 같은 AI 어시스턴트에 스토어를 연결하세요. 자연어로 상품, 주문, 재고를 관리할 수 있습니다.
Stripe와 토스페이먼츠 내장 지원. 플랫폼 수수료 없이 글로벌 결제를 받으세요.
***
## 제공 기능
| 도메인 | Storefront API | Admin API |
| - | :-: | :-: |
| 상품 & 옵션 | 조회 | 전체 CRUD |
| 카테고리 & 컬렉션 | 조회 | 전체 CRUD |
| 장바구니 & 체크아웃 | 전체 | — |
| 주문 & 반품 | 본인 조회 | 전체 관리 |
| 고객 & 주소 | 셀프서비스 | 전체 CRUD |
| 재고 | — | 전체 관리 |
| 할인 | 장바구니 적용 | 전체 CRUD |
| 웹훅 | — | 전체 CRUD |
| 결제 (Stripe, Toss) | 확인 | 완료 처리 |
| 리전 & 다국어 | 조회 | 전체 CRUD |
| CSV 가져오기/내보내기 | — | 전체 |
***
## 어떤 프레임워크든 OK
이미 사용 중인 도구로 스토어프론트를 구축하세요. Headless Commerce는 순수 API — 프론트엔드에 대한 제약이 없습니다.
React Server Components, App Router, SSR/SSG — 모두 지원됩니다.
Loaders, actions, 중첩 라우트 — 어디서든 Headless Commerce를 호출하세요.
SDK를 통한 완전한 TypeScript 지원으로 Vue 3 컴포저블을 사용하세요.
Svelte, Astro, 모바일 앱, 또는 순수 REST — HTTP만 되면 연동됩니다.
***
## 다음 단계
AI 에이전트를 연결하여 자연어로 스토어를 관리하세요.
TypeScript 및 Python SDK 레퍼런스 — 모든 리소스와 메서드를 확인하세요.
JWT 토큰, 비회원 장바구니, 고객 신원 확인.
Storefront와 Admin API의 100개 이상의 REST 엔드포인트를 살펴보세요.
신용카드 불필요. 테스트 모드에서 전체 API 접근 가능.
심플하고 예측 가능한 요금. 거래 수수료 0%.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.