> ## 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.

# API 레퍼런스

> Headless Commerce REST API 전체 레퍼런스

# API 레퍼런스

Headless Commerce API는 REST 기반으로 설계되었습니다. JSON 요청 본문을 받고, JSON 응답을 반환하며, 표준 HTTP 메서드와 상태 코드를 사용합니다.

## Base URL

```
https://api.headlesscommerce.io/v1
```

## 두 가지 API

<CardGroup cols={2}>
  <Card title="Storefront API" icon="shop">
    `/v1/storefront/*`

    고객 대면 애플리케이션용. Publishable Key(`pk_*`) 또는 Secret Key(`sk_*`)로 접근 가능합니다.
  </Card>

  <Card title="Admin API" icon="lock">
    `/v1/admin/*`

    백오피스 관리용. Secret Key(`sk_*`)만 필요합니다.
  </Card>
</CardGroup>

## 공통 헤더

| 헤더 | 필수 | 설명 |
| - | - | - |
| `Authorization` | 예 | `Bearer <api_key>` |
| `Content-Type` | POST/PATCH 시 | `application/json` |
| `X-Customer-Token` | 조건부 | 인증된 Storefront 엔드포인트용 고객 JWT |
| `Idempotency-Key` | 권장 | 중요 POST 요청의 고유 키 |

## Rate Limiting

요청은 플랜에 따라 스토어별로 제한됩니다:

| 플랜 | 제한 |
| - | - |
| Free | 100 req/min |
| Starter | 500 req/min |
| Pro | 2,000 req/min |
| Enterprise | 커스텀 |

모든 응답에 Rate Limit 헤더가 포함됩니다:

| 헤더 | 설명 |
| - | - |
| `X-RateLimit-Limit` | 분당 최대 요청 수 |
| `X-RateLimit-Remaining` | 현재 윈도우의 잔여 요청 수 |
| `X-RateLimit-Reset` | 윈도우 리셋 Unix 타임스탬프 |

## 인터랙티브 레퍼런스

[Scalar API Reference](https://api.headlesscommerce.io/reference)에서 API를 인터랙티브하게 탐색하고 테스트할 수도 있습니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.